Extension config (extension.config.js)

Use one configuration file to set browser defaults, command behavior, and bundler customization. Share browser defaults, command options, and build settings across your team. Stop repeating CLI flags. Extension.js reads extension.config.js (or .mjs / .cjs) from your project root. It applies settings to every command and the bundler.

How it works

Add extension.config.js at your project root (same level as package.json in typical setups). Supported file names:

extension.config.js
extension.config.mjs
extension.config.cjs

Top-level keys:

Key	Description
`browser`	Browser-specific defaults keyed by browser target.
`commands`	Per-command defaults (`dev`, `start`, `preview`, `build`).
`extensions`	Companion extensions applied across commands (load-only).
`transpilePackages`	Packages to compile before bundling (useful for monorepo/workspace setups).
`config`	Hook to extend/override the generated Rspack config.

Type-safe configuration

Extension.js exports the FileConfig type from the extension package so editors can autocomplete and type-check your config. Annotate the export with a JSDoc @type tag — it works in extension.config.js, .mjs, and .cjs without a build step:

/** @type {import('extension').FileConfig} */
export default {
  browser: {
    chrome: { profile: "path/to/profile" },
  },
};

Environment loading for configuration files

extension.config.* runs in Node and should read values from process.env.*.

Extension.js preloads env files before evaluating extension.config.*.
It first checks the project folder.
In monorepos, if Extension.js finds no project-local .env* file, it falls back to the nearest workspace root. The workspace root is the folder containing pnpm-workspace.yaml.
Prefer built-in env preload over importing dotenv in your configuration file.

Browser configuration

Need different browser defaults per target? Use browser:

export default {
  browser: {
    chrome: {
      profile: "path/to/profile",
      preferences: { darkMode: true },
      browserFlags: ["--disable-web-security"],
      excludeBrowserFlags: ["--mute-audio"],
    },
    "chromium-based": {
      chromiumBinary: "/path/to/brave-or-other-chromium-binary",
    },
    firefox: {
      geckoBinary: "/path/to/firefox",
    },
  },
};

Supported browser keys include: chrome, edge, firefox, chromium, chromium-based, gecko-based, firefox-based. Common browser fields:

profile, persistProfile
preferences
browserFlags, excludeBrowserFlags
chromiumBinary, geckoBinary
extensions (companion load-only extensions)

Browser target capabilities

Key	What it does
`profile`	Sets the browser profile path (or profile behavior) used when launching.
`persistProfile`	Reuses profile data between runs.
`preferences`	Applies browser preference overrides.
`browserFlags`	Adds launch flags for the browser process.
`excludeBrowserFlags`	Removes default launch flags you do not want.
`chromiumBinary`	Uses a custom Chromium-family binary path.
`geckoBinary`	Uses a custom Gecko/Firefox binary path.
`extensions`	Loads companion extensions together with the main extension.

Commands configuration

Use commands to define defaults per command:

export default {
  transpilePackages: ["@workspace/ui"],
  commands: {
    dev: {
      browser: "chrome",
      polyfill: true,
      logLevel: "info",
      persistProfile: true,
      browserFlags: ["--headless=new"],
      extensions: { dir: "./extensions" },
    },
    start: {
      browser: "firefox",
    },
    preview: {
      browser: "edge",
      noBrowser: false,
    },
    build: {
      browser: "chrome",
      zip: true,
      zipSource: true,
      zipFilename: "my-extension.zip",
      transpilePackages: ["@workspace/ui", "@workspace/icons"],
    },
  },
};

Notes:

Extension.js merges top-level extensions and transpilePackages into command defaults.
Per-command values override top-level values.
The start command runs build then preview internally. Extension.js applies settings from commands.start, including browser-launch options like profile, browserFlags, and startingUrl. You can also put build-specific settings in commands.build.

Command capabilities (shared)

