@webextension-toolbox/webextension-toolbox

WebExtension Toolbox

Small cli toolbox for creating cross-browser WebExtensions.

If you want to get started quickly check out the yeoman generator for this project.

Browser Support

• Chrome (chrome)
• Opera (opera)
• Edge (edge)
• Firefox (firefox)
• Safari (safari)

Features

Packing

The build task creates bundles for:

• Firefox (.xpi)
• Chrome (.zip)
• Opera (.crx)
• Edge (.zip)
• Safari (.zip)

Manifest validation

Validates your manifest.json while compiling.

You can skip this by adding --validateManifest to your build or dev command.

Manifest defaults

Uses default fields (name, version, description) from your package.json

Typescript Support

Native typescript support (but not enforced!) (see section How do I use Typescript?)

Manifest vendor keys

Allows you to define vendor specific manifest keys.

Example

manifest.json

"name": "my-extension",
"__chrome__key": "yourchromekey",
"__chrome|opera__key2": "yourblinkkey"

If the vendor is chrome it compiles to:

"name": "my-extension",
"key": "yourchromekey",
"key2": "yourblinkkey"

If the vendor is opera it compiles to:

"name": "my-extension",
"key2": "yourblinkkey"

else it compiles to:

"name": "my-extension"

Polyfill

The WebExtension specification is currently supported on Chrome, Firefox, Edge (Chromium) and Safari (Safari Web Extension’s Browser Compatibility).

This toolbox no longer provides any polyfills for cross-browser support. If you need polyfills e.g. between 'browser' and 'chrome', we recommend detecting the browser during the build time using process.env.VENDOR.

This toolbox comes with babel-preset-env. Feel free add custom configuration if you need any custom polyfills.

Usage

Install

Globally

$ npm install -g @webextension-toolbox/webextension-toolbox

Locally

$ npm install -D @webextension-toolbox/webextension-toolbox

Development

• Compiles the extension via webpack to dist/<vendor>.
• Watches all extension files and recompiles on demand.
• Reloads extension or extension page as soon something changed.
• Sets process.env.NODE_ENV to development.
• Sets process.env.VENDOR to the current vendor.

Syntax

$ webextension-toolbox dev <vendor> [..options]

Examples

$ webextension-toolbox dev --help
$ webextension-toolbox dev chrome
$ webextension-toolbox dev firefox
$ webextension-toolbox dev opera
$ webextension-toolbox dev edge
$ webextension-toolbox dev safari

Build

• Compile extension via webpack to dist/<vendor>.
• Minifies extension Code.
• Sets process.env.NODE_ENV to production.
• Sets process.env.VENDOR to the current vendor.
• Packs extension to packages.

Syntax

Building

Usage: build [options] <vendor>

Compiles extension for production

Options:
  -c, --config [config]                 specify config file path (default: "./webextension-toolbox.config.js")
  -s, --src [src]                       specify source directory (default: "app")
  -t, --target [target]                 specify target directory (default: "dist/[vendor]")
  -d, --devtool [string | false]        controls if and how source maps are generated (default: false)
  --no-minimize                         disables code minification
  -v, --vendor-version [vendorVersion]  last supported vendor (default: current)
  --no-manifest-validation              validate manifest syntax
  -h, --help                            display help for command

Developing

Usage: dev [options] <vendor>

Compiles extension in devmode

Arguments:
  vendor                                The Vendor to compile

Options:
  -c, --config [config]                 specify config file path (default: "./webextension-toolbox.config.js")
  -s, --src [src]                       specify source directory (default: "app")
  -t, --target [target]                 specify target directory (default: "dist/[vendor]")
  -d, --devtool [string | false]        controls if and how source maps are generated (default: "cheap-source-map")
  -r, --no-auto-reload                  Do not inject auto reload scripts into background objects
  -p, --port [port]                     Define the port for the websocket development server (default: "35729")
  -v, --vendor-version [vendorVersion]  last supported vendor (default: current)
  --dev-server [devServer]              use webpack dev server to serve bundled files (default: false)
  --no-manifest-validation              Skip Manifest Validation
  --verbose                             print messages at the beginning and end of incremental build
  -h, --help                            display help for command

Entry points

All javascript files located at the root of your ./app or ./app/scripts directory will create a separate bundle.

app	dist
app/background.js	dist/<vendor>/background.js
app/scripts/background.js	dist/<vendor>/scripts/background.js
app/some-dir/some-file.js	Will be ignored as entry file.
app/scripts/some-dir/some-file.js	Will be ignored as entry file.

Customizing webpack config

In order to extend the usage of webpack, you can define a function that extends its config via webextension-toolbox.config.js (or a file you define through the usage of the -c option) in your project root.

module.exports = {
  webpack: (config, { dev, vendor }) => {
    // Perform customizations to webpack config

    // Important: return the modified config
    return config;
  },
};

As WebExtension Toolbox uses webpack’s devtool feature under the hood, you can also customize the desired devtool with the --devtool argument.

For example, if you have problems with source maps on Firefox, you can try the following command:

webextension-toolbox build firefox --devtool=inline-cheap-source-map

Please see Issue #58 for more information on this

FAQ

What is the difference to web-ext?

If want to develop browser extensions for Firefox only web-ext might be a better fit for you, since it supports, extension signing, better manifest validation and auto mounting.

Nevertheless if you want to develop cross browser extensions using

• the same development experience in every browser
• a single codebase
• custom webpack configuration

webextension-toolbox might be your tool of choice.

How do I use React?

1. npm install @babel/preset-react --save-dev
2. Create a .babelrc file next to your package.json file and insert the following contents:

{
  "presets": [
    "@babel/preset-react"
  ]
}

How do I use Typescript?

1. npm install typescript --save-dev
2. Run tsc --init or manually add a tsconfig.json file to your project root

License

Copyright 2018-2022 Henrik Wenz

This project is free software released under the MIT license.

Changelog

[5.1.1] - 2021-04-11

Fixed

• Target resolution was incorrect and thus detroying most of the built modules

Changes

• In the past the node option was set to false in webpack config to prevent security issues with usage of eval (See https://github.com/webextension-toolbox/webextension-toolbox/pull/34). This was resolved at the end of life of webpack 4 and does not exist in webpack 5. This option is now set to true by default (not set). This means global is now set by webpack itself. If you want to disable this behavior you can set the node option to false in your webpack config. See: https://webpack.js.org/configuration/node/
• Clean webpack plugin was removed in favor of https://webpack.js.org/guides/output-management/#cleaning-up-the-dist-folder which is native in webpack 5.