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) 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..83cda8d9f --- /dev/null +++ b/src/pages/guides/app_builder_guides/configuration/typescript-actions.md @@ -0,0 +1,96 @@ +--- +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 + +- **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) 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 + +- [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)