Build command for production extension artifacts

Create production extension artifacts for one or more browser targets. build compiles your extension in production mode and writes output to dist/<browser>. For monorepo/submodule projects, see Environment variables for configuration-time env resolution (project root first, then workspace-root fallback).

When to use `build`

Preparing extension packages for Chrome Web Store, Edge Add-ons, or Firefox Add-ons.
Running continuous integration (CI) jobs that produce repeatable production artifacts.
Validating production bundle output and browser-target differences before submission.

Build command capabilities

Capability	What it gives you
Production compilation	Generate optimized extension artifacts per target
Multi-target output	Build multiple browser targets in one command
Packaging support	Create distribution zip artifacts with optional source bundle
CI-friendly behavior	Keep build outputs and naming predictable in automation

Usage

extension build [project-path] [options]

extension build [project-path] [options]

extension build [project-path] [options]

extension build [project-path] [options]

extension build [project-path] [options]

Build output

After running build, Extension.js generates optimized files for the selected browser targets. Output goes to dist/ with one subfolder per target. Each folder contains bundled JavaScript, CSS, HTML, and required runtime assets.

For TypeScript projects, build also regenerates the extension-env.d.ts ambient type declarations (the same file dev writes), so a CI tsc --noEmit stays clean whether or not you ran dev first. JavaScript-only projects skip this step.

Example output structure:

dist/
├── chrome/
│   ├── manifest.json
│   ├── background/service_worker.js
│   ├── content_scripts/content-0.js
├── edge/
│   ├── manifest.json
│   ├── background/service_worker.js
│   ├── content_scripts/content-0.js

Browser target matrix

Target style	Examples	Notes
Named targets	`chromium`, `chrome`, `edge`, `firefox`	Build one specific browser target
Engine targets	`chromium-based`, `gecko-based`, `firefox-based`	Family-generic artifacts. See below
Multi-target	`chrome,firefox`	Comma-separated targets

What engine targets mean for `build`

build never launches a browser, so engine targets don’t point at a binary here, but they still produce a distinct artifact, not a renamed copy of a named-target build:

Own output folder. --browser=chromium-based writes to dist/chromium-based, the same folder dev, preview, and start use for that target, so a project developed against a custom Chromium binary builds to matching paths.
Own env resolution. .env.chromium-based and .env.chromium-based.production win over the family’s .env.chromium/.env.chrome/.env.edge, and bundled code sees EXTENSION_BROWSER === "chromium-based", so code and config can branch on “generic Chromium” vs a specific store build.
Own manifest prefix. chromium-based: keys in manifest.json resolve as the most-specific match for this target, on top of the family-wide chrome:/chromium:/edge: keys.

gecko-based works the same way relative to firefox. No browser binary is required, and --chromium-binary/--gecko-binary only matter for commands that launch a browser.

Arguments and flags

Flag	Alias	What it does	Default
`[path]`	-	Builds a local extension project.	`process.cwd()`
`--browser <browser>`	-	Browser/engine target (`chromium`, `chrome`, `edge`, `firefox`, `safari`, engine aliases, or comma-separated values).	`chromium`
`--polyfill [boolean]`	-	Enables `browser.*` API compatibility polyfill for Chromium targets.	`false`
`--no-polyfill`	-	Disables the cross-browser polyfill.	polyfill disabled
`--zip [boolean]`	-	Creates a packaged zip artifact.	`false`
`--zip-source [boolean]`	-	Includes source files in zip output.	`false`
`--zip-filename <name>`	-	Sets custom zip filename.	sanitized extension name + version
`--silent [boolean]`	-	Suppresses build logs.	`false`
`--mode <mode>`	-	Bundler mode override (`development`, `production`, or `none`). Also sets `NODE_ENV`.	`production`
`--extensions <list>`	-	Comma-separated companion extensions or store URLs.	unset
`--install [boolean]`	-	Internal flag. Install project dependencies when missing. Lifecycle scripts stay disabled unless `EXTENSION_ALLOW_INSTALL_SCRIPTS=true`.	installs when `node_modules` is missing
`--output <pretty\|json>`	-	Result format. `json` prints a schema-1 envelope on stdout.	`pretty`
`--debug`	-	Enable maintainer diagnostics.	disabled

--author and --author-mode are hidden, deprecated aliases for --debug.

Safari flags

These flags apply to safari and webkit-based targets only. Passing any of them with another target exits with an error, so a typo never no-ops silently.

Flag	What it does	Default
`--open [boolean]`	Open the built Safari app after packaging. `build` never opens it unless you ask.	`false`
`--app-name <name>`	Override the Safari app name.	the manifest `name`
`--bundle-id <id>`	User-owned bundle identifier in reverse-DNS form. A malformed value fails before any build.	a generated `dev.extensionjs.*` id
`--development-team <id>`	Apple Developer team id to sign the Safari app with. Without it the build is ad-hoc signed, which Safari treats as unsigned, so the extension needs Develop ▸ Allow Unsigned Extensions re-ticked on every launch.	unset (ad-hoc signed)
`--macos-only [boolean]`	Generate a macOS-only Xcode project. Pass `false` for a universal macOS + iOS project.	`true`
`--force-regenerate`	Regenerate the Safari Xcode project even when up to date.	disabled

