Skip to main content

Documentation Index

Fetch the complete documentation index at: https://extension.js.org/llms.txt

Use this file to discover all available pages before exploring further.

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. Use 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 which browser binary Extension.js launches, regardless of the named browser target you selected.

​
Binary capabilities

Option / keyWhat 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>.chromiumBinarySets default custom Chromium binary in config.
browser.<target>.geckoBinarySets default custom Gecko binary in config.
commands.<name>.chromiumBinarySets command-specific custom Chromium binary.
commands.<name>.geckoBinarySets 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.

​
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

Common browsers you can run with binary flags:
Browser nameTypeCLI flagOfficial website
BraveChromium-based browser--chromium-binarybrave.com
OperaChromium-based browser--chromium-binaryopera.com
VivaldiChromium-based browser--chromium-binaryvivaldi.com
WaterfoxGecko-based browser--gecko-binaryWaterfox
Firefox Developer EditionGecko-based browser--gecko-binaryfirefox.com

​
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