Skip to main content
Run popular Chromium and Gecko forks either by name (Extension.js locates the installed binary for you) or by providing an explicit binary path. Test Brave, Opera, Vivaldi, Yandex, Waterfox, and LibreWolf from the same Extension.js workflow. Name the fork directly, or point at any custom binary with binary flags and extension.config.* in dev, start, and preview.

​
Run a fork by name

These forks are first-class browser targets. Pass the name to --browser and Extension.js finds the installed binary on your system automatically, running it through its engine family’s launcher:
If the browser is not installed, Extension.js exits with install guidance. A named fork inherits its family’s manifest keys, so chromium:/firefox: prefixed fields resolve correctly (see Browser-specific manifest fields).
The dev, build, start, and preview help output all list every fork name. The start and preview lists leave out safari and webkit-based because those two commands refuse Safari targets by design.

​
Run a custom binary

To run a browser without a built-in locator, or to override the located binary, use one of these flags:
  • --chromium-binary <path>
  • --gecko-binary <path> (alias: --firefox-binary <path>)
These binary flags override which browser binary Extension.js launches, regardless of the named browser target you selected.

​
Binary capabilities

​
CLI examples

You can also use them with start and preview.

​
Configure in extension.config.*

You can also place binary paths in command blocks:

​
Target mapping behavior

Binary hints map to engine targets:
  • chromiumBinary → chromium-based
  • geckoBinary / firefoxBinary → gecko-based
If you provide both, Extension.js applies Chromium binary resolution first.

​
Available browsers

Forks with a built-in locator run by name; anything else runs with a binary flag:

​
Important constraints

  • chromium-based requires --chromium-binary (or chromiumBinary in config). Without it the launch hard-exits with an error. There is no fallback to a system browser.
  • gecko-based / firefox-based require a valid geckoBinary path.
  • Invalid paths fail fast with a clear CLI/runtime error.
  • build does not accept binary flags. You can use binary-based launching only with dev, start, and preview.

​
Edge binary override

Set the EDGE_BINARY environment variable to launch --browser=edge from a specific binary, without touching config:
If the path does not exist, the launch fails instead of silently falling back.

​
Best practices

  • Pair binaries with explicit browser target: Use --browser=chromium-based or --browser=gecko-based for predictable intent.
  • Use absolute paths: Avoid shell-dependent path resolution issues.
  • Version-pin in continuous integration (CI) runners: Keep browser binary paths deterministic for automated checks.
  • Combine with profile/flags carefully: Reuse the same profile and flag strategy used for named browser targets.

​
Next steps