Skip to main content
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 the named browser you selected at runner level.

​
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; 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