Package Exports

webext-options-sync

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (webext-options-sync) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

webext-options-sync

Helps you manage and autosave your extension's options.

Main features:

Define your default options
Add autoload and autosave to your options <form>
Run migrations on update

Install

npm install --save webext-options-sync

If you're using a bundler:

import OptionsSync from 'webext-options-sync';

Or just include the file webext-options-sync.js in your manifest.json.

Usage

Options access

Access your saved options from content.js or background.js with:

/* globals OptionsSync */
new OptionsSync().getAll().then(options => {
    console.log('The user’s options are', options);
    if(options.color) {
        document.body.style.color = color;
    }
});

And don't forget to include webext-options-sync in your manifest.json:

{
    "content_scripts": [
        {
            "matches": [
                "https://www.google.com*",
            ],
            "js": [
                "webext-options-sync.js",
                "content.js"
            ]
        }
    ]
}

Defaults definition

Create your options definition file, for example options-init.js:

/* globals OptionsSync */
new OptionsSync().define({
    defaults: {
        yourStringOption: 'green',
        anyBooleans: true,
        numbersAreFine: 9001
        // Open an issue to discuss more complex fields like multiselects
    }
});

Include it in manifest.json as a background script together with webext-options-sync

{
    "background": {
        "scripts": [
            "webext-options-sync.js",
            "options-init.js"
        ]
    }
}

Form autosave and autoload

OptionsSync listens to any field that triggers input or change events. Option names are set via the fields' name attribute. Checkboxes are stored as true/false; other fields are stored as strings.

In your options.html file, include webext-options-sync.js and then enable the sync this way:

/* globals OptionsSync */
new OptionsSync().syncForm(document.querySelector('form#options-form'));

Done. Any defaults or saved options will be loaded into the form and any change will automatically be saved via chrome.storage.sync

In alternative you can put your fields in a custom<options-sync> element instead of <form> and they'll be automatically synchronized. You can specify the storageName via attribute, like:

<options-sync storageName="my-options">
    <input type="color" name="color">
</options-sync>

Warning: Custom Elements are supported by Firefox 63+ (November 2018)

Input validation

If your form fields have any validation attributes they will not be saved until they become valid.

Since autosave and validation is silent, you should inform the user of invalid fields, possibly via CSS by using the :invalid selector:

/* Style the element */
input:invalid {
    color: red;
    border: 1px solid red;
}

/* Or display a custom error message */
input:invalid ~ .error-message {
    display: block;
}

Migrations

In your options-init.js file, extend the call by including an array of functions, for example:

/* globals OptionsSync */
new OptionsSync().define({
    defaults: {
        color: 'red',
    },
    migrations: [
        (savedOptions, currentDefaults) => {
            // perhaps it was renamed
            if(savedOptions.colour) {
                savedOptions.color = savedOptions.colour;
                delete savedOptions.colour;
            }
        },
        OptionsSync.migrations.removeUnused
    ]
});

Notice OptionsSync.migrations.removeUnused: it's a helper method that removes any option that isn't defined in the defaults. It's useful to avoid leaving old options taking up space.

API

const opts = new OptionsSync([storageName])

Returns an instance linked to the chosen storage.

storageName

Type: string
Default: options

The key used to store data in chrome.storage.sync

opts.define(setup)

To be used in the background only, this is used to initiate the options. It's not required but it's recommended as a way to define which options the extension supports.

setup

Type: object

It should follow this format:

{
    defaults: { // recommended
        color: 'blue'
    }, 
    migrations: [ // optional
        savedOptions => {
            if(savedOptions.oldStuff) {
                delete savedOptions.oldStuff
            }
        }
    ],
}

defaults

Type: object

A map of default options as strings or booleans. The keys will have to match the form fields' name attributes.

migrations

Type: array

A list of functions to call when the extension is updated. The function will have this signature: (savedOptions, defaults). In this function, alter the savedOptions. Don't return anything.

opts.getAll()

This returns a Promise that will resolve with all the options stored, as an object.

opts.setAll(options)

This will override all the options stored with your options

options

Type: object

A map of default options as strings or booleans. The keys will have to match the form fields' name attributes.

opts.syncForm(form)

Any defaults or saved options will be loaded into the <form> and any change will automatically be saved via chrome.storage.sync

form

Type: form dom element, string

It's the <form> that needs to be synchronized or a CSS selector (one element). The form fields' name attributes will have to match the option names.

webext-inject-on-install: Automatically add content scripts to existing tabs when your extension is installed
Awesome WebExtensions: A curated list of awesome resources for Web Extensions development