> ## 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.

# Build command for production extension artifacts

> Create production-ready extension artifacts for Chrome, Edge, or Firefox with the Extension.js build command. Supports multi-browser and zip output.

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](/docs/features/environment-variables#how-it-works) 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

<CodeGroup>
  ```bash npm theme={null}
  extension build [project-path] [options]
  ```

  ```bash pnpm theme={null}
  extension build [project-path] [options]
  ```

  ```bash yarn theme={null}
  extension build [project-path] [options]
  ```

  ```bash bun theme={null}
  extension build [project-path] [options]
  ```

  ```bash deno theme={null}
  extension build [project-path] [options]
  ```
</CodeGroup>

## 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.

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

**Example output structure:**

```plaintext theme={null}
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](/docs/workflows/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.

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash bun theme={null}
  extension build ./my-extension --mode development
  ```

  ```bash deno theme={null}
  extension build ./my-extension --mode development
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash bun theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```

  ```bash deno theme={null}
  extension build ./my-extension --browser=edge,chrome --zip --zip-filename=my-extension.zip
  ```
</CodeGroup>

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

### Building with polyfill support

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash bun theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```

  ```bash deno theme={null}
  extension build ./my-extension --browser=chrome,firefox --polyfill
  ```
</CodeGroup>

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

### Building source and artifact zip

<CodeGroup>
  ```bash npm theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash pnpm theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash yarn theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash bun theme={null}
  extension build ./my-extension --zip --zip-source
  ```

  ```bash deno theme={null}
  extension build ./my-extension --zip --zip-source
  ```
</CodeGroup>

## 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

* Run existing build output with [`preview`](/docs/commands/preview).
* Build and launch in one command with [`start`](/docs/commands/start).
* Configure shared defaults in [`extension.config.js`](/docs/features/extension-configuration).
* Review configuration env loading behavior in [Environment variables](/docs/features/environment-variables#how-it-works).
* Review supported targets in [Browsers available](/docs/browsers/browsers-available).