Skip to content

webextension-toolbox/webextension-toolbox

Repository files navigation

WebExtension Toolbox

npm version Node.js CI license

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

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.