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.
createStorage
✓ import { createStorage } from 'typesafe-storage'
✗ import createStorage from 'typesafe-storage'
Named export only; default import is not available. Works with both ESM and CJS.
createStorage (default import)
✓ import { createStorage } from 'typesafe-storage'
✗ const createStorage = require('typesafe-storage').default
In CJS, use `const { createStorage } = require('typesafe-storage')`. There is no `.default`.
Type parameters
✓ createStorage<MySchema>(localStorage)
✗ createStorage(localStorage) as StorageSchema<MySchema>
The generic is passed to `createStorage`, not cast afterwards. The type must be an object mapping string keys to value types.
Shows how to define a schema, create a typed storage instance, and use setItem/getItem/removeItem with full type safety.
import { createStorage } from 'typesafe-storage';
interface SessionSchema {
userId: number;
theme: 'light' | 'dark';
tokens: string[];
}
const storage = createStorage<SessionSchema>(sessionStorage);
storage.setItem('userId', 42);
storage.setItem('theme', 'dark');
storage.setItem('tokens', ['abc', 'xyz']);
const userId = storage.getItem('userId'); // typeof userId === number | null
const theme = storage.getItem('theme'); // typeof theme === 'light' | 'dark' | null
storage.removeItem('tokens');
// TypeScript errors on wrong key or value type:
// storage.setItem('invalidKey', 1); // Error: 'invalidKey' not in keys
// storage.setItem('userId', 'not-number'); // Error: type mismatch
storage.clear();
Debug
Known issues
gotchagetItem returns `ValueType | null` even if the key exists but the stored JSON is malformed.fixAlways check for null or use a default value: `const val = storage.getItem('key') ?? defaultValue`. affects: >=0.0.0
gotchaThe generic schema type must include all keys you intend to use. Adding keys later requires updating the type.fixDefine a single comprehensive interface for your storage schema before creation.
affects: >=0.0.0
gotchaOnly localStorage and sessionStorage are supported as storage backends. Passing a custom Storage-like object may cause runtime errors if it doesn't match the Web Storage API exactly.fixUse only native Storage objects or ensure your custom object implements the exact interface.
affects: >=0.0.0
gotchaThe package does not provide SSR (Server-Side Rendering) safety. Calling `createStorage` in a Node environment without a global `localStorage` polyfill will throw.fixUse a conditional import or a polyfill: `typeof window !== 'undefined' ? createStorage(...) : null`.
affects: >=0.0.0
deprecatedNo deprecated features documented.
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'getItem')
Calling methods on a storage instance created without a valid Storage object (e.g., undefined due to SSR).
fixEnsure `localStorage` or `sessionStorage` is available before creating the instance, or provide a fallback.
Type 'string' is not assignable to type 'number'.
Attempting to set a value of the wrong type according to the schema generic.
fixUse the correct value type as defined in the schema interface, or update the schema to accept multiple types.
Argument of type '"nonexistent"' is not assignable to parameter of type '"key1" | "key2"'.
Using a key not declared in the schema generic.
fixAdd the missing key to the schema interface or use a key that is defined.
Audit
Dependencies
No dependency data recorded yet.