> ## 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. # defineConfig API reference for the defineConfig method. 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: defineConfig with Rsbuild (the default) ```typescript // canva-app.config.ts - Rsbuild (the default) import type { RsbuildContext } from '@canva/app-scripts'; import { defineConfig } 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; }, }); ``` ## Parameters The configuration object Properties of config}> 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** ## Returns The same configuration object (for chaining/export). 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** Define a Canva App configuration object for webpack. 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. Webpack is always an explicit opt-in: set `bundler: 'webpack'` to use it instead of 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: defineConfig with webpack and customization ```typescript // canva-app.config.ts - webpack import type { WebpackContext } from '@canva/app-scripts'; import { defineConfig } from '@canva/app-scripts'; import type { Configuration } from 'webpack'; export default defineConfig({ bundler: 'webpack', entry: './src/index.tsx', config: (webpackConfig: Configuration, { mode }: WebpackContext) => { // Customize the webpack config here if (mode === 'production') { // Production specific configuration } // Common configuration return webpackConfig; }, }); ``` ## Parameters The configuration object Properties of config}> 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 same configuration object (for chaining/export). 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**