Skip to main content
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

TargetUse whenExample
chromiumFast default local developmentextension dev --browser=chromium
chromeValidating Chrome-specific behaviorextension dev --browser=chrome
edgeValidating Edge distribution behaviorextension dev --browser=edge
firefoxValidating Gecko compatibility and APIsextension dev --browser=firefox
chrome,firefoxRelease checks across both major enginesextension build --browser=chrome,firefox
chromium-basedRunning custom Chromium binaries (Brave, Arc, etc.)extension dev --browser=chromium-based --chromium-binary=/path/to/browser
gecko-basedRunning custom Firefox-family binariesextension dev --browser=gecko-based --gecko-binary=/path/to/browser
safariBuilding 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.

​
Supported browsers

Named browser targets:
BrowserUsage
Chromenpx extension dev --browser=chrome
Edgenpx extension dev --browser=edge
Firefoxnpx extension dev --browser=firefox
Chromiumnpx extension dev --browser=chromium
Engine-based targets (custom binary required):
Engine targetUsage
Chromium-basednpx 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.
TargetUsage
Safarinpx 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 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: 
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