A cookiecutter template for web-extension with webpack integration
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
hooks Initial commit Nov 24, 2017
{{cookiecutter.project_slug}} Initial commit Nov 24, 2017
LICENSE Added a LICENSE file Nov 25, 2017
README.md README title fix Nov 25, 2017
cookiecutter.json Initial commit Nov 24, 2017

README.md

cookiecutter-web-extension-webpack

A cookiecutter template for Web Extensions with webpack integration and a simple preferences system.

Overwiew

This template bootstraps a new Web Extension with two noticeable features:

  • Webpack integration. Your source code lives in a separate directory and is packed to your extension distribution directory.
  • Simple preferences system. A simple, yet good enough, system for extension preferences. Just fill out a JSON file with your project settings and you're good to go!

Usage

Clone this repository and run cookiecutter on it, or load directly this repository through cookiecutter.

Project layout

Your generated project looks like this:

.
├── addon                 (The extension itself)
│   ├── icons             (Your project icons)
│   │   ├── icon-48.png
│   │   └── icon-96.png
│   └── options
│       └── options.html  (The preferences files)
├── .eslintrc.json
├── .gitignore
├── LICENSE               (Empty file, fill this out with your license)
├── Makefile              (See below)
├── package.json
├── README.md             (Almost empty ;)
├── src
│   ├── browser
│   │   └── options.js    (The JS file used by options.html)
│   ├── lib
│   │   └── settings.js   (Settings library)
│   └── settings.json     (Extension default settings, see below)
├── webext-manifest.json  (This file will become addon/manifest.json upon building)
└── webpack.config.js

Makefile targets

Your project management goes through a Makefile with the following targets:

  • make init
    Run yarn or npm install.
  • make source-lint
    Run eslint on your code in src.
  • make source-build
    Run webpack on your code and create the needed files in addon.
  • make moz-lint
    Run the target source-lint, source-build then web-ext lint.
  • make moz-run
    Build your source code and launch Firefox so you can test your extension. While developing, you don't need to reload, files are watched and both webpack and firefox will reload everything they need to upon any change.
  • make moz-pack
    Sign your extension with web-ext sign.
  • make chrome-run
    Build your source code and launch Chrome or Chromium. While webpack will rebuild sources when needed, you'll have to reload the extension in Chrome interface.
  • make chrome-pack
    Create a zip file of your extension.
  • make lint
    Run source-lint, source-build and moz-lint targets.
  • make clean
    Remove generated files in addon directory.

Default extension settings

The file src/settings.json provides your settings layout and configuration. The file's content is used by the settings library and gives you the following:

  • A comprehensive setting list
  • Default values, for you're going to add new settings over time and you don't want to break your extension :)

The settings.json file's content is a dictionary of settings, each one having the following values:

  • default: the default value
  • type: could be one of text, textarea, checkbox, radio, select
  • label: the option label
  • choices: only for radio and select types. A dictionary of label/value.

Play with your src/settings.json to see how it works.

Each defined option will be available in your extension settings page.

To access those settings in your code, use something like this:

// We assume your file is in src/lib
import {getSettings} from './settings';

getSettings().then(result => {
    // result contains your extension settings
    // and default values when nothing was found
});

Environment variables

The web-ext command use some environment variables. Here are the most important:

  • WEB_EXT_FIREFOX_BINARY: Use it if web-ext can't find your Firefox binary
  • WEB_EXT_API_KEY: Your Mozilla API Key (only if you plan to sign your addon)
  • WEB_EXT_API_SECRET: Your Mozilla API Secret (only if you plan to sign your addon)

Happy hacking!