{"id":49704,"library":"webext-storage","title":"webext-storage","description":"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.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/fregante/webext-storage","tags":["javascript","browser","extension","chrome","firefox","safari","webextension","storage","session","typescript"],"install":[{"cmd":"npm install webext-storage","lang":"bash","label":"npm"},{"cmd":"yarn add webext-storage","lang":"bash","label":"yarn"},{"cmd":"pnpm add webext-storage","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only; CJS require will fail. TypeScript types included.","wrong":"const { StorageItem } = require('webext-storage')","symbol":"StorageItem","correct":"import { StorageItem } from 'webext-storage'"},{"note":"Named export only, not default. Also ESM-only.","wrong":"import StorageItemMap from 'webext-storage'","symbol":"StorageItemMap","correct":"import { StorageItemMap } from 'webext-storage'"},{"note":"There is no default export; only named exports exist. This pattern will cause undefined.","wrong":"import { default } from 'webext-storage'","symbol":"default export","correct":"import webextStorage from 'webext-storage'"}],"quickstart":{"code":"import { StorageItem } from 'webext-storage';\n\nconst options = new StorageItem('user-options', {\n  area: 'local',\n  defaultValue: { theme: 'light' } as Record<string, string>,\n});\n\nasync function init() {\n  const value = await options.get(); // type is Record<string, string>\n  console.log('Current options', value);\n  await options.set({ theme: 'dark' });\n  options.onChanged((newValue) => {\n    console.log('Options updated to', newValue);\n  });\n}\ninit().catch(console.error);","lang":"typescript","description":"Creates a typed StorageItem for user options with default value, demonstrates get/set and change listener."},"warnings":[{"fix":"Use import syntax and ensure your project is configured for ESM (e.g., type: module in package.json).","message":"Version 3.0.0 removed CommonJS support; package is now ESM-only.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update constructor calls: new StorageItem(key, { area, defaultValue }) instead of new StorageItem(key, defaultValue, area).","message":"Version 2.0.0 changed StorageItem constructor signature; area option moved to options object.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use .delete() to explicitly remove a key, or set to null if you want to store null.","message":"Calling .set(undefined) on a StorageItem deletes the key from storage, which is different from native chrome.storage that ignores undefined values.","severity":"gotcha","affected_versions":"all"},{"fix":"Access previous value by storing it externally before the change, or use native chrome.storage.onChanged which provides both new and old values.","message":"onChanged listener does not receive the old value in the callback; only the new value is provided.","severity":"gotcha","affected_versions":"all"},{"fix":"Watch for breaking changes when upgrading minor versions.","message":"StorageItemMap is in beta and may change in future releases.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'3.1.0':17 'altern':41 'api':8,48 'avoid':50 'boilerpl':52 'browser':60 'call':56 'chang':37 'chrome':62 'chrome.storage':55 'chrome.storage.local':14 'current':15 'default':34 'esm':57 'extens':11,61 'firefox':63 'javascript':59 'like':42 'listen':38 'map':30 'month':20 'nativ':54 'polyfil':45 'provid':22 'releas':19 'safari':64 'safeti':33 'session':67 'singl':25 'smaller':39 'stabl':18 'storag':3,7,47,66 'storageitem':23 'storageitemmap':28 'type':5,32 'typescript':68 'usabl':6 'valu':26,35 'version':16 'web':10 'webext':2 'webext-storag':1 'webextens':44,65 'webextension-polyfil':43 'wrap':13","created_at":"2026-06-07T17:03:10.654075+00:00","updated_at":"2026-06-07T17:03:10.654075+00:00","problems":[{"fix":"Add \"type\": \"module\" to your package.json or rename file to .mjs.","cause":"The package is ESM-only, but the project is not configured for ESM.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use: import { StorageItem } from 'webext-storage'","cause":"Incorrect import syntax: using default import or require instead of named import.","error":"TypeError: StorageItem is not a constructor"},{"fix":"Ensure your code runs only in extension contexts (background, popup, options, content scripts) and that the 'storage' permission is declared in manifest.json.","cause":"StorageItem constructor failed because the chrome.storage API is not available (e.g., not running in extension context).","error":"Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'get')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/fregante/webext-storage#readme","github":"https://github.com/fregante/webext-storage","docs":null,"changelog":null,"pypi":null,"npm":"webext-storage","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}