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

​
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 a valid chromiumBinary path.
  • 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.

​
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