Docs
Blog
Docs
Blog
firefox icongecko icon

Browser Preferences

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.

Extension.js allows you to customize browser preferences for Firefox and other Gecko-based browsers. These preferences can be configured through the preferences property in the extension.config.js file, which then adds the custom preferences to the browser's user profile during development.

How Does It Work?

Browser preferences are settings that can be configured to customize the behavior of the browser. Extension.js will hook into the browser's profile directory and modify the preferences file to set the custom preferences you define in the configuration file.

How to Set Custom Preferences

To set custom preferences, add a preferences key to the browser configuration in your extension.config.js. These preferences will be passed to the browser during the development process, modifying its behavior according to your configuration.

Example Configuration

Here is an example of how you can set custom preferences for Firefox and Gecko-based browsers in your extension.config.js:

module.exports = {
  browser: {
    firefox: {
      preferences: {
        "browser.startup.homepage": "https://developer.mozilla.org",
        "devtools.theme": "dark",
        "dom.webnotifications.enabled": false,
      },
    },
  },
};

In this example:

  • browser.startup.homepage sets the default homepage for Firefox.
  • devtools.theme sets the theme of the developer tools to dark mode.
  • dom.webnotifications.enabled disables web notifications.

Using Preferences in the Configuration File

Below is the interface for configuring browser preferences within your extension.config.js:

interface DevOptions {
  browser: "firefox" | "gecko-based";
  preferences?: Record<string, any>;
}

Note from the Author: The preferences object can contain any key-value pair that is valid for the browser's preferences. While it is theoretically possible to set any preference on Chromium-based browsers, there is no guarantee that all preferences will work as expected.

This allows you to customize preferences like the homepage, DevTools configuration, or disable certain browser features like web notifications.

Example with Custom Profile

You can also specify a custom profile for Firefox using the profile option along with preferences:

module.exports = {
  browser: {
    firefox: {
      profile: "path/to/custom-profile",
      preferences: {
        "browser.startup.homepage": "https://example.com",
      },
    },
  },
};

More Detailed Preferences

For a comprehensive list of available Firefox preferences, you can explore the Firefox source code where many default preferences are defined in all.js or firefox.js.

Best Practices

  • Use Custom Profiles: It is a good idea to use separate profiles for different browsers during development to keep testing environments isolated.
  • Set Browser-Specific Preferences: Customize browser preferences to optimize your development environment, such as disabling web notifications or setting custom homepages.

Next Steps