Running other browsers from binary path

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:

Browser target	Engine family	Auto-located
`brave`	Chromium	yes
`opera`	Chromium	yes
`vivaldi`	Chromium	yes
`yandex`	Chromium	yes
`waterfox`	Gecko	yes
`librewolf`	Gecko	yes

extension dev --browser=brave

extension dev --browser=waterfox

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

Option / key	What it does
`--chromium-binary <path>`	Launches a custom Chromium-family browser binary.
`--gecko-binary <path>`	Launches a custom Gecko-family browser binary.
`--firefox-binary <path>`	Alias of `--gecko-binary`.
`browser.<target>.chromiumBinary`	Sets default custom Chromium binary in config.
`browser.<target>.geckoBinary`	Sets default custom Gecko binary in config.
`commands.<name>.chromiumBinary`	Sets command-specific custom Chromium binary.
`commands.<name>.geckoBinary`	Sets command-specific custom Gecko binary.

CLI examples

extension dev --browser=chromium-based --chromium-binary="/path/to/brave"

extension dev --browser=firefox --gecko-binary="/path/to/firefox-developer-edition"

You can also use them with start and preview.

Find the binary path per OS

The binary flags expect an executable file. An invalid path fails fast with an error instead of launching.

macOS

On macOS, an app such as /Applications/Brave Browser.app is a folder, not an executable. Pass the executable inside the bundle, at Contents/MacOS:

extension dev --browser=chromium-based --chromium-binary="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"

The executable name can differ from the app name. List the folder to find it:

ls "/Applications/Brave Browser.app/Contents/MacOS"

Windows

Quote the path and use forward slashes, which every shell accepts:

extension dev --browser=chromium-based --chromium-binary="C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"

Backslashes also work, but many shells require you to double them, as in C:\\Program Files\\....

Linux

Pass the executable that your package manager installed:

extension dev --browser=chromium-based --chromium-binary="/usr/bin/brave-browser"

Run which brave-browser to print the path when the binary is on your PATH.

Configure in `extension.config.*`

export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    "gecko-based": {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};

You can also place binary paths in command blocks:

export default {
  commands: {
    dev: {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    preview: {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};

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:

Browser name	Type	How to run	Official website
Brave	Chromium-based browser	`--browser=brave` or `--chromium-binary`	brave.com
Opera	Chromium-based browser	`--browser=opera` or `--chromium-binary`	opera.com
Vivaldi	Chromium-based browser	`--browser=vivaldi` or `--chromium-binary`	vivaldi.com
Yandex	Chromium-based browser	`--browser=yandex` or `--chromium-binary`	browser.yandex.com
Waterfox	Gecko-based browser	`--browser=waterfox` or `--gecko-binary`	Waterfox
LibreWolf	Gecko-based browser	`--browser=librewolf` or `--gecko-binary`	librewolf.net
Firefox Developer Edition	Gecko-based browser	`--gecko-binary`	firefox.com

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:

EDGE_BINARY="/path/to/msedge" extension dev --browser=edge

If the path does not exist, the launch fails instead of silently falling back.

Run without launching a browser

Sometimes the right browser count is zero, for example in containers, over SSH, or when you drive a browser yourself. Pass --no-browser to dev, start, or preview:

extension dev --no-browser

The dev loop stays complete. The server watches your files, and every rebuild broadcasts a reload. After the first successful compile, the terminal prints a (no-browser mode) banner that names the output folder. Load that dist/<browser> folder into a browser that you already run. In Chromium browsers, choose “Load unpacked” at chrome://extensions with Developer mode on. The loaded extension keeps updating on save. See dev for readiness synchronization with --wait. To make this the default for a command, set noBrowser in config. The CLI flag wins over the config value:

export default {
  commands: {
    dev: {
      noBrowser: true,
    },
  },
};

Opt out of injected defaults

dev, start, and preview inject launch defaults into every session. One visible default is dark appearance. Chromium targets get the --force-dark-mode and --enable-features=WebUIDarkMode flags. Gecko targets get the matching dark preferences. To keep your system appearance, list the flag in excludeBrowserFlags:

export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
      excludeBrowserFlags: ["--force-dark-mode"],
    },
  },
};

Excluding --force-dark-mode drops the whole appearance bundle, including the Gecko preferences. An exclude entry also matches by switch name, so --enable-features removes --enable-features=WebUIDarkMode. See Browser flags for the default flag list and the full exclusion rules.

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

Learn more about Browser preferences.
Learn more about Browser profile.

Introduction

Browser extension fundamentals

Getting started

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Running other browsers from binary path

Run a fork by name

Run a custom binary

Binary capabilities

CLI examples

Find the binary path per OS

macOS

Windows

Linux

Configure in `extension.config.*`

Target mapping behavior

Available browsers

Important constraints

Edge binary override

Run without launching a browser

Opt out of injected defaults

Best practices

Next steps

​Run a fork by name

​Run a custom binary

​Binary capabilities

​CLI examples

​Find the binary path per OS

​macOS

​Windows

​Linux

​Configure in extension.config.*

​Target mapping behavior

​Available browsers

​Important constraints

​Edge binary override

​Run without launching a browser

​Opt out of injected defaults

​Best practices

​Next steps

Run a fork by name

Run a custom binary

Binary capabilities

CLI examples

Find the binary path per OS

macOS

Windows

Linux

Configure in `extension.config.*`

Target mapping behavior

Available browsers

Important constraints

Edge binary override

Run without launching a browser

Opt out of injected defaults

Best practices

Next steps