From 176bb5626b4c17cc00fe6772b4b8f44d8d2d5f2c Mon Sep 17 00:00:00 2001 From: Patrick Russell Date: Thu, 26 Mar 2026 10:57:47 -0700 Subject: [PATCH 1/3] Add TypeScript runtime actions documentation App Builder supports TypeScript for runtime actions via Webpack's ts-loader, but this capability was essentially undiscovered because it was not documented in the public docs. This change adds a dedicated guide and cross-links it from existing configuration pages. Changes: - New page: typescript-actions.md covering prerequisites, setup, limitations, and ESM project considerations - webpack-configuration.md: add .cjs extension support (addresses #497) and TypeScript cross-reference - configuration.md: note that function field supports .ts files, add TypeScript Actions to "Learn more" list - index.md: add TypeScript Actions link under Configuration section References: - https://github.com/adobe/aio-cli-plugin-app-dev#typescript-support - https://github.com/AdobeDocs/app-builder/issues/497 Made-with: Cursor --- .../configuration/configuration.md | 3 + .../configuration/typescript-actions.md | 97 +++++++++++++++++++ .../configuration/webpack-configuration.md | 13 +-- src/pages/guides/app_builder_guides/index.md | 1 + 4 files changed, 108 insertions(+), 6 deletions(-) create mode 100644 src/pages/guides/app_builder_guides/configuration/typescript-actions.md diff --git a/src/pages/guides/app_builder_guides/configuration/configuration.md b/src/pages/guides/app_builder_guides/configuration/configuration.md index 82e72bbe2..b79d59329 100644 --- a/src/pages/guides/app_builder_guides/configuration/configuration.md +++ b/src/pages/guides/app_builder_guides/configuration/configuration.md @@ -140,6 +140,8 @@ runtimeManifest: - ["myfilestoinclude/*.txt", "text/"] ``` +> Note: the `function` field can also point to TypeScript files (e.g., `index.ts`) when a Webpack configuration with `ts-loader` is present. See [TypeScript Actions](typescript-actions.md) for setup details. + > Note: the example above demonstrates the 'include' field of an action, for cases when you may want to have a file deployed with your action code and available to your code while it runs. > The example copies all .txt files from the `myfilestoinclude/` directory and places them in a new dir `text/` available when your action is invoked via `fs.readFile('text/somefile.txt', 'utf8', callback);` @@ -424,5 +426,6 @@ If you can't view your application in the App Builder Catalog of Adobe Experienc Learn more about: - [Configuring Sequences](sequences.md) - Chain actions together declaratively - [Webpack Configuration](webpack-configuration.md) - Customize your build process +- [TypeScript Actions](typescript-actions.md) - Use TypeScript in your Runtime actions Return to [Guides Index](../../index.md). diff --git a/src/pages/guides/app_builder_guides/configuration/typescript-actions.md b/src/pages/guides/app_builder_guides/configuration/typescript-actions.md new file mode 100644 index 000000000..c5712adf3 --- /dev/null +++ b/src/pages/guides/app_builder_guides/configuration/typescript-actions.md @@ -0,0 +1,97 @@ +--- +title: TypeScript Actions +description: >- + Use TypeScript to write Runtime actions in App Builder applications. +keywords: + - TypeScript + - Runtime Actions + - Webpack + - Configuration +--- + +# TypeScript Actions + +## Overview + +App Builder supports TypeScript for Runtime actions via Webpack's `ts-loader`. You can point your `app.config.yaml` directly to `.ts` files — no manual `tsc` compilation step or duplicated source directories required. This works with `aio app dev`, `aio app build`, and `aio app deploy`. + +## Prerequisites + +Install the required dev dependencies in your project: + +```bash +npm install --save-dev ts-loader typescript +``` + +## Setup + +### 1. Add a Webpack configuration + +Create a `webpack-config.js` file in the root of your project (or in an action directory for per-action configuration). See [Webpack Configuration](webpack-configuration.md) for details on file placement and supported export formats. + +```javascript +module.exports = { + devtool: 'inline-source-map', + module: { + rules: [ + { + test: /\.ts?$/, + exclude: /node_modules/, + use: 'ts-loader' + } + ] + } +} +``` + +> If your project uses ES modules (`"type": "module"` in `package.json`), name this file `webpack-config.cjs` instead so that it is treated as CommonJS. See the [ES module syntax](webpack-configuration.md#es-module-syntax) section for more information. + +### 2. Add a TypeScript configuration + +Create a `tsconfig.json` file in the root of your project: + +```json +{ + "exclude": ["node_modules", "dist"], + "compilerOptions": { + "target": "ES6", + "module": "ES6", + "sourceMap": true + } +} +``` + +### 3. Point your actions to `.ts` files + +In `app.config.yaml`, set the `function` field of your action to the TypeScript entry file: + +```yaml +runtimeManifest: + packages: + my-package: + actions: + my-action: + function: actions/my-action/index.ts + web: 'yes' + runtime: nodejs:18 +``` + +That's it. App Builder will use Webpack with `ts-loader` to compile your TypeScript action during build and deployment. + +## Limitations + +- **CommonJS output only** — Runtime actions must produce CommonJS modules. App Builder enforces this automatically (`output.libraryTarget` defaults to `commonjs2`), so no extra configuration is needed. +- **Webpack config must be CommonJS** — The webpack configuration file must use CommonJS syntax (`.js` or `.cjs`). ES module syntax (`.mjs`) is not supported. +- **Immutable Webpack options** — You cannot override `target`, `output.path`, or `output.filename` in your webpack configuration. See [Immutable options](webpack-configuration.md#immutable-options) for details. +- **Debugging** — The VS Code debugger steps through the compiled JavaScript output by default. Adding `devtool: 'inline-source-map'` to your webpack configuration (as shown above) enables source map support, which improves the debugging experience but may not be a perfect 1:1 mapping with your original TypeScript source. + +## Example project + +The [typescript-app quickstart](https://github.com/adobe/appbuilder-quickstarts/tree/master/typescript-app) provides a complete working example. + +## Next steps + +- [Webpack Configuration](webpack-configuration.md) — Customize your build process +- [App Builder Configuration Files](configuration.md) — Full `app.config.yaml` reference + +Return to [Guides Index](../../index.md). diff --git a/src/pages/guides/app_builder_guides/configuration/webpack-configuration.md b/src/pages/guides/app_builder_guides/configuration/webpack-configuration.md index 9d3b7cbcb..5d414124e 100644 --- a/src/pages/guides/app_builder_guides/configuration/webpack-configuration.md +++ b/src/pages/guides/app_builder_guides/configuration/webpack-configuration.md @@ -17,18 +17,18 @@ App Builder bundles Runtime action code using Webpack. Users can specify Webpack ## Configuration file -When Runtime action code is bundled during `aio app build|run|deploy` the action directory is searched for a webpack config file named `*webpack-config.js`. The search is done first in the directory of the action being built, then the parent directory, up to the project root. +When Runtime action code is bundled during `aio app build|run|deploy` the action directory is searched for a webpack config file named `*webpack-config.js` or `*webpack-config.cjs`. The search is done first in the directory of the action being built, then the parent directory, up to the project root. -- To specify a Webpack configuration for a single action, place the `*webpack-config.js` file in the action folder. +- To specify a Webpack configuration for a single action, place the config file in the action folder. -- To specify a Webpack configuration for a set of actions, place the `*webpack-config.js` file in the parent directory of your action +- To specify a Webpack configuration for a set of actions, place the config file in the parent directory of your action folders. -- To specify a Webpack configuration for an entire project, place the `*webpack-config.js` file in the root directory of your project. +- To specify a Webpack configuration for an entire project, place the config file in the root directory of your project. ### ES module syntax -App Builder does not currently support ES Module syntax. This file must be written in CommonJS, or failures will occur at build time. +The webpack config file must be written in CommonJS, or failures will occur at build time. If your project uses ES modules (`"type": "module"` in `package.json`), name the file `*webpack-config.cjs` so that Node.js treats it as CommonJS. ## Configuration types @@ -208,6 +208,7 @@ module.exports = (env) => ({ ## Next steps -Return to [Configuration](configuration.md). +- [TypeScript Actions](typescript-actions.md) — Use TypeScript in your Runtime actions +- [Configuration](configuration.md) — Full `app.config.yaml` reference Return to [Guides Index](../../index.md). diff --git a/src/pages/guides/app_builder_guides/index.md b/src/pages/guides/app_builder_guides/index.md index 7e707a115..da166c9e9 100644 --- a/src/pages/guides/app_builder_guides/index.md +++ b/src/pages/guides/app_builder_guides/index.md @@ -23,6 +23,7 @@ Welcome to the App Builder Guides section. Here you'll find comprehensive docume ## Configuration and Deployment * [Configuration](configuration/configuration.md) +* [TypeScript Actions](configuration/typescript-actions.md) * [Deployment](deployment/deployment.md) * [Content Delivery Network](cdn/index.md) * [Application Logging](application_logging/logging.md) From e1a3b72f9d0b4f3684c7778aee1e6e469e527350 Mon Sep 17 00:00:00 2001 From: Patrick Russell Date: Thu, 26 Mar 2026 11:19:28 -0700 Subject: [PATCH 2/3] Add TypeScript Actions to site navigation config Add the new TypeScript Actions page as a sub-item under Configuration in src/pages/config.md so it appears in the site sidebar navigation. Made-with: Cursor --- src/pages/config.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/config.md b/src/pages/config.md index 395c47cd8..0a57cf24b 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -48,6 +48,7 @@ - [CDN](guides/app_builder_guides/cdn/index.md) - [Configuration](guides/app_builder_guides/configuration/configuration.md) - [Sequences](guides/app_builder_guides/configuration/sequences.md) + - [TypeScript Actions](guides/app_builder_guides/configuration/typescript-actions.md) - [Webpack Configuration](guides/app_builder_guides/configuration/webpack-configuration.md) - [Deployment](guides/app_builder_guides/deployment/deployment.md) - [CI/CD overview](guides/app_builder_guides/deployment/cicd-for-app-builder-apps.md) From cbb1dd605d7cbc938dca011c6f9d0d26de03a709 Mon Sep 17 00:00:00 2001 From: Patrick Russell Date: Thu, 26 Mar 2026 11:36:44 -0700 Subject: [PATCH 3/3] Address PR review feedback on typescript-actions.md - Trim Limitations section to only the TypeScript-specific debugging note; link to webpack-configuration.md for general webpack constraints - Clarify that the typescript-app quickstart uses the older manual tsc approach, and that the ts-loader method on this page is simpler Made-with: Cursor --- .../app_builder_guides/configuration/typescript-actions.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/pages/guides/app_builder_guides/configuration/typescript-actions.md b/src/pages/guides/app_builder_guides/configuration/typescript-actions.md index c5712adf3..83cda8d9f 100644 --- a/src/pages/guides/app_builder_guides/configuration/typescript-actions.md +++ b/src/pages/guides/app_builder_guides/configuration/typescript-actions.md @@ -80,14 +80,13 @@ That's it. App Builder will use Webpack with `ts-loader` to compile your TypeScr ## Limitations -- **CommonJS output only** — Runtime actions must produce CommonJS modules. App Builder enforces this automatically (`output.libraryTarget` defaults to `commonjs2`), so no extra configuration is needed. -- **Webpack config must be CommonJS** — The webpack configuration file must use CommonJS syntax (`.js` or `.cjs`). ES module syntax (`.mjs`) is not supported. -- **Immutable Webpack options** — You cannot override `target`, `output.path`, or `output.filename` in your webpack configuration. See [Immutable options](webpack-configuration.md#immutable-options) for details. - **Debugging** — The VS Code debugger steps through the compiled JavaScript output by default. Adding `devtool: 'inline-source-map'` to your webpack configuration (as shown above) enables source map support, which improves the debugging experience but may not be a perfect 1:1 mapping with your original TypeScript source. +For general Webpack constraints (immutable options, supported config formats, etc.), see [Webpack Configuration](webpack-configuration.md). + ## Example project -The [typescript-app quickstart](https://github.com/adobe/appbuilder-quickstarts/tree/master/typescript-app) provides a complete working example. +The [typescript-app quickstart](https://github.com/adobe/appbuilder-quickstarts/tree/master/typescript-app) demonstrates TypeScript in an App Builder project. Note that it uses a manual `tsc` compilation approach; the `ts-loader` method described on this page is a simpler alternative that avoids the need for a separate build step or duplicated source directories. ## Next steps