Registry / storage / webext-storage-cache

webext-storage-cache

library6.0.3jsnpmunverified

A caching library for Web Extensions (Chrome, Firefox, Safari) with support for expired cache clearing. Version 6.0.3 is the latest stable release, actively maintained by the author (fregante). It provides two main APIs: CachedValue for simple get/set operations, and CachedFunction for memoizing function calls automatically. The library requires the `storage` permission and optionally `alarms` for scheduled cache purging. It ships TypeScript types and works with both Manifest v2 and v3. The deprecated legacy API from v5 is still available via `webext-storage-cache/legacy.js`. Key differentiators from general Node.js caching libraries: it is specifically designed for browser extensions, uses `chrome.storage` under the hood, and handles cross-context caching (background, content scripts, popup).

storage

npm install webext-storage-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBEXT-STORAGE-CAC

webext-storage-cache

storagejavascriptv6.0.3

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.

CachedValue

✓ import { CachedValue } from 'webext-storage-cache'

✗ import CachedValue from 'webext-storage-cache'

CachedValue is a named export, not default.

CachedFunction

✓ import { CachedFunction } from 'webext-storage-cache'

✗ const CachedFunction = require('webext-storage-cache').CachedFunction

ESM-only package; require() will not work.

globalCache

✓ import { globalCache } from 'webext-storage-cache'

✗ import globalCache from 'webext-storage-cache/global'

globalCache is a named export, not default. Subpath imports are not valid.

Shows basic usage of CachedValue: check cache, fetch data, store, and retrieve.

// manifest.json must include permissions: ["storage", "alarms"] import { CachedValue } from 'webext-storage-cache'; async function main() { const cache = new CachedValue('myKey', { maxAge: { hours: 1 } }); if (!(await cache.isCached())) { const data = await fetchDataFromApi(); await cache.set(data); } const result = await cache.get(); console.log(result); } main();

Debug

Known issues

deprecatedThe legacy API (cache.get, cache.set) from v5 is deprecated and will be removed in v7. Use CachedValue or CachedFunction instead.

fix

Migrate to CachedValue or CachedFunction. See https://github.com/fregante/webext-storage-cache/releases/v6.0.0

affects: >=6.0.0

breakingIn v6, the package became ESM-only. CommonJS require() will not work.

fix

Switch to ESM imports (import { ... } from 'webext-storage-cache') or use dynamic import().

affects: >=6.0.0

breakingIn v6, the legacy API is moved to 'webext-storage-cache/legacy.js'. The main export no longer includes cache.get/cache.set.

fix

Use import cache from 'webext-storage-cache/legacy.js' to access legacy API, or migrate to new API.

affects: >=6.0.0

gotchaCachedFunction requires the 'alarms' permission for scheduled cache purging; otherwise, expired items may not be cleared until the extension restarts.

fix

Add 'alarms' permission to manifest.json and import the module in the background script.

affects: >=6.0.0

gotchaCachedValue and CachedFunction must be instantiated with a unique key per cache entry. Using the same key across different contexts (e.g., content script and background page) may cause conflicts.

fix

Use unique keys with prefixing for each context (e.g., 'content:myKey' vs 'background:myKey').

affects: >=6.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'storage')

Running code in a context where chrome.storage is not available (e.g., Node.js, or missing permissions).

fix

Ensure you are running the code inside a Web Extension (background, content script, popup) and have 'storage' permission in manifest.json.

Uncaught SyntaxError: The requested module 'webext-storage-cache' does not provide an export named 'default'

Trying to use a default import when the package only has named exports.

fix

Use import { CachedValue } from 'webext-storage-cache' instead of import CachedValue from 'webext-storage-cache'.

Error: The 'alarms' permission is required to schedule cache purging. Add 'alarms' to your manifest permissions and import the module in the background script.

Missing alarms permission in manifest.json.

fix

Add 'alarms' to permissions in manifest.json and ensure the module is imported in the background script.

Upgrade

Version history

6.0.3latest on npm

Audit

Dependencies

webextension-polyfilloptionalRequired for cross-browser compatibility with `chrome.storage` and `chrome.alarms`

Agent activity

30 hits · last 30 days

node

Resources

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

packagewebext-storage-cache ↗

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