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`, engine aliases, or comma-separated values).	`chromium`
`--polyfill [boolean]`	-	Enables `browser.*` API compatibility polyfill for Chromium targets.	`false`
`--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.	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]`	-	Install project dependencies when missing.	command behavior default
`--author`	`--author-mode`	Enable maintainer diagnostics.	disabled

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

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

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.

Next steps

Publish the artifacts to browser stores with @extension.dev/deploy (npx @extension.dev/deploy); a successful build prints this hint too.
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.

Preview command to launch built extensions Install command for managed browser runtimes

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

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

Shared global options

Mode override

Zip behavior

Examples

Building with zip output and custom filename

Building with polyfill support

Building source and artifact zip

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

​Shared global options

​Mode override

​Zip behavior

​Examples

​Building with zip output and custom filename

​Building with polyfill support

​Building source and artifact zip

​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

Shared global options

Mode override

Zip behavior

Examples

Building with zip output and custom filename

Building with polyfill support

Building source and artifact zip

Best practices

Next steps