> ## 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.