Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/webextension-toolbox/webextension-toolbox

Small CLI toolbox for cross-browser WebExtension development
https://github.com/webextension-toolbox/webextension-toolbox

auto chrome chrome-extension cli-toolbox edge edge-extension firefox firefox-extension opera-extension webextension webextension-toolbox webpack

Last synced: 7 days ago
JSON representation

Small CLI toolbox for cross-browser WebExtension development

Awesome Lists containing this project

README 

        
[](https://www.npmjs.com/package/@webextension-toolbox/webextension-toolbox)



# WebExtension Toolbox



[![npm version](https://badge.fury.io/js/@webextension-toolbox%2Fwebextension-toolbox.svg)](https://badge.fury.io/js/webextension-toolbox%2Fwebextension-toolbox)

[![Node.js CI](https://github.com/webextension-toolbox/webextension-toolbox/actions/workflows/build.yml/badge.svg)](https://github.com/webextension-toolbox/webextension-toolbox/actions/workflows/build.yml)

[![license](https://img.shields.io/npm/l/@webextension-toolbox%2Fwebextension-toolbox.svg)](https://github.com/webextension-toolbox/webextension-toolbox/blob/main/LICENSE)



Small cli toolbox for creating cross-browser WebExtensions.



If you want to get started quickly check out the [yeoman generator](https://github.com/webextension-toolbox/generator-web-extension) for this project.



- [WebExtension Toolbox](#webextension-toolbox)

- [Browser Support](#browser-support)

  - [Official](#official)

  - [Unofficial](#unofficial)

- [Features](#features)

  - [Packing](#packing)

  - [Manifest validation](#manifest-validation)

  - [Manifest defaults](#manifest-defaults)

  - [Typescript Support](#typescript-support)

  - [Manifest vendor keys](#manifest-vendor-keys)

    - [Example](#example)

  - [Polyfill](#polyfill)

- [Usage](#usage)

  - [Install](#install)

      - [Globally](#globally)

      - [Locally](#locally)

  - [Development](#development)

    - [Syntax](#syntax)

    - [Examples](#examples)

  - [Build](#build)

    - [Syntax](#syntax-1)

      - [Building](#building)

      - [Developing](#developing)

  - [.webextensiontoolboxrc](#webextensiontoolboxrc)

  - [Customizing webpack config](#customizing-webpack-config)

- [FAQ](#faq)

  - [What is the difference to web-ext?](#what-is-the-difference-to-web-ext)

  - [How do I use React?](#how-do-i-use-react)

  - [How do I use Typescript?](#how-do-i-use-typescript)

  - [What is SWC?](#what-is-swc)

- [License](#license)



# Browser Support



## Official



These browsers are tested through [github actions](https://github.com/webextension-toolbox/webextension-toolbox/actions/workflows/build.yml)



- 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?](#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](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions) is currently supported on Chrome, Firefox, Edge (Chromium) and Safari ([Safari Web Extension’s Browser Compatibility](https://developer.apple.com/documentation/safariservices/safari_web_extensions/assessing_your_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



```shell

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

```



#### Locally



```shell

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

```



## Development



- Compiles the extension via webpack to `dist/`.

- 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



```shell

$ webextension-toolbox dev  [..options]

```



### Examples



```shell

$ 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/`.

- Minifies extension Code.

- Sets `process.env.NODE_ENV` to `production`.

- Sets `process.env.VENDOR` to the current vendor.

- Packs extension to `packages`.



### Syntax



#### Building



```shell

Usage: build [options] 



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



```shell

Usage: dev [options] 



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  --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.



```js

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](https://webpack.js.org/configuration/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](https://github.com/webextension-toolbox/webextension-toolbox/issues/58) for more information on this



# FAQ



## What is the difference to [web-ext](https://github.com/mozilla/web-ext)?



If want to develop browser extensions for Firefox only [web-ext](https://github.com/mozilla/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.