bun-storage

library2.0.5jsnpmunverified

bun-storage is a zero-dependency ponyfill for the Web Storage API that uses SQLite to persist data. Version 2.0.5 is the current stable release, maintained as a fast Bun-native alternative to node-localstorage or memory-based implementations. It supports localStorage, sessionStorage, storage events, and optional quota enforcement. Compatible with Bun ≥1.0 and Node ≥20. Released via both npm and JSR, with automatic global injection via 'bun-storage/auto'. It differs from other storage libraries by targeting the Bun runtime, using SQLite for reliable persistence, and exposing both class-based and factory APIs.

storage

npm install bun-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUN-STORAGE

bun-storage

storagejavascriptv2.0.5

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.

createStorage

✓ import { createStorage } from 'bun-storage'

✗ import createStorage from 'bun-storage'

createStorage is a named export, not a default export. Common mistake if using default import syntax.

Storage

✓ import { Storage } from 'bun-storage'

✗ const { Storage } = require('bun-storage')

The package is ESM-only; require() will fail. Use named import for TypeScript/ESM.

auto setup

✓ import 'bun-storage/auto'

✗ import { auto } from 'bun-storage'

Auto setup is a side-effect import from the 'auto' subpath. No symbol is exported; it sets global sessionStorage and localStorage.

Demonstrates creating storage instances, basic get/set, and listening for storage events using the factory function.

import { createStorage } from 'bun-storage'; const { sessionStorage, localStorage, emitter } = createStorage('./db.sqlite'); // Set an item localStorage.setItem('key', process.env.KEY ?? 'value'); console.log(localStorage.getItem('key')); // 'value' // Listen for storage events emitter.on('storage', (event) => { console.log('Storage event:', event); }); // Example usage with sessionStorage sessionStorage.setItem('sessionKey', 'sessionValue'); console.log(sessionStorage.getItem('sessionKey')); // 'sessionValue'

Debug

Known issues

breakingimport 'bun-storage/auto' now requires the .sqlite file path to default to a writable location; if running in a read-only filesystem, auto setup will fail.

fix

Use explicit createStorage() with a writable path or ':memory:' instead of auto-import.

affects: >=2.0.0

deprecatedUsing Storage class directly without an emitter is deprecated; you should pass an emitter option for event support.

fix

Provide an instance of EventEmitter in the options when constructing Storage.

affects: >=1.5.0

gotchaThe package is ESM-only and uses Bun APIs. Running with Node.js may fail if Bun APIs are not polyfilled.

fix

Use only with Bun runtime (>=1.0.0). If Node.js is required, consider @idleberg/local-storage instead.

affects: >=2.0.0

Errors

Common errors & fixes

SyntaxError: The requested module 'bun-storage' does not provide an export named 'default'

Trying default import when only named exports exist.

fix

import { createStorage } from 'bun-storage'

TypeError: localStorage.getItem is not a function

Using global localStorage from auto setup but imported incorrectly or not at all.

fix

Add import 'bun-storage/auto' at the top of your entry file.

Error: The file './db.sqlite' could not be opened. Permission denied.

Running in a directory without write permissions.

fix

Use ':memory:' or provide a writable path.

Upgrade

Version history

2.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/idleberg/bun-storage ↗

packagebun-storage ↗

homepagehttps://github.com/idleberg/bun-storage#readme ↗