Most apps start with canva apps start (using @canva/cli) or canva-app-scripts dev (using @canva/app-scripts). Call this API only for programmatic use. See Canva App Scripts for the CLI-first workflow.

Start a development server for a Canva App.

Loads the project's canva-app.config.{ts,…} (or the file named by options.configFile), applies options.overrides on top — overrides > env > config file > default — and starts the dev server. The returned handle carries notices, configPath, version, entry, and bundler so callers can present them.

Usage

import { dev } from '@canva/app-scripts';

const server = await dev({
  overrides: { entry: './src/index.tsx' },
});
console.log(`Server running at ${server.url}`);

// Later: stop the server
await server.close();

TYPESCRIPT

Parameters

optionsDevOptions

Optional

Configuration overrides, config-file selection, crash hook

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

onCrashfunction

Optional

Invoked after a backend crash has torn the dev server down — exit, restart, or surface the failure as suits the caller. The canva-app-scripts CLI exits the process.

Returns

void

Returns

Handle to the running dev server. This is a Promise that resolves with the following object:

bundlerNonNullable<string | undefined>

The bundler used to start the development server

entrystring

The entry path used to start the development server

closefunction

Stop the development server (and the backend, if one was started).

Returns

Promise<void>

urlstring

URL where the server is running

portnumber

Port the server is running on

noticesstring[]

One-line notices where an env var shadowed a config-file value.

hmrboolean

Whether Hot Module Replacement is active for this server.

versionstring

The running @canva/app-scripts version (the module-level version).

backendobject

Optional

Backend addresses, present when a backend is configured. localUrl is always the local address; publicUrl is the tunnel address when a tunnel was requested (backend.tunnel) and started successfully, else undefined. tunnel reports whether one was requested, distinguishing "no tunnel asked for" from "tunnel failed to start".

localUrlstring

tunnelboolean

publicUrlstring

Optional

configPathstring

Optional

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