Safari packaging runs a preflight before the build. On a non-macOS host, build warns and skips the Safari packaging step but still compiles the bundle. On macOS with a broken or missing Xcode, the failure is fatal.

Shared global options

Also supports Global flags.

Mode override

--mode overrides the bundler mode and NODE_ENV for the build. Accepts development, production, or none. Use it to mirror Vite/webpack workflows where you need a non-production bundle for staging or debugging.

extension build ./my-extension --mode development

extension build ./my-extension --mode development

extension build ./my-extension --mode development

extension build ./my-extension --mode development

extension build ./my-extension --mode development

Invalid values exit with an error. The default remains production.

Zip behavior

Option	Effect	Typical use
`--zip`	Creates a packaged artifact zip	Store submission/manual distribution
`--zip-filename`	Sets custom zip name	CI naming conventions
`--zip-source`	Adds source archive alongside artifacts	Compliance/review pipelines

Each zip lands inside its own dist/<browser> folder, next to the unpacked output. Without --zip-filename, the name is the manifest name lowercased with every character outside a-z0-9 and spaces removed, remaining spaces turned into dashes, then the manifest version. A manifest named My Extension+ at version 1.0.0 packages as dist/chrome/my-extension-1.0.0.zip. Because the name is rewritten, read the emitted path from the build output instead of composing it from the manifest name.

Examples

Building with zip output and custom filename

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip

In this example, the build targets Edge and Chrome, zips the output, and saves it as my-extension.zip.

Building with polyfill support

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

extension build ./my-extension --browser=chrome,firefox --polyfill

In this example, the build targets Chrome and Firefox and includes polyfill support where relevant.

Building source and artifact zip

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

extension build ./my-extension --zip --zip-source

What a successful build prints

After the asset summary, a successful build prints the output directory and its size, then a link you can use to share the build for review:

⏵⏵⏵ Extension built for production in dist/chrome (35.5 KB).
⏵⏵⏵ Send this build to someone for review: https://docs.extension.dev/share/unpublished-build-for-review

Each target prints its own pair of lines, so a multi-browser build repeats them once per browser. Builds that succeed with warnings print the warning details above those lines, and the compile line reads compiled with warnings instead of compiled in. Do not gate CI on this prose. It is written for people and it changes between releases. Use the exit code, or --output json below, which is the supported machine contract.

Machine output with `--output json`

--output json prints one schema-1 envelope on stdout and routes the human build lines to stderr. Stdout stays parseable as a single JSON document.

A successful run prints a status: "built" frame. Its value carries the built browsers, the resolved mode, and one summary per browser. Each summary records the output path, asset totals, warning text, and the Safari app identity when relevant.
A failed build prints one ok: false frame with status: "build-failed" and error.code: "E_COMPILE" before the process exits 1.

Every build also writes dist/extension-js/<browser>/build-summary.json. Scripts that shell out to extension build can read structured warnings there. Guard against stale files by checking the file’s modification time.

Best practices

Check build logs: Review logs for warnings and missing assets after each build.
Optimize your manifest: Keep manifest.json compatible with every target browser.
Name artifacts intentionally: Use --zip-filename for stable CI artifact naming.
Validate target output: Check each dist/<browser> folder before publishing. A later dev session overwrites that same folder with a dev-instrumented build that adds permissions such as scripting, tabs, management, and storage, plus host_permissions for <all_urls> and broad web-accessible resources. Run build again before you package or publish.

Next steps

Send the build to a reviewer behind a link by following Share an unpublished build for review.
Submit the artifacts to the browser stores by following the extension.dev publish docs.
Get a shareable URL for a project on extension.dev with publish.
Run existing build output with preview.
Build and launch in one command with start.
Configure shared defaults in extension.config.js.
Review configuration env loading behavior in Environment variables.
Review supported targets in Browsers available.

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Build command for production extension artifacts

When to use `build`

Build command capabilities

Usage

Build output

Browser target matrix

What engine targets mean for `build`

Arguments and flags

Safari flags

Shared global options

Mode override

Zip behavior

Examples

Building with zip output and custom filename

Building with polyfill support

Building source and artifact zip

What a successful build prints

Machine output with `--output json`

Best practices

Next steps

​When to use build

​Build command capabilities

​Usage

​Build output

​Browser target matrix

​What engine targets mean for build

​Arguments and flags

​Safari flags

​Shared global options

​Mode override

​Zip behavior

​Examples

​Building with zip output and custom filename

​Building with polyfill support

​Building source and artifact zip

​What a successful build prints

​Machine output with --output json

​Best practices

​Next steps

When to use `build`

Build command capabilities

Usage

Build output

Browser target matrix

What engine targets mean for `build`

Arguments and flags

Safari flags

Shared global options

Mode override

Zip behavior

Examples

Building with zip output and custom filename

Building with polyfill support

Building source and artifact zip

What a successful build prints

Machine output with `--output json`

Best practices

Next steps