Key	Applies to	What it does
`browser`	`dev`, `start`, `preview`, `build`	Sets browser or browser-family target.
`profile`	`dev`, `start`, `preview`	Sets browser profile path/behavior.
`persistProfile`	`dev`, `start`, `preview`	Reuses browser profile data between runs.
`chromiumBinary`	`dev`, `start`, `preview`	Uses a custom Chromium-family binary.
`geckoBinary`	`dev`, `start`, `preview`	Uses a custom Gecko-family binary.
`polyfill`	`dev`, `start`, `build`	Enables compatibility polyfill behavior where relevant.
`preferences`	`dev`, `start`, `preview`	Applies browser preference overrides.
`browserFlags`	`dev`, `start`, `preview`	Adds launch flags for the browser process.
`excludeBrowserFlags`	`dev`, `start`, `preview`	Removes default launch flags you do not want.
`startingUrl`	`dev`, `start`, `preview`	Opens a specific URL on browser launch.
`port`	`dev`, `start`, `preview`	Sets runner/DevTools port.
`host`	`dev`, `start`, `preview`	Sets dev server host. Use `0.0.0.0` for Docker/dev containers.
`noBrowser`	`dev`, `start`, `preview`	Disables browser launch.
`extensions`	`dev`, `start`, `preview`, `build`	Loads companion extensions (or extension list).
`install`	`dev`, `start`, `build`	Installs missing dependencies before running.
`transpilePackages`	`dev`, `start`, `preview`, `build`	Transpiles listed workspace/external packages.

`build` command capabilities

Key	What it does
`zip`	Generates a packaged zip artifact.
`zipSource`	Adds source bundle/archive output for review/compliance workflows.
`zipFilename`	Sets a custom zip output filename.
`silent`	Reduces build log output.

`dev` command capabilities

Key	What it does
`noOpen`	Runs dev server without auto-opening browser.

Logging capabilities

Key	Applies to	What it does
`logs`	`dev`, `start`, `preview`	Sets minimum log level (`off` to `all`).
`logContext`	`dev`, `start`, `preview`	Filters logs by context (`background`, `content`, etc.).
`logFormat`	`dev`, `start`, `preview`	Sets output format (`pretty`, `json`, `ndjson`).
`logUrl`	`dev`, `start`, `preview`	Filters logs by URL pattern.
`logTab`	`dev`, `start`, `preview`	Filters logs by tab ID.

Rspack configuration

Need advanced bundler customization? Use config to patch the generated Rspack configuration:

export default {
  config: (config) => {
    config.module.rules.push({
      test: /\.mdx$/,
      use: ["babel-loader", "@mdx-js/loader"],
    });
    return config;
  },
};

config may also be an object, which Extension.js merges on top of the generated config.

Full sample

export default {
  browser: {
    chrome: { browser: "chrome", profile: "default" },
    firefox: { browser: "firefox", persistProfile: true },
    "chromium-based": {
      browser: "chromium-based",
      chromiumBinary:
        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    },
  },
  commands: {
    dev: {
      browser: "chrome",
      polyfill: true,
      host: "0.0.0.0",
      extensions: { dir: "./extensions" },
    },
    start: { browser: "edge" },
    preview: { browser: "firefox" },
    build: {
      zipFilename: "extension.zip",
      zip: true,
      zipSource: true,
    },
  },
  extensions: { dir: "./extensions" },
  transpilePackages: ["@workspace/ui"],
  config: (config) => config,
};

Best practices

Keep browser-specific values in browser: Keep command definitions focused on workflow, not browser internals.
Use top-level defaults intentionally: Put shared extensions / transpilePackages at root; override only where needed.
Prefer chromiumBinary/geckoBinary names: They align with current command and type surface.
Keep config hook minimal: Add only what first-class Extension.js options do not cover.

Next steps

Learn more about Browsers available.
Learn more about Rspack configuration.
Tune launch behavior with Browser flags and Browser preferences.
Manage env values with Environment variables.

Environment variables in browser extensions Rspack configuration in extension.config.js

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Debugging

Implementation guide

Community

Extension config (extension.config.js)

How it works

Type-safe configuration

Environment loading for configuration files

Browser configuration

Browser target capabilities

Commands configuration

Command capabilities (shared)

`build` command capabilities

`dev` command capabilities

Logging capabilities

Rspack configuration

Full sample

Best practices

Next steps

​How it works

​Type-safe configuration

​Environment loading for configuration files

​Browser configuration

​Browser target capabilities

​Commands configuration

​Command capabilities (shared)

​build command capabilities

​dev command capabilities

​Logging capabilities

​Rspack configuration

​Full sample

​Best practices

​Next steps

How it works

Type-safe configuration

Environment loading for configuration files

Browser configuration

Browser target capabilities

Commands configuration

Command capabilities (shared)

`build` command capabilities

`dev` command capabilities

Logging capabilities

Rspack configuration

Full sample

Best practices

Next steps