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.
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 |
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.
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 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 |
firefox-based as a Gecko engine target internally.
Safari and other WebKit targets
The CLI fully supports the Chromium family and Firefox (Gecko engine). Chromium targets include chromium, chrome, edge, and chromium-based with a custom binary. Firefox targets include firefox, gecko-based, and firefox-based.
Safari is not a supported --browser value in the CLI today. You can still author extensions with shared web code and add Safari-specific build steps outside this workflow.
Multi-browser selection
You can run multiple named browsers in one command:
npx extension dev --browser=chrome,firefox
--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
