webext-storage

library3.1.0jsnpmunverified

A typed, usable storage API for Web Extensions that wraps chrome.storage.local. Current version 3.1.0 (stable), released monthly. It provides StorageItem for single values and StorageItemMap for maps, with type safety, default values, and change listeners. Smaller than alternatives like webextension-polyfill's storage API, and avoids the boilerplate of native chrome.storage calls. ESM only.

storage

npm install webext-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBEXT-STORAGE

webext-storage

storagejavascriptv3.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StorageItem

✓ import { StorageItem } from 'webext-storage'

✗ const { StorageItem } = require('webext-storage')

ESM-only; CJS require will fail. TypeScript types included.

StorageItemMap

✓ import { StorageItemMap } from 'webext-storage'

✗ import StorageItemMap from 'webext-storage'

Named export only, not default. Also ESM-only.

default export

✓ import webextStorage from 'webext-storage'

✗ import { default } from 'webext-storage'

There is no default export; only named exports exist. This pattern will cause undefined.

Creates a typed StorageItem for user options with default value, demonstrates get/set and change listener.

import { StorageItem } from 'webext-storage'; const options = new StorageItem('user-options', { area: 'local', defaultValue: { theme: 'light' } as Record<string, string>, }); async function init() { const value = await options.get(); // type is Record<string, string> console.log('Current options', value); await options.set({ theme: 'dark' }); options.onChanged((newValue) => { console.log('Options updated to', newValue); }); } init().catch(console.error);

Debug

Known issues

breakingVersion 3.0.0 removed CommonJS support; package is now ESM-only.

fix

Use import syntax and ensure your project is configured for ESM (e.g., type: module in package.json).

affects: >=3.0.0

breakingVersion 2.0.0 changed StorageItem constructor signature; area option moved to options object.

fix

Update constructor calls: new StorageItem(key, { area, defaultValue }) instead of new StorageItem(key, defaultValue, area).

affects: >=2.0.0

gotchaCalling .set(undefined) on a StorageItem deletes the key from storage, which is different from native chrome.storage that ignores undefined values.

fix

Use .delete() to explicitly remove a key, or set to null if you want to store null.

affects: all

gotchaonChanged listener does not receive the old value in the callback; only the new value is provided.

fix

Access previous value by storing it externally before the change, or use native chrome.storage.onChanged which provides both new and old values.

affects: all

deprecatedStorageItemMap is in beta and may change in future releases.

fix

Watch for breaking changes when upgrading minor versions.

affects: >=3.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

The package is ESM-only, but the project is not configured for ESM.

fix

Add "type": "module" to your package.json or rename file to .mjs.

TypeError: StorageItem is not a constructor

Incorrect import syntax: using default import or require instead of named import.

fix

Use: import { StorageItem } from 'webext-storage'

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'get')

StorageItem constructor failed because the chrome.storage API is not available (e.g., not running in extension context).

fix

Ensure your code runs only in extension contexts (background, popup, options, content scripts) and that the 'storage' permission is declared in manifest.json.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

47 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fregante/webext-storage ↗

packagewebext-storage ↗

homepagehttps://github.com/fregante/webext-storage#readme ↗