Most apps never need this, dev, build, and extractTranslations already run it internally. Call it only when building custom tooling. See 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.

Parameters

commandCommand

Required

Which commands's validation rules to apply

Available values:

"dev"
"build"
"extractTranslation"

optionsCoreCommandOptions

Optional

Configuration overrides and config-file selection

configFilestring

Optional

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.

overridesCanvaAppConfig

Optional

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.

entrystring

Optional

Entry point for the app (default: 'src/index.tsx')

rootDirstring

Optional

Root directory of the project (default: process.cwd())

outputDirstring

Optional

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

"dist"

devServerDevServerOptions

Optional

Optional dev-server options (frontend port, HTTPS, public tunnel). CLI flags and env vars override these at run time.

portnumber

Optional

Frontend dev-server port. Overridden by --override-frontend-port and the CANVA_FRONTEND_PORT env var.

Default

httpsboolean

Optional

Serve the frontend over HTTPS using locally-managed certificates. Overridden by --use-https.

Default

false

backendobject

Optional

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

export default defineConfig({
  entry: "./src/index.tsx",
  backend: true, // runs backend/server.ts
});

TYPESCRIPT

export default defineConfig({
  entry: "./src/index.tsx",
  backend: { entry: "./api/main.ts", port: 3100 },
});

TYPESCRIPT

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.

entrystring

Optional

Path to the backend entry script, relative to rootDir, falls back to the package default when unset.

Default

"backend/server.ts"

portnumber

Optional

Port the backend listens on, used to build DevServer.backend.url. Falls back to CANVA_BACKEND_PORT then the package default when unset.

Default

hoststring

Optional

Backend host the built app calls. Falls back to CANVA_BACKEND_HOST when unset.

tunnelboolean

Optional

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⁠(opens in a new tab or window)

Default

false

extractTranslationsobject

Optional

Optional configuration for extractTranslations.

outputDirstring

Optional

Directory to write extracted messages into (default: 'dist').

outputFilestring

Optional

Output filename written into outputDir (default: 'messages_en.json'). Must be a bare filename — no directory segments; use outputDir for that.

patternstring

Optional

Glob for source files to scan (default: 'src/**/*.{ts,tsx}').

bundlerstring

Optional

The bundler to use for building the app. Defaults to 'rsbuild' if not specified.

The only valid value is "rsbuild".

configRsbuildConfigFn

Optional

Customize the Rsbuild configuration. Receives the base config and context, returns modified config.

Example

export default defineConfig({
  config: (rsbuildConfig, { mode }) => {
    rsbuildConfig.plugins?.push(myPlugin());
    return rsbuildConfig;
  },
});

TYPESCRIPT

Parameters

configRsbuildConfig

Required

contextRsbuildContext

Required

Context passed to the Rsbuild customization function.

Mirrors WebpackContext's { mode } shape for symmetry across adapters.

modestring

Required

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.

bundlerstring

Required

The bundler to use for building the app.

The only valid value is "webpack".

entrystring

Optional

Entry point for the app (default: 'src/index.tsx')

rootDirstring

Optional

Root directory of the project (default: process.cwd())

outputDirstring

Optional

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

"dist"

devServerDevServerOptions

Optional

Optional dev-server options (frontend port, HTTPS, public tunnel). CLI flags and env vars override these at run time.

portnumber

Optional

Frontend dev-server port. Overridden by --override-frontend-port and the CANVA_FRONTEND_PORT env var.

Default

httpsboolean

Optional

Serve the frontend over HTTPS using locally-managed certificates. Overridden by --use-https.

Default

false

backendobject

Optional

Optional backend run alongside the dev server.

Use true (or any backend config, even {}) to run the backend at the default location backend/server.ts; set entry to point elsewhere.

Examples

export default defineConfig({
  entry: "./src/index.tsx",
  backend: true, // runs backend/server.ts
});

TYPESCRIPT

export default defineConfig({
  entry: "./src/index.tsx",
  backend: { entry: "./api/main.ts", port: 3100 },
});

TYPESCRIPT

Backend options for the dev server.

entrystring

Optional

Path to the backend entry script, relative to rootDir, falls back to the package default when unset.

Default

"backend/server.ts"

portnumber

Optional

Port the backend listens on, used to build DevServer.backend.url. Falls back to CANVA_BACKEND_PORT then the package default when unset.

