Documentation Index
Fetch the complete documentation index at: https://extension.js.org/llms.txt
Use this file to discover all available pages before exploring further.
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 |
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.
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 | Useful for engine-family workflows |
| Multi-target | chrome,firefox | Comma-separated targets |
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
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
my-extension.zip.
Building with polyfill support
extension build ./my-extension --browser=chrome,firefox --polyfill
Building source and artifact zip
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
