npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

webext-options-sync

v4.3.0

Published

Helps you manage and autosave your extension's options.

Downloads

2,680

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
  • Import/export helpers

This also lets you very easily have separate options for each domain with the help of webext-options-sync-per-domain.

Install

You can download the standalone bundle and include it in your manifest.json.

Or use npm:

npm install webext-options-sync
import OptionsSync from 'webext-options-sync';

The browser-extension-template repo includes a complete setup with ES Modules, based on the advanced usage below.

Usage

This module requires the storage permission in manifest.json:

{
	"name": "My Cool Extension",
	"permissions": [
		"storage"
	]
}

Simple usage

You can set and get your options from any context (background, content script, etc):

/* global OptionsSync */
const optionsStorage = new OptionsSync();

await optionsStorage.set({showStars: 10});

const options = await optionsStorage.getAll();
// {showStars: 10}

Note: OptionsSync relies on chrome.storage.sync, so its limitations apply, both the size limit and the type of data stored (which must be compatible with JSON).

Advanced usage

It's suggested to create an options-storage.js file with your defaults and possible migrations, and import it where needed:

/* global OptionsSync */
window.optionsStorage = new OptionsSync({
	defaults: {
		colorString: 'green',
		anyBooleans: true,
		numbersAreFine: 9001
	},

	// List of functions that are called when the extension is updated
	migrations: [
		(savedOptions, currentDefaults) => {
			// Perhaps it was renamed
			if (savedOptions.colour) {
				savedOptions.color = savedOptions.colour;
				delete savedOptions.colour;
			}
		},

		// Integrated utility that drops any properties that don't appear in the defaults
		OptionsSync.migrations.removeUnused
	]
});

Include this file as a background script: it's where the defaults are set for the first time and where the migrations are run. This example also includes it in the content script, if you need it there:

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

Then you can use it this way from the background or content.js:

/* global optionsStorage */
async function init () {
	const {colorString} = await optionsStorage.getAll();
	document.body.style.background = colorString;
}

init();

And also enable autosaving in your options page:

<!-- Your options.html -->
<form>
	<label>Color: <input name="colorString"/></label><br>
	<label>Show: <input type="checkbox" name="anyBooleans"/></label><br>
	<label>Stars: <input name="numbersAreFine"/></label><br>
</form>

<script src="webext-options-sync.js"></script>
<script src="options-storage.js"></script>
<script src="options.js"></script>
// Your options.js file
/* global optionsStorage */

optionsStorage.syncForm(document.querySelector('form'));

Form autosave and autoload

When using the syncForm method, OptionsSync will serialize the form using dom-form-serializer, which uses the name attribute as key for your options. Refer to its readme for more info on the structure of the data.

Any user changes to the form are automatically saved into chrome.storage.sync after 300ms (debounced). It listens to input events.

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;
}

API

const optionsStorage = new OptionsSync(setup?)

Returns an instance linked to the chosen storage. It will also run any migrations if it's called in the background.

setup

Type: object

Optional. 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 options form fields' name attributes.

migrations

Type: array

A list of functions to run in the background when the extension is updated. Example:

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

			// No return needed
		},

		// Integrated utility that drops any properties that don't appear in the defaults
		OptionsSync.migrations.removeUnused
	],
}

[!NOTE] The options argument will always include the defaults as well as any options that were saved before the update.

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.

storageType

Type: 'local' | 'sync' Default: sync

What storage area type to use (sync storage vs local storage). Sync storage is used by default.

Considerations for selecting which option to use:

  • Sync is default as it's likely more convenient for users.
  • Firefox requires browser_specific_settings.gecko.id for the sync storage to work locally.
  • Sync storage is subject to much tighter quota limitations, and may cause privacy concerns if the data being stored is confidential.

optionsStorage.set(options)

This will merge the existing options with the object provided.

Note: Any values specified in default are not saved into the storage, to save space, but they will still appear when using getAll. You just have to make sure to always specify the same defaults object in every context (this happens automatically in the Advanced usage above.)

options

Type: object Default: {} Example: {color: red}

A map of default options as strings, booleans, numbers and anything accepted by dom-form-serializer’s deserialize function.

optionsStorage.setAll(options)

This will override all the options stored with your options.

optionsStorage.getAll()

This returns a Promise that will resolve with all the options.

optionsStorage.onChanged(callback, signal?)

Listens to changes in the storage and calls the callback when the options are changed. The callback is called with the new and old options.

callback

Type: (newOptions: object, oldOptions: object) => void

signal

Type: AbortSignal

If provided, the callback will be removed when the signal is aborted.

optionsStorage.syncForm(form)

Any defaults or saved options will be loaded into the <form> and any change will automatically be saved via chrome.storage.sync. It also looks for any buttons with js-import or js-export classes that when clicked will allow the user to export and import the options to a JSON file.

  • options-sync:save-success: Fired on the edited field when the form is saved.
  • options-sync:save-error: Fired on the edited field when the form is not saved due to an error. The error is passed as the detail property.

Saving can fail when the storage quota is exceeded for example. You should handle this case and display a message to the user.

form

Type: HTMLFormElement, 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.

optionsStorage.stopSyncForm()

Removes any listeners added by syncForm.

optionsStorage.exportToFile()

Opens the browser’s "save file" dialog to export options to a JSON file. If your form has a .js-export element, this listener will be attached automatically.

optionsStorage.importFromFile()

Opens the browser’s file picker to import options from a previously-saved JSON file. If your form has a .js-import element, this listener will be attached automatically.

Related