Running other browsers from binary path#

Run Chromium- and Gecko-family browsers beyond the default named targets by providing explicit binary paths.

Test custom browser binaries (for example Brave, Vivaldi, or Waterfox) from the same Extension.js workflow. Extension.js supports custom browser executables through binary flags and extension.config.* in dev, start, and preview.

How it works#

Use one of these flags:

• --chromium-binary <path>
• --gecko-binary <path> (alias: --firefox-binary <path>)

These binary flags override named browser selection at runner level.

Binary capabilities#

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.

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 both are provided, Chromium binary resolution is applied first.

Available browsers#

Common browsers you can run with binary flags:

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; binary-based launching applies to 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 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#

• Check out the browser preferences to further configure your environment.
• Learn more about Browser profile.