Registry / storage / local-storage-fallback

local-storage-fallback

library5.0.0jsnpmunverified

A browser storage adapter that automatically falls back through localStorage, sessionStorage, cookies, and in-memory storage, depending on what is available and not throwing exceptions (e.g., in private browsing mode). Current stable version is 5.0.0. Maintained infrequently. Key differentiator: handles private browsing and quota errors gracefully where native localStorage would throw, and provides a unified API across all backends. Fully typed with TypeScript definitions.

storage

npm install local-storage-fallback

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOCAL-STORAGE-FALL

local-storage-fallback

storagejavascriptv5.0.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.

default (storage)

✓ import storage from 'local-storage-fallback'

✗ const storage = require('local-storage-fallback')

ESM default import in modern bundlers/TypeScript. The package ships both ESM and CJS; default export is a storage adapter object.

storage (named as default)

✓ const storage = require('local-storage-fallback'); // then use storage.getItem()

✗ import { storage } from 'local-storage-fallback'

With CommonJS require, the default export is returned directly. Using named import { storage } fails because there is no named export called storage.

window.localStorageFallback

✓ <script src="dist.min.js"><script>window.localStorageFallback.setItem('foo', 'bar')

✗ window.storage.setItem()

Browser bundle attaches to window.localStorageFallback, not window.storage.

StorageType enum (if exposed)

✓ import storage from 'local-storage-fallback'; // storage itself has no named export; types only

No named exports are documented; only default export or window global.

Import and use local-storage-fallback as a drop-in replacement for window.localStorage with automatic fallback through sessionStorage, cookies, and memory.

import storage from 'local-storage-fallback'; // Set and get item storage.setItem('username', 'john'); console.log(storage.getItem('username')); // 'john' // Remove item storage.removeItem('username'); // Clear all storage.clear(); // Fallback shim (if localStorage might be broken) if (!('localStorage' in window)) { window.localStorage = storage; } // With CommonJS: // const storage = require('local-storage-fallback'); // storage.setItem('key', 'value');

Debug

Known issues

gotchaCookieStorage has a 4KB size limit per cookie and may be rejected by the browser if too large.

fix

Keep stored values under 4KB, or use sessionStorage/localStorage if available. Monitor for cookie size limits.

affects: >=1.0.0

gotchaMemoryStorage does not persist data across page loads. Data is lost on refresh or navigation.

fix

If you need persistence across full page loads, avoid falling back to MemoryStorage. Ensure localStorage or sessionStorage is available first.

affects: >=1.0.0

deprecatedCommonJS require() returns the default export directly, not an object with a 'storage' property. Using require().storage is wrong.

fix

Use require('local-storage-fallback') directly, not require('local-storage-fallback').storage.

affects: >=3.0.0

gotchaIn private browsing mode, some browsers (e.g., Safari) throw SecurityError when accessing localStorage. This module catches that exception and falls back, but you must still handle errors in your own code if you call storage methods outside the module.

fix

Wrap storage.getItem()/setItem() in try-catch if you use the module directly; the fallback may still throw if all backends fail.

affects: >=1.0.0

gotchaThe module relies on the browser's global object (window). It is not designed for Node.js or server-side rendering.

fix

Use conditional imports or mock for server-side environments.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: localStorageFallback is not a function

Accessed window.localStorageFallback incorrectly or before script load.

fix

Ensure the UMD script is loaded before calling window.localStorageFallback.setItem(). If using a module bundler, import the module instead.

Cannot read properties of undefined (reading 'setItem')

Destructured require() result incorrectly, e.g., const { storage } = require('local-storage-fallback') but storage is undefined.

fix

Change to const storage = require('local-storage-fallback'); then use storage.setItem().

Uncaught DOMException: Failed to read the 'localStorage' property from 'Window': Access is denied for this document.

Browser's security restrictions (e.g., third-party iframe, file:// protocol) block localStorage entirely. The module will attempt fallback, but if no fallback works, it may still throw.

fix

Serve from a proper http/https origin. If not possible, ensure the module is used with fallback that includes memory storage (but data will not persist).

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ripeworks/local-storage-fallback ↗

packagelocal-storage-fallback ↗

homepagehttps://github.com/ripeworks/local-storage-fallback#readme ↗