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

You can just download the standalone bundle (it might take a minute to download) and include the file in your manifest.json, or:

npm install --save webext-options-sync

import OptionsSync from 'webext-options-sync';

const OptionsSync = require('webext-options-sync');

Usage

This module requires the storage permission:

// manifest.json
{
  "permissions": [
    "storage"
  ]
}

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({
    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

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({
    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 optionsStorage = new OptionsSync([setup])

setup

Type: object

Optional. It should follow this format:

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

Returns an instance linked to the chosen storage.

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 run in the background when the extension is updated. Example:

{
    migrations: [
        (savedOptions, defaults) => {
            // Change the `savedOptions`
            if(savedOptions.oldStuff) {
                delete savedOptions.oldStuff
            }

            // No return needed
        }
    ],
}

storageName

Type: string Default: 'options'

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

logging

Type: boolean Default: true

Whether info and warnings (on sync, updating form, etc.) should be logged to the console or not.

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-storage-cache - Map-like promised cache storage with expiration.
webext-domain-permission-toggle - Browser-action context menu to request permission for the current tab.
webext-dynamic-content-scripts - Automatically inject your content_scripts on custom domains.
webext-detect-page - Detects where the current browser extension code is being run.
webext-content-script-ping - One-file interface to detect whether your content script have loaded.
Awesome WebExtensions: A curated list of awesome resources for Web Extensions development