m0a / webextension-toolbox

Small cli toolbox for creating cross-browser WebExtensions.

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 (polyfill)
• opera (polyfill)
• firefox
• edge

Features

react.js

Works with react.js out of the box!

packing

The build task creates bundles for:

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

manifest validation

Validates your manifest.json while compiling.

manifest defaults

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

manifest vendor keys

Allows you to define vendor specific manifest keys.

Example: manifest.json

...
"name": "my-extension"
"__chrome__key": "yourchromekey"
...

If the vendor is chrome it compiles to:

...
"name": "my-extension"
"key": "yourchromekey"
...

else it compiles to:

...
"name": "my-extension"
...

polyfill

The webextension standard is currently only supported by firefox and edge. This toolbox adds the necessary polyfills for chrome and opera.

This way many webextension apis will work in chrome and opera out of the box.

In addition to that, this toolbox comes with babel-preset-env.

Usage

Install

$ npm install -g webextension-toolbox

Development

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

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

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

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

Examples

$ webextension-toolbox build --help
$ webextension-toolbox build chrome
$ webextension-toolbox build firefox
$ webextension-toolbox build opera
$ webextension-toolbox build edge

Node.js API

const { compile } = require('webextension-toolbox')

const compiler = compile({
  vendor: 'chrome',
  src: 'app',
  target: 'build/[vendor]',
  packageTarget: 'packages',
  dev: false,
  devtool: false,
  autoReload: false,
  copyIgnore: [ '**/*.js', '**/*.json', '!_locales/**/*.json' ],
  pack: false
})

compiler.run((error, stats) => console.log(error, stats))

// or

compiler.watch({}, (error, stats) => console.log(error, stats))

Browser API

Always use the webextension browser api. Webextension-Toolbox will polyfill it for you in chrome and opera.

Entry points

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

"app/background.js"               -> "dist/<vendor>/dist/background.js"
"app/scripts/background.js"       -> "dist/<vendor>/dist/scripts/background.js"
"app/someDir/someFile.js"         -> Will be ignored.

License

Copyright 2018 Henrik Wenz

This project is free software released under the MIT license.