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.

​
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

​
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:
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

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