Skip navigation

Skip to main content

API reference
Intents
Intents: Content
Intents: Design
Intents: Test
Platform: Test
API reference

build

API reference for the build method.

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

Run a production build 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 runs the build. The result carries notices, configPath, and version so callers can present them.

Usage

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


const result = await build({
  overrides: { entry: './src/index.tsx' },
});
console.log(`Built in ${result.duration}ms`);
TYPESCRIPT

Parameters

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"
TS
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

8080
TS
httpsboolean
Optional

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

Default

false
TS
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"
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

3001
TS
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
TS
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"
TS
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

8080
TS
httpsboolean
Optional

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

Default

false
TS
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"
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

3001
TS
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
TS
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

Build result with output information. This is a Promise that resolves with the following object:

outputDirstring

Output directory path

assetsOutputFile[]

Generated assets with their output sizes

pathstring

Path relative to outputDir

sizeBytesnumber

Size on disk in bytes

durationnumber

Build duration in milliseconds

noticesstring[]

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

versionstring

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

configPathstring
Optional

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