safe-storage

library1.0.2jsnpmunverified

safe-storage (v1.0.2) provides drop-in replacements for localStorage and sessionStorage that gracefully fall back to an in-memory implementation when the native browser storages are unavailable or throw errors (e.g., Safari private mode). No dependencies, no build step, and supports both ESM and CommonJS. Unlike other storage wrappers, it specifically targets the Safari private browsing bug and does not introduce any new API surface — it exactly mirrors the native Storage interface. Released in 2017, stable with no recent updates.

storage

npm install safe-storage

package ↗

INSTALL

IMPORT

SIG · SAFE-STORAGE

safe-storage

storagejavascriptv1.0.2

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.

safeLocalStorage

✓ import { safeLocalStorage } from 'safe-storage'

✗ import safeLocalStorage from 'safe-storage'

Default export does not exist; must use named import.

safeSessionStorage

✓ import { safeSessionStorage } from 'safe-storage'

✗ const { safeSessionStorage } = require('safe-storage')

Library supports both ESM and CJS, but the CJS require pattern is less common in modern codebases.

Storage (type)

✓ import type { Storage } from 'safe-storage'

✗ import { Storage } from 'safe-storage'

Storage is a TypeScript type export, not a runtime value. Use 'import type' for type-only imports.

Demonstrates basic setItem, getItem, length, and clear methods for both safeLocalStorage and safeSessionStorage.

import { safeLocalStorage, safeSessionStorage } from 'safe-storage'; safeLocalStorage.setItem('user', JSON.stringify({ name: 'Alice' })); const user = JSON.parse(safeLocalStorage.getItem('user') ?? 'null'); console.log(user.name); // Alice safeSessionStorage.setItem('sessionId', 'abc123'); console.log(safeSessionStorage.length); // 1 safeSessionStorage.clear(); console.log(safeSessionStorage.length); // 0

Debug

Known issues

gotchaThe library only falls back to in-memory storage when the native storage throws or is missing. If the native storage is present but full (quota exceeded), safe-storage does NOT catch that error.

fix

Wrap calls in a try-catch if you need to handle quota exceeded errors, or use a different library that handles that case.

affects: >=1.0.0

deprecatedThis package has not been updated since 2017. It may not be compatible with newer environments or bundlers that enforce stricter module resolution.

fix

Consider using a more modern alternative like 'localforage' or 'storage-factory' that provides a similar fallback but with more features and active maintenance.

affects: >=1.0.0

gotchaIn Node.js environments, both safeLocalStorage and safeSessionStorage will always fall back to in-memory storage because native localStorage is not available. This may cause data loss across server restarts.

fix

Do not use this library on the server side for persistent data; use a dedicated database or file-based storage instead.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught TypeError: safeLocalStorage is not a function

Using default import instead of named import: `import safeLocalStorage from 'safe-storage'`

fix

Use named import: `import { safeLocalStorage } from 'safe-storage'`

Cannot find module 'safe-storage' or its corresponding type declarations.

The package may not be installed, or TypeScript cannot find the type definitions.

fix

Install the package: `npm install safe-storage`. Ensure tsconfig.json includes 'node_modules' in 'types' or 'typeRoots'.

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

Attempting to use safeLocalStorage before the import resolves, often in environments where the module is not fully loaded.

fix

Ensure the import is at the top of the file and that the module is correctly installed. Check for circular dependencies.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

packagesafe-storage ↗