How to use webext-options-sync with a React options page?

You'll need to manually integrate it by calling getAll() and set() to sync with React state, as the library doesn't natively support React forms. Handle form changes through React events instead of relying on automatic syncForm.

webext-options-sync vs manual chrome.storage: which is better?

webext-options-sync reduces boilerplate and handles migrations automatically, making it ideal for standard WebExtensions. Manual storage is better for complex, custom logic or when you need full control over data serialization and error handling.

How to handle storage quota errors in webext-options-sync?

Listen for the options-sync:save-error event fired on form fields when saves fail, and display user-friendly messages. The library doesn't automatically manage quotas, so you must implement fallback strategies like switching to local storage.

Can I use webext-options-sync with Firefox extensions?

Yes, it's compatible with any WebExtensions browser, but for sync storage in Firefox, you must set browser_specific_settings.gecko.id in the manifest.json, as mentioned in the README's storageType considerations.

How to add custom validation beyond HTML attributes in webext-options-sync?

You'll need to extend or override the syncForm method, as the library only respects built-in HTML validation attributes. Implement additional checks in JavaScript and prevent saves until conditions are met.

What are the performance impacts of webext-options-sync's debounced autosave?

Debouncing input events with a 300ms delay reduces storage writes and improves performance, but it might cause slight delays in saving. For real-time updates, you might need to adjust the debouncing logic manually.

Open-Awesome

webext-options-sync

MITTypeScriptv4.3.0

A JavaScript library for managing and autosaving WebExtension options with built-in migrations and form synchronization.

Visit Website GitHub

158 stars12 forks0 contributors

What is webext-options-sync?

webext-options-sync is a JavaScript library that helps developers manage configuration options in browser extensions. It automates the process of saving, loading, and synchronizing options between storage and UI forms, and includes tools for handling option migrations during extension updates. It solves the problem of writing repetitive boilerplate code for options management in WebExtensions.

Target Audience

Browser extension developers working with Chrome, Firefox, or other WebExtensions-compatible browsers who need a robust solution for handling user preferences and settings.

Value Proposition

Developers choose webext-options-sync because it drastically reduces the amount of custom storage logic needed, provides built-in form synchronization and migration handling, and is specifically tailored for the WebExtensions ecosystem with a simple, promise-based API.

Overview

Helps you manage and autosave your extension's options.

Use Cases

Best For

Adding autosave functionality to extension options pages
Managing default values and migrations for extension updates
Synchronizing form inputs with Chrome storage automatically
Implementing import/export features for extension settings
Handling option changes across background and content scripts
Reducing boilerplate code in WebExtensions projects

Not Ideal For

Extensions using modern UI frameworks (e.g., React, Vue) with custom component-based forms
Projects requiring real-time, multi-user synchronization or server-side option storage
Developers needing fine-grained control over storage serialization or non-JSON data formats
Extensions with minimal options (e.g., a single toggle) where adding a library introduces unnecessary complexity

Pros & Cons

Pros

Automatic Form Synchronization

Automatically loads saved options into HTML forms and saves user changes with debounced input events, eliminating manual event handling boilerplate as described in the README.

Built-in Migration System

Provides a framework for defining migration functions that run on extension updates, ensuring backward compatibility and clean option transformations without manual intervention.

Cross-Context Consistency

Works seamlessly across background scripts and content scripts with a promise-based API, simplifying option access and synchronization across extension contexts.

Import/Export Utilities

Includes ready-made methods for exporting options to JSON files and importing them back, with automatic UI binding for export/import buttons, reducing custom implementation work.

Cons

Storage Quota Limitations

Inherits Chrome storage's strict quotas and JSON serialization constraints, which can cause save errors for extensions with large or complex option sets, as noted in the API documentation.

HTML Form Dependency

Relies heavily on standard HTML form elements and name attributes, making it inflexible for extensions using custom UI components or non-form-based options interfaces.

Setup Complexity for Simple Use

The advanced usage requires multiple script files and manifest.json edits, which can be overkill for trivial storage needs, adding initial setup overhead compared to manual storage handling.

Frequently Asked Questions

Related Projects

webextension-polyfill

A lightweight polyfill library for Promise-based WebExtension APIs in Chrome

Stars3,070

Forks238

Last commit5 months ago

ExtPay

The JavaScript library for ExtensionPay.com — payments for your browser extensions, no server needed.

Stars758

Forks90

Last commit6 days ago

More…

WebExtension packages for every need

Stars140

Forks3

Last commit1 year ago

redux-webext

Redux for WebExtensions

Stars107

Forks15

Last commit4 years ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub