Running Browsers From Binary#

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 --chromiumBinary or --geckoBinary 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 --chromiumBinary or --geckoBinary 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:

Example Configuration#

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

extension dev --geckoBinary=/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#

• Check out the browser preferences to further configure your environment.