Docs
Blog
Docs
Blog
📦

Multi-platform builds

Build and package the same extension for multiple browsers with predictable outputs.

Ship the same extension to Chrome, Edge, and Firefox without maintaining separate build scripts. Extension.js can run production builds per target, write artifacts to dist/<browser>, and optionally generate zip packages for distribution.

How it works

Run a production build:

npm
pnpm
yarn
npx extension build

Default browser target is chromium unless overridden.

Video demo soon: default multi-platform build

Browser selection

You can target a specific browser/engine:

npm
pnpm
yarn
npx extension build --browser=chrome
npm
pnpm
yarn
npx extension build --browser=firefox

Supported values include:

  • chrome
  • edge
  • firefox
  • chromium
  • chromium-based
  • gecko-based / firefox-based (aliases)

You can also run a build matrix in one command:

npm
pnpm
yarn
npx extension build --browser=chrome,edge,firefox

This builds sequentially for chrome, edge, and firefox.

Video demo soon: browser matrix build flow

Output layout

Each target writes to its own folder:

  • dist/chrome
  • dist/edge
  • dist/firefox
  • dist/chromium
  • dist/chromium-based
  • dist/gecko-based

Build capabilities

Option What it does
--browser=<target> Builds for a specific browser or engine family.
--zip Creates a distribution zip per target output.
--zip-filename=<name> Overrides the default zip file name.
--zip-source Creates a source archive alongside output.
--polyfill Enables compatibility behavior for browser.* API usage in Chromium-family targets.

Video demo soon: output layout by browser

Generating a zip file

Generate a distribution zip from each target output with --zip:

npm
pnpm
yarn
npx extension build --zip

By default, the zip name uses sanitized manifest name + version, for example:

  • my-extension-1.0.0.zip

Customize filename:

npm
pnpm
yarn
npx extension build --zip --zip-filename=my-release

This creates my-release.zip inside the target dist/<browser> folder.

Video demo soon: zip packaging workflow

Include source archive

Use --zip-source to generate a source archive alongside distribution output.

--zip-source produces:

  • dist/<name>-<version>-source.zip

Video demo soon: source archive output

Polyfill support

If your code relies on Gecko-style browser.* APIs and you need Chromium compatibility, enable --polyfill:

npm
pnpm
yarn
npx extension build --polyfill

Video demo soon: polyfill build behavior

Best practices

  • Build per target in CI: Treat each browser output as an independent artifact.
  • Use a browser matrix command for parity checks: Catch target-specific issues early in one pipeline step.
  • Package intentionally: Use --zip for store uploads and --zip-source for traceable source artifacts.
  • Keep target config explicit: Use extension.config.* command/browser defaults for reproducible builds.

Next steps

ON THIS PAGE