localit

library6.1.0jsnpmunverified

A lightweight (~1kB gzipped), fully-typed wrapper around the Web Storage API (localStorage / sessionStorage) with expiration support, optional key namespacing, and change event listeners. Version 6.1.0 is the latest stable release, actively maintained on GitHub. Unlike raw storage APIs, localit handles serialization automatically, supports expiration strings like '5m' or '2h', and allows listening to key changes via an `on` method. It requires no external dependencies and ships TypeScript type definitions.

storage

npm install localit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOCALIT

localit

storagejavascriptv6.1.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.

localit

✓ import { localit } from 'localit'

✗ import localit from 'localit'

Named export only, no default export. TypeScript users must use named import.

ExpirationType

✓ import { ExpirationType } from 'localit'

✗ type ExpirationType = `${number}s` | `${number}m` | `${number}h` | `${number}d` | Date

Type exported for convenience; avoid re-declaring.

LocalitSetConfig

✓ import { LocalitSetConfig } from 'localit'

✗ interface LocalitSetConfig { type?: Storage; family?: string; expiration?: ExpirationType; }

Type exported; import rather than redefine.

LocalitGetConfig

✓ import { LocalitGetConfig } from 'localit'

✗ interface LocalitGetConfig { type?: Storage; family?: string; }

Type exported; import rather than redefine.

Demonstrates setting with expiration, typed get, change listener, removal, and family-based namespacing with clearFamily.

import { localit } from 'localit'; localit.set('greeting', 'Hello, world!', { expiration: '1h' }); const value = localit.get<string>('greeting'); console.log(value); // 'Hello, world!' (if not expired) localit.on('greeting', (newVal) => { console.log('Greeting changed to:', newVal); }); localit.set('greeting', 'Hi there!'); // triggers log localit.remove('greeting'); const afterDelete = localit.get('greeting'); console.log(afterDelete); // null localit.set('config', { theme: 'dark' }, { family: 'app' }); localit.clearFamily('app'); // removes 'app::config' and all other keys in family 'app'

Debug

Known issues

gotcha`localit.on` only triggers for changes made via localit's set/remove methods, not for direct localStorage.setItem or other tabs.

fix

Use the native 'storage' event or a polyfill for cross-tab synchronization.

affects: >=1.0.0

gotchaExpiration is checked on `get`; if a value expires between calls, it is removed and null returned. However, expired values are NOT automatically cleaned up unless you call `get` or `bust`.

fix

Purge expired entries by calling `get` on them or periodically clearing storage with `bust()`.

affects: >=1.0.0

gotchaWhen using `family`, keys are stored as `family::key`. Removal without specifying the family only deletes the unprefixed key.

fix

Use `localit.remove('key', { family: 'familyName' })` to remove a namespaced key.

affects: >=1.0.0

deprecatedIn version 5.x and earlier, the import was `import localit from 'localit'`. This default export is removed in v6.

fix

Change to `import { localit } from 'localit'`.

affects: >=6.0.0

gotchaThe expiration string format is strict: only `Xs`, `Xm`, `Xh`, `Xd` are supported (e.g., '5m', '2h'). Leading/trailing spaces or other units (e.g., '1day') will be ignored and no expiration is set.

fix

Use valid format: e.g., '1d' for 1 day. Or pass a Date object.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: localit__WEBPACK_IMPORTED_MODULE_0___default(...).set is not a function

Using default import instead of named import in bundler environment.

fix

Replace `import localit from 'localit'` with `import { localit } from 'localit'`.

Uncaught TypeError: Cannot read properties of null (reading 'set')

localStorage or sessionStorage is not available (e.g., in private browsing mode or SSR).

fix

Wrap usage in a try-catch or check `typeof window !== 'undefined'` before calling localit methods.

TypeScript error: Module '"localit"' has no exported member 'localit'

Package version is older than 6.0.0 where only a default export existed, or missing TypeScript types.

fix

Update to v6.1.0: `npm install localit@latest`. For v5, use `import localit from 'localit'`.

localit.get returns null even though I just set a value without expiration

The key might be stored under a different `family` than expected, or storage was cleared externally.

fix

Ensure the `family` config matches between `set` and `get`. Or omit family entirely if not needed.

Upgrade

Version history

6.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/alexmayol/localit ↗

packagelocalit ↗

homepagehttps://github.com/alexmayol/localit#readme ↗