> ## Documentation Index > Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt > Use this file to discover all available pages before exploring further. # prepareConfig API reference for the prepareConfig method. Note: Most apps never need this, `dev`, `build`, and `extractTranslations` already run it internally. Call it only when building custom tooling. See [Canva App Scripts](https://www.canva.dev/docs/apps/canva-app-scripts/) for the CLI-first workflow. Runs the config-preparation pipeline every command shares: load `canva-app.config.{ts,…}` (or the file named by `options.configFile`), apply `options.overrides` on top, **overrides > env > config file > default**, then validate the result for `command`. import("./dev.ts").dev, import("./build.ts").build, and import("./extract\_translations.ts").extractTranslations already run this internally. Call it directly only when building tooling that needs the same resolution and validation ahead of, or independent from, invoking one of those verbs. ## Usage ### Basic config preparation ```typescript import { prepareConfig } from '@canva/app-scripts'; const { config, configPath } = await prepareConfig("build"); console.log(`Loaded config from ${configPath}`); console.log(`Build will run on: ${config.entry}`); ``` ### Config preparation with a custom config file and overrides ```typescript import { prepareConfig } from '@canva/app-scripts'; const { config, configPath } = await prepareConfig("dev", { configFile: './.configs/canva-app.config.ts', overrides: { devServer: { port: 3000 } }, }); console.log(`Loaded config from ${configPath}`); console.log(`Dev server will run on port: ${config.devServer.port}`); ``` ## Parameters Which commands's validation rules to apply **Available values**: * `"dev"` * `"build"` * `"extractTranslation"` Configuration overrides and config-file selection Properties of options}> Explicit config file, resolved against `rootDir`; must exist. Unset runs the default `canva-app.config.{ts,…}` discovery at the project root, falling back to package defaults when nothing is found. Configuration overrides, merged over the loaded config file as the top precedence tier: **overrides > env > config file > default**. Rsbuild-specific app configuration. This is the configuration for apps using Rsbuild as the bundler. The `bundler` property is optional since Rsbuild is the default. Entry point for the app (default: 'src/index.tsx') Root directory of the project (default: process.cwd()) Build output directory, relative to `rootDir`. `build` writes artefacts here. Bundler-tier output concerns (filename, chunking) are reachable through the bundler escape hatch, not this field. **Default** ```ts "dist" ``` Optional dev-server options (frontend port, HTTPS, public tunnel). CLI flags and env vars override these at run time. Properties of devServer}> Frontend dev-server port. Overridden by `--override-frontend-port` and the `CANVA_FRONTEND_PORT` env var. **Default** ```ts 8080 ``` Serve the frontend over HTTPS using locally-managed certificates. Overridden by `--use-https`. **Default** ```ts false ``` Optional backend run alongside the dev server. When enabled, `dev` spawns the backend entry under `nodemon` with TypeScript support, passes SSL certificate paths through to its environment, and ties its lifecycle to the dev server — a backend crash tears the whole process down. Apps without a backend simply omit this field. Use `true` (or any backend config, even `{}`) to run the backend at the default location `backend/server.ts`; set `entry` to point elsewhere. **Examples** **Default backend location** ```typescript export default defineConfig({ entry: "./src/index.tsx", backend: true, // runs backend/server.ts }); ``` **Custom entry and port** ```typescript export default defineConfig({ entry: "./src/index.tsx", backend: { entry: "./api/main.ts", port: 3100 }, }); ``` Backend options for the dev server. In `canva-app.config.ts`, any backend config (even an empty object) enables the backend; omit the `backend` field entirely to run frontend-only. As a command override, an object without `entry` only patches fields — `true` or `{ entry }` opts into a run. Path to the backend entry script, relative to `rootDir`, falls back to the package default when unset. **Default** ```ts "backend/server.ts" ``` Port the backend listens on, used to build `DevServer.backend.url`. Falls back to `CANVA_BACKEND_PORT` then the package default when unset. **Default** ```ts 3001 ``` Backend host the built app calls. Falls back to `CANVA_BACKEND_HOST` when unset. Expose the backend through a public HTTPS tunnel so third-party services (OAuth providers, webhook callbacks) can reach it during local development. Overridden by `--tunnel`. Requires a tunnel authtoken in env. **See** [https://github.com/canva-sdks/canva-apps-sdk-starter-kit/blob/main/templates/hello\_world/README.md#configure-ngrok-optional](https://github.com/canva-sdks/canva-apps-sdk-starter-kit/blob/main/templates/hello_world/README.md#configure-ngrok-optional) **Default** ```ts false ``` Optional configuration for `extractTranslations`. Properties of extractTranslations}> Directory to write extracted messages into (default: 'dist'). Output filename written into `outputDir` (default: 'messages\_en.json'). Must be a bare filename — no directory segments; use `outputDir` for that. Glob for source files to scan (default: `src/**/*.{ts,tsx}`). The bundler to use for building the app. Defaults to 'rsbuild' if not specified. The only valid value is `"rsbuild"`. Customize the Rsbuild configuration. Receives the base config and context, returns modified config. **Example: Registering an Rsbuild plugin** ```typescript export default defineConfig({ config: (rsbuildConfig, { mode }) => { rsbuildConfig.plugins?.push(myPlugin()); return rsbuildConfig; }, }); ``` **Parameters** Context passed to the Rsbuild customization function. Mirrors `WebpackContext`'s `{ mode }` shape for symmetry across adapters. Properties of context}> Whether this is a development or production build. **Available values**: * `"production"` * `"development"` **Returns** Webpack-specific app configuration. The `bundler` property is required: Rsbuild is the package default, so webpack is always an explicit opt-in. The bundler to use for building the app. The only valid value is `"webpack"`. Entry point for the app (default: 'src/index.tsx') Root directory of the project (default: process.cwd()) Build output directory, relative to `rootDir`. `build` writes artefacts here. Bundler-tier output concerns (filename, chunking) are reachable through the bundler escape hatch, not this field. **Default** ```ts "dist" ``` Optional dev-server options (frontend port, HTTPS, public tunnel). CLI flags and env vars override these at run time. Properties of devServer}> Frontend dev-server port. Overridden by `--override-frontend-port` and the `CANVA_FRONTEND_PORT` env var. **Default** ```ts 8080 ``` Serve the frontend over HTTPS using locally-managed certificates. Overridden by `--use-https`. **Default** ```ts false ``` Optional backend run alongside the dev server. When enabled, `dev` spawns the backend entry under `nodemon` with TypeScript support, passes SSL certificate paths through to its environment, and ties its lifecycle to the dev server — a backend crash tears the whole process down. Apps without a backend simply omit this field. Use `true` (or any backend config, even `{}`) to run the backend at the default location `backend/server.ts`; set `entry` to point elsewhere. **Examples** **Default backend location** ```typescript export default defineConfig({ entry: "./src/index.tsx", backend: true, // runs backend/server.ts }); ``` **Custom entry and port** ```typescript export default defineConfig({ entry: "./src/index.tsx", backend: { entry: "./api/main.ts", port: 3100 }, }); ``` Backend options for the dev server. In `canva-app.config.ts`, any backend config (even an empty object) enables the backend; omit the `backend` field entirely to run frontend-only. As a command override, an object without `entry` only patches fields — `true` or `{ entry }` opts into a run. Path to the backend entry script, relative to `rootDir`, falls back to the package default when unset. **Default** ```ts "backend/server.ts" ``` Port the backend listens on, used to build `DevServer.backend.url`. Falls back to `CANVA_BACKEND_PORT` then the package default when unset. **Default** ```ts 3001 ``` Backend host the built app calls. Falls back to `CANVA_BACKEND_HOST` when unset. Expose the backend through a public HTTPS tunnel so third-party services (OAuth providers, webhook callbacks) can reach it during local development. Overridden by `--tunnel`. Requires a tunnel authtoken in env. **See** [https://github.com/canva-sdks/canva-apps-sdk-starter-kit/blob/main/templates/hello\_world/README.md#configure-ngrok-optional](https://github.com/canva-sdks/canva-apps-sdk-starter-kit/blob/main/templates/hello_world/README.md#configure-ngrok-optional) **Default** ```ts false ``` Optional configuration for `extractTranslations`. Properties of extractTranslations}> Directory to write extracted messages into (default: 'dist'). Output filename written into `outputDir` (default: 'messages\_en.json'). Must be a bare filename — no directory segments; use `outputDir` for that. Glob for source files to scan (default: `src/**/*.{ts,tsx}`). Customize the webpack configuration. Receives the base config and context, returns modified config. **Example: Registering a webpack plugin** ```typescript export default defineConfig({ bundler: 'webpack', config: (webpackConfig, { mode }) => { webpackConfig.plugins?.push(new MyPlugin()); return webpackConfig; }, }); ``` **Parameters** Context passed to the webpack customization function. Shaped to match `argv.mode` from webpack's own CLI convention. Other bundler adapters mirror the same `{ mode }` shape for symmetry. Properties of context}> Whether this is a development or production build. **Available values**: * `"production"` * `"development"` **Returns** ## Returns The prepared config, its source file path, and any notices. This is a `Promise` that resolves with the following object: The fully-resolved config the engine consumes. Properties of config}> The resolved bundler, defaulting to Rsbuild. **Available values**: * `"rsbuild"` * `"webpack"` Resolved frontend entry, relative to `rootDir` (or absolute), defaulting to `src/index.tsx`; `validateConfig` checks it exists. Resolved project root, defaulting to `process.cwd()`. Resolved build output directory, relative to `rootDir` (or absolute), defaulting to `dist`. Consumers absolutize against `rootDir`. Resolved static assets directory, relative to `rootDir` (or absolute), defaulting to `assets`. Consumers absolutize against `rootDir`. Local development only, not recommended for production builds — imported assets bundle directly into `app.js`, and apps have a 5MB submission size limit. Not part of the `canva-app.config.ts` schema (unlike `outputDir`); set via the `CANVA_ASSETS_DIR` env var, for tooling like the starter-kit's `examples/` runner, which shares one asset directory across many apps. Resolved `extractTranslations` options, all fields defaulted. Properties of extractTranslations}> Elaborated dev-server options (the internal superset of the public DevServerOptions, adding HMR, app origin, and SSL cert paths). Port, HTTPS, and HMR are always resolved. Properties of devServer}> Options for SSL certificate generation. Directory to store SSL certificates (default: `.ssl` in rootDir) Root directory of the project (default: `process.cwd()`) Open browser on start App origin URL for HMR CORS configuration Pre-generated SSL certificate paths (avoids regeneration) Properties of ssl}> Path to the SSL certificate file Path to the SSL private key file The app's identity from `CANVA_APP_ID`, captured by `resolveConfig` so validation stays env-free. Required when a backend runs in dev. Customize the selected bundler's configuration Function to customize webpack configuration. Receives the base config and returns a modified version. **Example: Conditional plugin by mode** ```typescript config: (webpackConfig, { mode }) => { if (mode === "production") { webpackConfig.plugins?.push(new MyPlugin()); } return webpackConfig; } ``` **Parameters** Context passed to the webpack customization function. Shaped to match `argv.mode` from webpack's own CLI convention. Other bundler adapters mirror the same `{ mode }` shape for symmetry. Properties of context}> Whether this is a development or production build. **Available values**: * `"production"` * `"development"` **Returns** Function to customize the Rsbuild configuration. Receives the base config and returns a modified version. **Example: Conditional plugin by mode** ```typescript config: (rsbuildConfig, { mode }) => { if (mode === "production") { rsbuildConfig.plugins?.push(myPlugin()); } return rsbuildConfig; } ``` **Parameters** Context passed to the Rsbuild customization function. Mirrors `WebpackContext`'s `{ mode }` shape for symmetry across adapters. Properties of context}> Whether this is a development or production build. **Available values**: * `"production"` * `"development"` **Returns** Resolved backend. `resolveConfig` collapses the public boolean/object form to an object (or undefined): a resolved `entry` marks a local backend to spawn, while a lone `host` (e.g. from `CANVA_BACKEND_HOST` with no run opt-in) carries the deployed `BACKEND_HOST` for an external backend without running one. `onCrash` is the api-only hook invoked after a backend crash tears the frontend down — the CLI exits non-zero, an embedding consumer can recover. Properties of backend}> Path to the backend entry script, relative to `rootDir`, falls back to the package default when unset. **Default** ```ts "backend/server.ts" ``` Backend host the built app calls. Falls back to `CANVA_BACKEND_HOST` when unset. **Returns** `void` Resolved test-harness paths. Test harness mode is deliberately only invocable through the concrete env `IN_HARNESS`, to avoid accidental builds with the harness. The harness `entry`/`init` are absolute; `html` is the filename each adapter's `dev()` uses to build its printed URL. For more info, see: [https://www.canva.dev/docs/apps/test-harness/](https://www.canva.dev/docs/apps/test-harness/) Properties of harness}> Absolute path to the harness entry module. **Default** ```ts "harness/harness.tsx" ``` Absolute path to the harness init module. **Default** ```ts "harness/init.ts" ``` Filename used only to build the printed dev-server URL — not read or served by `app-scripts` itself. **Default** ```ts "harness.html" ``` Non-fatal advisories for the caller to render. Absolute path of the loaded config file; undefined when defaults applied.