Default

hoststring

Optional

Backend host the built app calls. Falls back to CANVA_BACKEND_HOST when unset.

tunnelboolean

Optional

See

https://github.com/canva-sdks/canva-apps-sdk-starter-kit/blob/main/templates/hello_world/README.md#configure-ngrok-optional⁠(opens in a new tab or window)

Default

false

extractTranslationsobject

Optional

Optional configuration for extractTranslations.

outputDirstring

Optional

Directory to write extracted messages into (default: 'dist').

outputFilestring

Optional

Output filename written into outputDir (default: 'messages_en.json'). Must be a bare filename — no directory segments; use outputDir for that.

patternstring

Optional

Glob for source files to scan (default: 'src/**/*.{ts,tsx}').

configWebpackConfigFn

Optional

Customize the webpack configuration. Receives the base config and context, returns modified config.

Example

export default defineConfig({
  bundler: 'webpack',
  config: (webpackConfig, { mode }) => {
    webpackConfig.plugins?.push(new MyPlugin());
    return webpackConfig;
  },
});

TYPESCRIPT

Parameters

configConfiguration

Required

contextWebpackContext

Required

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.

modestring

Required

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:

configFullConfig

The fully-resolved config the engine consumes.

bundlerstring

The resolved bundler, defaulting to Rsbuild.

Available values:

"rsbuild"
"webpack"

entrystring

Resolved frontend entry, relative to rootDir (or absolute), defaulting to src/index.tsx; validateConfig checks it exists.

rootDirstring

Resolved project root, defaulting to process.cwd().

outputDirstring

Resolved build output directory, relative to rootDir (or absolute), defaulting to dist. Consumers absolutize against rootDir.

assetsDirstring

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.

extractTranslationsobject

Resolved extractTranslations options, all fields defaulted.

outputDirstring

outputFilestring

patternstring

devServerobject

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.

portnumber

httpsobject

Options for SSL certificate generation.

sslDirstring

Optional

Directory to store SSL certificates (default: .ssl in rootDir)

rootDirstring

Optional

Root directory of the project (default: process.cwd())

hmrboolean

openboolean

Optional

Open browser on start

appOriginstring

Optional

App origin URL for HMR CORS configuration

sslSSLCertPaths

Optional

Pre-generated SSL certificate paths (avoids regeneration)

certFilestring

Path to the SSL certificate file

keyFilestring

Path to the SSL private key file

appIdstring

Optional

The app's identity from CANVA_APP_ID, captured by resolveConfig so validation stays env-free. Required when a backend runs in dev.

configobject

Optional

Customize the selected bundler's configuration

Function to customize webpack configuration. Receives the base config and returns a modified version.

Example

config: (webpackConfig, { mode }) => {
  if (mode === "production") {
    webpackConfig.plugins?.push(new MyPlugin());
  }
  return webpackConfig;
}

TYPESCRIPT

Parameters

configConfiguration

Required

contextWebpackContext

Required

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.

modestring

Required

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

config: (rsbuildConfig, { mode }) => {
  if (mode === "production") {
    rsbuildConfig.output = { ...rsbuildConfig.output, sourceMap: false };
  }
  return rsbuildConfig;
}

TYPESCRIPT

Parameters

configRsbuildConfig

Required

contextRsbuildContext

Required

Context passed to the Rsbuild customization function.

Mirrors WebpackContext's { mode } shape for symmetry across adapters.

modestring

Required

Whether this is a development or production build.

Available values:

"production"
"development"

Returns

backendobject

Optional

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.

portnumber

tunnelboolean

entrystring

Optional

Path to the backend entry script, relative to rootDir, falls back to the package default when unset.

Default

"backend/server.ts"

hoststring

Optional

Backend host the built app calls. Falls back to CANVA_BACKEND_HOST when unset.

onCrashfunction

Optional

Returns

void

harnessHarnessConfig

Optional

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/

entrystring

Absolute path to the harness entry module.

Default

"harness/harness.tsx"

initstring

Absolute path to the harness init module.

Default

"harness/init.ts"

htmlstring

Filename used only to build the printed dev-server URL — not read or served by app-scripts itself.

Default

"harness.html"

noticesstring[]

Non-fatal advisories for the caller to render.

configPathstring

Optional

Absolute path of the loaded config file; undefined when defaults applied.