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

# Supported browsers for Extension.js development

> See which browsers Extension.js supports. Run and test extensions across Chrome, Edge, Firefox, and custom binaries from a single CLI workflow.

<AvatarBrowsers browsers={["chrome", "firefox", "edge"]} />

Run and test your extension across major browsers from one CLI workflow.

Validate one extension across Chrome, Edge, Firefox, and custom browser binaries from a single CLI.

Use this page when you need to test a Chrome extension, Firefox extension, or Edge extension from the same Extension.js project.

## Choose the right target

| Target           | Use when                                            | Example                                                                     |
| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
| `chromium`       | Fast default local development                      | `extension dev --browser=chromium`                                          |
| `chrome`         | Validating Chrome-specific behavior                 | `extension dev --browser=chrome`                                            |
| `edge`           | Validating Edge distribution behavior               | `extension dev --browser=edge`                                              |
| `firefox`        | Validating Gecko compatibility and APIs             | `extension dev --browser=firefox`                                           |
| `chrome,firefox` | Release checks across both major engines            | `extension build --browser=chrome,firefox`                                  |
| `chromium-based` | Running custom Chromium binaries (Brave, Arc, etc.) | `extension dev --browser=chromium-based --chromium-binary=/path/to/browser` |
| `gecko-based`    | Running custom Firefox-family binaries              | `extension dev --browser=gecko-based --gecko-binary=/path/to/browser`       |
| `safari`         | Building a Safari app on macOS (Xcode required)     | `extension build --browser=safari`                                          |

## How it works

Use `--browser` to choose a target in `dev`, `start`, `preview`, and `build`.

If you do not specify a browser, the CLI defaults to `chromium`.

`safari` (and its `webkit-based` alias) is the exception: it's an **alpha**, macOS-only build target supported by `build` and `dev` only — not `preview` or `start`. See [Building Safari extensions](/docs/browsers/safari).

## Supported browsers

Named browser targets:

| Browser      | Usage                                  |
| ------------ | -------------------------------------- |
| **Chrome**   | `npx extension dev --browser=chrome`   |
| **Edge**     | `npx extension dev --browser=edge`     |
| **Firefox**  | `npx extension dev --browser=firefox`  |
| **Chromium** | `npx extension dev --browser=chromium` |

Engine-based targets (custom binary required):

| Engine target                     | Usage                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------- |
| **Chromium-based**                | `npx extension dev --browser=chromium-based --chromium-binary=/path/to/browser` |
| **Gecko-based** (`firefox-based`) | `npx extension dev --browser=gecko-based --gecko-binary=/path/to/browser`       |

Extension.js treats `firefox-based` as a Gecko engine target internally.

## Safari and other WebKit targets

In addition to the Chromium family and Firefox (Gecko engine), Extension.js can build your extension into a **Safari** app on macOS.

| Target                          | Usage                                        |
| ------------------------------- | -------------------------------------------- |
| **Safari**                      | `npx extension build --browser=safari`       |
| **WebKit-based** (engine alias) | `npx extension build --browser=webkit-based` |

Safari is a **build target**: `build` and `dev` are supported, but `preview` and `start` are not (Safari extensions can't be auto-loaded into a live browser). It requires macOS with the full Xcode app. See [Building Safari extensions](/docs/browsers/safari) for the full workflow, requirements, and how to enable the extension in Safari.

## Multi-browser selection

You can run multiple named browsers in one command:

```bash theme={null}
npx extension dev --browser=chrome,firefox
```

Use comma-separated values to run multiple named targets in sequence (for example, `--browser=chrome,edge,firefox`).

## Constraints and behavior

* `chromium-based` requires `--chromium-binary`.
* `gecko-based` / `firefox-based` require `--gecko-binary`.
* Engine-based targets route to the same Chromium/Firefox runners with engine-aware behavior.

## Best practices

* **Use named browsers for daily iteration**: `chrome`, `edge`, and `firefox` are the fastest path for regular testing.
* **Use engine-based mode intentionally**: Prefer `chromium-based` / `gecko-based` only when validating custom binaries.
* **Keep profiles isolated per browser**: Reduce cross-browser state leakage while debugging.
* **Pair with browser-specific fields**: Use browser-prefixed manifest keys for true behavior differences.

## Next steps

* [Customize browser flags](/docs/browsers/browser-flags).
* [Customize browser preferences](/docs/browsers/browser-preferences).
* [Run other browsers from custom binaries](/docs/browsers/running-other-browsers).
* [Build Safari extensions on macOS](/docs/browsers/safari).