Docs
Blog
Docs
Blog

Extension Config (extension.config.js)

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.

The extension.config.js file enables developers to adjust the behavior of Extension.js. This configuration file provides flexibility by enabling browser-specific configurations, command customization, and support for the massive ecosystem of webpack loaders and plugins.

How Does It Work?

Adding a extension.config.js file at the same level as your manifest.json file will extend the capabilities of Extension.js. The config file includes the following keys:

Key Description
browser Defines browser-specific configurations.
commands Customizes command behavior (dev, preview, build).
config Modifies the webpack configuration for added flexibility.

Browser Configuration

The browser key allows setting up browser-specific preferences, profiles, binaries, and flags. Below is an example configuration for Chrome and Firefox:

browser: {
  chrome: {
    profile: 'path/to/profile',
    preferences: { darkMode: true },
    browserFlags: ['--disable-web-security'],
    chromeBinary: 'path/to/custom/chrome',
  },
  firefox: {
    geckoBinary: 'path/to/custom/firefox',
  }
}
Property Description Example
profile Specifies the path to the browser profile. 'path/to/profile'
preferences Customizes preferences such as dark mode. { darkMode: true }
browserFlags Adds flags to the browser launch process. ['--disable-web-security']
chromeBinary Sets a custom Chrome binary path. 'path/to/custom/chrome'
geckoBinary Sets a custom Firefox binary path. 'path/to/custom/firefox'

Commands Configuration

Use the commands key to customize how Extension.js runs commands like dev, preview, and build. Here's an example:

commands: {
  dev: {
    browser: 'chrome',
    polyfill: true,
  },
  build: {
    zipFilename: 'my-extension.zip',
    zip: true,
    zipSource: true,
  }
}
Property Description Example
browser Specifies the browser for dev or preview mode. 'chrome'
polyfill Enables polyfills for legacy browser compatibility. true
zipFilename Sets the filename for the output zip file during build. 'my-extension.zip'
zip Enables zipping the extension in build process. true
zipSource Includes the source code in the zip file. true

Webpack Configuration

The config key allows you to modify the default webpack configuration. This gives you the power to add additional loaders or plugins:

config: (config) => {
  config.module.rules.push({
    test: /\.mdx$/,
    use: ["babel-loader", "@mdx-js/loader"],
  });
  return config;
};

Full Sample extension.config.js

Below are sample configurations for the different sections in extension.config.js.

Browser Configuration Sample

module.exports = {
  browser: {
    chrome: {
      profile: "path/to/chrome/profile",
      preferences: { theme: "dark" },
      browserFlags: ["--disable-extensions"],
      chromeBinary: "path/to/custom/chrome",
    },
    firefox: {
      profile: "path/to/firefox/profile",
      preferences: { darkMode: true },
      geckoBinary: "path/to/custom/firefox",
    },
  },
};

Commands Configuration Sample

module.exports = {
  commands: {
    dev: {
      browser: "chrome",
      profile: "path/to/chrome/profile",
      polyfill: true,
      port: 8080,
      noOpen: false,
    },
    preview: {
      browser: "firefox",
      profile: "path/to/firefox/profile",
    },
    build: {
      zipFilename: "extension.zip",
      zip: true,
      zipSource: true,
      silent: true,
    },
  },
};

Webpack Configuration Sample

For the webpack configuration sample, see Webpack Configuration.

The extension.config.js types are defined here.

Best Practices

  • Use the extension.config.js file: Leverage the extension.config.js file to customize your extension's behavior.
  • Separate browser-specific configurations: Keep browser-specific configurations in the browser key.
  • Customize commands: Use the commands key to adjust the behavior of commands like dev, preview, and build.

Next Steps