A helper for defining an app's build configuration with full type-checking, used as the default export of the canva-app.config.ts file in an app project's root.

A config file is optional: without one, the defaults are used, including the default bundler (Rsbuild).

Precedence: where an option can be set in more than one place, CLI flag > environment variable > this config file > package default.

Usage

// canva-app.config.ts - Rsbuild (the default)
import { defineConfig } from '@canva/app-scripts';
import type { RsbuildContext } from '@canva/app-scripts';
import type { RsbuildConfig } from '@rsbuild/core';

export default defineConfig({
  bundler: 'rsbuild',
  entry: './src/index.tsx',
  config: (rsbuildConfig: RsbuildConfig, { mode }: RsbuildContext) => {
    // Customize the Rsbuild config here
    if (mode === 'production') {
      // Production specific configuration
    }
    // Common configuration
    return rsbuildConfig;
  },
});

TYPESCRIPT

Parameters

configRsbuildAppConfig

Required

The configuration object

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

Returns

The same configuration object (for chaining/export).

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}').

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

Define a Canva App configuration object.

A helper for defining an app's build configuration with full type-checking, used as the default export of the canva-app.config.ts file in an app project's root.

A config file is optional: without one, the defaults are used, including the default bundler (Rsbuild).

Precedence: where an option can be set in more than one place, CLI flag > environment variable > this config file > package default.

Usage

// canva-app.config.ts - Rsbuild (the default)
import { defineConfig } from '@canva/app-scripts';
import type { RsbuildContext } from '@canva/app-scripts';
import type { RsbuildConfig } from '@rsbuild/core';

export default defineConfig({
  bundler: 'rsbuild',
  entry: './src/index.tsx',
  config: (rsbuildConfig: RsbuildConfig, { mode }: RsbuildContext) => {
    // Customize the Rsbuild config here
    if (mode === 'production') {
      // Production specific configuration
    }
    // Common configuration
    return rsbuildConfig;
  },
});

TYPESCRIPT

Parameters

configWebpackAppConfig

Required

The configuration object

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 same configuration object (for chaining/export).

bundlerstring

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