waterfox iconopera iconbrave icon

Running Other Browsers From Binary Path

Warning: This feature is a work in progress and may be incomplete or subject to change. If you see an error or something that could be improved, please make a pull request. The link that documents this feature can be found at the bottom of the page.

While Extension.js natively supports browsers like Chrome, Edge, and Firefox, you can also run unsupported browsers by specifying the path to the browser binary using the --chromium-binary or --gecko-binary flags. Additionally, you can add custom binary paths via the extension.config.js file for persistent configuration across runs.

How Does It Work?

If you need to run a browser that is not fully supported by Extension.js, you can specify the path to a custom browser binary using the --chromium-binary or --gecko-binary flags. Extension.js will launch the specified browser binary with your extension loaded, allowing you to test your extension in a custom browser environment.

Example Using CLI Flags:

extension dev --chromiumBinary=/path/to/custom-browser

or for Gecko-based browsers like Firefox:

extension dev --geckoBinary=/path/to/custom-firefox

Example Using extension.config.js:

module.exports = {
  browser: {
    firefox: {
      geckoBinary: "/path/to/custom-firefox",
    },
    "chromium-based": {
      chromiumBinary: "/path/to/custom-browser",
    },
  },
};

In these scenarios, the browser specified in the --chromiumBinary or --geckoBinary flag (or in extension.config.js) will be launched instead of the default Chrome, Edge, or Firefox binaries.

Available Browsers

Here is a short list of browsers you can run using these binary flags, along with their official websites for reference:

Browser Name Type CLI Flag Official Website
Brave Chromium-Based Browser --chromium-binary brave.com
Opera Chromium-Based Browser --chromium-binary opera.com
Vivaldi Chromium-Based Browser --chromium-binary vivaldi.com
Waterfox Gecko-Based Browser --gecko-binary waterfox.net
Firefox Developer Edition Gecko-Based Browser --gecko-binary firefox.com

Example Configuration

Below is an example configuration using the --gecko-binary flag to run a custom Firefox instance with specific preferences and flags:

extension dev --gecko-binary=/path/to/custom-firefox --profile=/path/to/firefox/profile

Or via extension.config.js:

module.exports = {
  browser: {
    firefox: {
      geckoBinary: "/path/to/custom-firefox",
      profile: "/path/to/firefox/profile",
      preferences: {
        homepage: "https://example.com",
      },
      browserFlags: ["--safe-mode"],
    },
  },
};

Best Practices

  • Set Up Profiles: Utilize custom profiles for different users or configurations.
  • Preferences: Use the preferences option to customize browser settings.
  • Flags: Leverage browser flags for specialized environments or behaviors.
  • Binary Paths: Run custom or unsupported browsers by specifying their binary paths.

Next Steps