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.

• WebExtension Toolbox
• Browser Support
  • Official
  • Unofficial
• Features
  • Packing
  • Manifest validation
  • Manifest defaults
  • Typescript Support
  • Manifest vendor keys
    • Example
  • Polyfill
• Usage
  • Install
    • Globally
    • Locally
  • Development
    • Syntax
    • Examples
  • Build
    • Syntax
      • Building
      • Developing
  • .webextensiontoolboxrc
  • Customizing webpack config
• FAQ
  • What is the difference to web-ext?
  • How do I use React?
  • How do I use Typescript?
  • What is SWC?
• License

Browser Support

Official

These browsers are tested through github actions

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

Unofficial

These browsers will compile but are not tested

• Internet Explorer (ie)
• iOS Safari (ios_saf)
• Opera Mini (op_mini)
• Android Browser (android)
• Blackberry Browser (bb)
• Opera Mobile (op_mob)
• Chrome for Android (and_chr)
• Firefox for Android (and_ff)
• Internet Explorer Mobile (ie_mob)
• UC Browser (and_uc)
• Samsung Internet (samsung)
• QQ Browser (and_qq)
• Baidu Browser (baidu)
• KaiOS (kaios)

Features

Packing

The build task creates specific bundles for:

• Firefox (.xpi)
• Opera (.crx)

all other bundles are .zip files

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 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:
  --swc                                Use SWC instead of Babel
  -c, --config [config]                specify config file path
  -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")
  --vendor-version [vendorVersion]     last supported vendor (default: current)
  --copy-ignore [copyIgnore...]        Do not copy the files in this list, glob pattern
  --compile-ignore [compileIgnore...]  Do not compile the files in this list, glob pattern
  --no-manifest-validation             Skip Manifest Validation
  --save                               Save config to .webextensiontoolboxrc
  --verbose                            print messages at the beginning and end of incremental build
  --no-minimize                        disables code minification
  -h, --help                           display help for command

Developing

Usage: dev [options] <vendor>

Compiles extension in devmode

Arguments:
  vendor                                The Vendor to compile

Options:
  --swc                                Use SWC instead of Babel
  -c, --config [config]                specify config file path
  -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")
  --vendor-version [vendorVersion]     last supported vendor (default: current)
  --copy-ignore [copyIgnore...]        Do not copy the files in this list, glob pattern
  --compile-ignore [compileIgnore...]  Do not compile the files in this list, glob pattern
  --no-manifest-validation             Skip Manifest Validation
  --save                               Save config to .webextensiontoolboxrc
  --verbose                            print messages at the beginning and end of incremental build
  --no-auto-reload                     Do not inject auto reload scripts into background pages or service workers
  -p, --port [port]                    Define the port for the websocket development server (default: "35729")
  --dev-server [devServer]             use webpack dev server to serve bundled files (default: false)
  -h, --help                           display help for command

.webextensiontoolboxrc

This file is used to configure the WebExtension Toolbox without cli options. You can generate it by running webextension-toolbox <options> --save command. This will take your current cli options and save them to .webextensiontoolboxrc. You can then run webextension-toolbox without any options

Customizing webpack config

In order to extend the usage of webpack, you can define a function that extends its config through 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

What is SWC?

SWC (stands for Speedy Web Compiler) is a super-fast TypeScript / JavaScript compiler written in Rust. It's an alternative to Babel. For more informaiton see: https://github.com/swc-project/swc

License

Copyright 2018-2023 Henrik Wenz

This project is free software released under the MIT license.