Registry / database / redux-persist-node-storage

redux-persist-node-storage

library2.0.0jsnpmunverified

Redux-persist-node-storage is an adapter for the Redux Persist library, enabling state persistence in Node.js environments. It achieves this by implementing Redux Persist's required storage interface (`setItem`, `getItem`, `removeItem`, `getAllKeys`) using `node-localstorage`. The package provides a `localStorage`-like API for Node.js, making `redux-persist` usable in server-side applications, Electron apps, or other Node.js contexts where browser `localStorage` is unavailable. Data is stored on disk in a user-specified directory. The current stable version is 2.0.0, released in December 2017. Due to its age and lack of recent updates, its release cadence is effectively non-existent, and it primarily serves a niche requirement for Node.js-specific Redux state persistence.

database serialization

npm install redux-persist-node-storage

github ↗package ↗

INSTALL

IMPORT

SIG · REDUX-PERSIST-NODE

redux-persist-node-storage

databasejavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AsyncNodeStorage

✓ import { AsyncNodeStorage } from 'redux-persist-node-storage';

✗ const AsyncNodeStorage = require('redux-persist-node-storage').AsyncNodeStorage;

While CommonJS `require` might work in older Node.js setups, the package ships with TypeScript types and is generally used in modern ESM-compatible environments.

NodeStorage

✓ import { NodeStorage } from 'redux-persist-node-storage';

NodeStorage is also exported, often used for synchronous operations or specific `node-localstorage` configurations directly, though `AsyncNodeStorage` is preferred for `redux-persist`.

This example demonstrates how to set up `redux-persist-node-storage` with `redux-persist` in a Node.js environment. It defines a simple Redux store with a user reducer, configures the `AsyncNodeStorage` to save to a local directory, and initializes the persisted store, logging the rehydrated state. It also shows basic interaction and a purge option.

import { createStore, combineReducers } from 'redux'; import { persistStore, persistReducer } from 'redux-persist'; import { AsyncNodeStorage } from 'redux-persist-node-storage'; import path from 'path'; // A simple reducer const userReducer = (state = { name: 'Guest', loggedIn: false }, action) => { switch (action.type) { case 'LOGIN': return { ...state, name: action.payload.name, loggedIn: true }; case 'LOGOUT': return { ...state, name: 'Guest', loggedIn: false }; default: return state; } }; const rootReducer = combineReducers({ user: userReducer, }); // Configure redux-persist for Node.js const storageDir = path.join(process.cwd(), './tmp/persist-storage'); const storage = new AsyncNodeStorage(storageDir); const persistConfig = { key: 'root', storage, }; const persistedReducer = persistReducer(persistConfig, rootReducer); const store = createStore(persistedReducer); const persistor = persistStore(store, null, () => { console.log('Redux store rehydrated!'); // Example: Dispatch an action after rehydration // store.dispatch({ type: 'LOGIN', payload: { name: 'NodeUser' } }); console.log('Current state:', store.getState().user); }); // You can trigger actions and check state // store.dispatch({ type: 'LOGIN', payload: { name: 'NodeUser' } }); // console.log('State after login:', store.getState().user); // To clear persisted state (useful for logout/reset) // persistor.purge(); // This will keep the Node process alive long enough to see the output setTimeout(() => { console.log('Final state before exit:', store.getState().user); }, 1000);

Debug

Known issues

breakingThe `autoRehydrate` enhancer used in older `redux-persist` examples (including the package's own README) is deprecated. Modern `redux-persist` (v6+) uses `persistReducer` and `persistStore` directly, requiring the storage engine to be explicitly passed in the configuration object.

fix

Migrate your `redux-persist` configuration to use `persistReducer` and `persistStore` with a `persistConfig` object that explicitly includes the `storage` property. Remove `autoRehydrate` from your store enhancers.

affects: >=2.0.0

gotchaThe underlying `node-localstorage` package, by default, sets a storage quota of 5MB, similar to browser `localStorage`. Exceeding this limit will result in a `QuotaExceededError`. This can be a silent failure if not handled, leading to incomplete state persistence.

fix

Monitor disk usage for your configured storage directory. If large amounts of data need to be persisted, consider increasing the quota for `node-localstorage` during instantiation or using a different storage solution. Implement `try...catch` blocks around persistence operations to handle `QuotaExceededError` gracefully.

affects: >=1.0.0

gotchaSince `node-localstorage` persists data to disk, proper directory permissions are crucial. If the Node.js process does not have write access to the specified storage directory, persistence will fail, potentially silently, or with file system errors.

fix

Ensure that the directory provided to `AsyncNodeStorage` (e.g., `/tmp/storageDir`) exists and that the user running the Node.js process has sufficient read/write permissions for that directory. Use `path.join(process.cwd(), '...')` for reliable path resolution.

affects: >=1.0.0

gotchaThis package is built on `node-localstorage`, which simulates browser `localStorage`. Unlike truly asynchronous Node.js file system operations, `node-localstorage` can still exhibit blocking behavior for large synchronous operations, potentially impacting the Node.js event loop. While `AsyncNodeStorage` attempts to mitigate this, heavy I/O might still be a concern.

fix

For very large or complex state objects, consider selective persistence using `whitelist` or `blacklist` in `redux-persist` config, or utilizing `redux-persist` transforms to store only necessary data. Avoid storing excessively large objects directly.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'length') or similar from 'node-localstorage'

The directory provided to `AsyncNodeStorage` or `NodeStorage` is invalid or inaccessible, preventing `node-localstorage` from initializing properly.

fix

Ensure the directory path passed to `new AsyncNodeStorage('/path/to/dir')` is an absolute, valid, and writable path. Use `path.join(process.cwd(), './your-storage-dir')` for robust path handling.

Error: Redux Persist: `redux-persist` requires a `storage` config. For web, we recommend `redux-persist/lib/storage`.

The `storage` property was omitted or incorrectly configured in the `persistConfig` object passed to `persistReducer` or `persistStore`.

fix

Ensure your `persistConfig` object explicitly includes `storage: new AsyncNodeStorage('/path/to/dir')` (or `storage: new NodeStorage('/path/to/dir')` for synchronous). You must instantiate the storage adapter.

Redux store state is not persisting across application restarts or page refreshes.

Common `redux-persist` setup issues, such as not wrapping the root reducer with `persistReducer`, not calling `persistStore`, or misconfiguring `persistConfig` (e.g., incorrect `key`).

fix

Verify that your root reducer is wrapped by `persistReducer(persistConfig, rootReducer)`, and that `persistStore(store)` is called. Also, ensure the `key` in `persistConfig` is unique and the `storage` adapter is correctly instantiated and passed. Check for any `persistor.purge()` calls being inadvertently triggered.

Redux-persist rehydrates to initial state instead of persisted state.

This often happens when there's a mismatch between the persisted state structure and the current reducer's initial state, or if a `stateReconciler` is not configured appropriately for schema changes.

fix

If your Redux state shape has changed between application versions, consider using a `stateReconciler` like `autoMergeLevel2` or implementing Redux Persist Migrations to handle schema changes gracefully. Purging the old persisted state (`persistor.purge()`) can also resolve immediate rehydration issues, but users will lose their previous state.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

redux-persistrequiredCore persistence library that this package adapts.

node-localstoragerequiredUnderlying Node.js implementation for `localStorage` semantics, used to save data to disk.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/pellejacobs/redux-persist-node-storage ↗

packagehttps://www.npmjs.com/package/redux-persist-node-storage ↗