Persisting State: ngrx-store-localstorage vs redux-persist

Saving user data, preferences, or session tokens so they survive a page refresh is a common requirement in modern web apps. Both ngrx-store-localstorage and redux-persist solve this problem by syncing your store to the browser's local storage. However, they are built for different ecosystems and follow distinct architectural patterns. Let's look at how they handle integration, rehydration, and advanced scenarios.

🏗️ Integration Style: Meta-Reducers vs Store Enhancers

The most fundamental difference lies in how these libraries plug into your state management system.

ngrx-store-localstorage acts as a meta-reducer. In NgRx, meta-reducers wrap the root reducer to intercept actions before they reach your feature reducers. This approach is purely functional and fits naturally into the Angular/NgRx architecture. You simply pass the meta-reducer to the StoreModule.forRoot configuration.

// ngrx-store-localstorage: Integrated as a meta-reducer
import { StoreModule } from '@ngrx/store';
import { localStorageSync } from 'ngrx-store-localstorage';

export function localStorageSyncReducer(reducer: ActionReducer<any>): ActionReducer<any> {
  return localStorageSync({ keys: ['user', 'settings'] })(reducer);
}

@NgModule({
  imports: [
    StoreModule.forRoot(reducers, {
      metaReducers: [localStorageSyncReducer]
    })
  ]
})
export class AppModule {}

redux-persist uses a store enhancer and a separate persistStore function. It does not just wrap the reducer; it creates a persistence object that manages the engine. In React applications, this usually requires wrapping your app in a PersistGate component to delay rendering until the state is restored from storage.

// redux-persist: Requires persistStore and PersistGate
import { persistStore, persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import { PersistGate } from 'redux-persist/integration/react';

const persistConfig = {
  key: 'root',
  storage,
};

const persistedReducer = persistReducer(persistConfig, rootReducer);
const store = createStore(persistedReducer);
const persistor = persistStore(store);

// In your React App component
<Provider store={store}>
  <PersistGate loading={null} persistor={persistor}>
    <App />
  </PersistGate>
</Provider>

⏳ Rehydration: Automatic vs Gated Rendering

How the application behaves while waiting for data to load from disk differs significantly between the two.

ngrx-store-localstorage performs rehydration synchronously during the store initialization phase (inside the meta-reducer). By the time your Angular components initialize, the state is already populated from local storage. There is no need for a loading gate or special component to wait for data.

// ngrx-store-localstorage: No gate needed
// State is available immediately in components
@Component({
  selector: 'app-user',
  template: `<div *ngIf="user$ | async as user">{{ user.name }}</div>`
})
export class UserComponent {
  user$ = this.store.select('user'); // Data is ready here
}

redux-persist often handles rehydration asynchronously. Because reading from storage (especially IndexedDB or large JSON blobs) can take time, the library provides a PersistGate. This component pauses the rendering of its children until the persisted state has been retrieved and merged into the store. This prevents UI errors caused by rendering with empty initial state.

// redux-persist: Explicitly handles loading state
const LoadingScreen = () => <div>Loading saved data...</div>;

// Children inside PersistGate will not render until rehydration completes
<PersistGate loading={<LoadingScreen />} persistor={persistor}>
  <Dashboard /> 
</PersistGate>

🛠️ Configuration and Filtering

Both libraries allow you to choose which parts of the state to save, but the configuration syntax reflects their host frameworks.

ngrx-store-localstorage uses a simple function call where you specify an array of keys. It also supports custom serialization logic if you need to handle complex objects like Dates or Maps.

// ngrx-store-localstorage: Key array and custom serialize
localStorageSync({
  keys: ['auth', 'preferences'],
  rehydrate: true,
  serialize: (state) => {
    // Custom logic to handle Date objects
    return JSON.stringify(state, (key, value) => 
      value instanceof Date ? { __type: 'Date', value: value.getTime() } : value
    );
  }
});

redux-persist uses a configuration object passed to persistReducer. It supports whitelist (only save these) or blacklist (save everything except these). It also has built-in support for transforms to handle data conversion.

// redux-persist: Whitelist/Blacklist and Transforms
const persistConfig = {
  key: 'root',
  storage,
  whitelist: ['auth', 'settings'], // Only persist these keys
  transforms: [
    // Built-in or custom transforms for complex data
  ]
};

🔄 State Migrations: Handling Schema Changes

When you change the shape of your state (e.g., renaming a field), old data in local storage might break your app. Handling these migrations is a key differentiator.

ngrx-store-localstorage does not have a built-in migration system. If you change your state structure, you typically need to manually check for version numbers in your reducer or clear the storage if the data shape is incompatible. You might write a custom meta-reducer to handle this logic yourself.

// ngrx-store-localstorage: Manual migration logic required
export function migrationMetaReducer(reducer: ActionReducer<any>): ActionReducer<any> {
  return (state, action) => {
    if (action.type === '@ngrx/store/init') {
       const storedState = localStorage.getItem('ngrx-store');
       if (storedState) {
         const parsed = JSON.parse(storedState);
         // Manually check and fix old structure
         if (!parsed.user.fullName && parsed.user.name) {
            parsed.user.fullName = parsed.user.name;
         }
       }
    }
    return reducer(state, action);
  };
}

redux-persist includes a robust, built-in migration system. You define a migrate function in your config that receives the old state and a version number. This makes updating state schemas across app versions much safer and cleaner.

// redux-persist: Built-in migration support
const migrations = {
  2: (state) => {
    // Migrate from version 1 to 2
    return {
      ...state,
      user: {
        ...state.user,
        fullName: state.user.name // Rename field
      }
    };
  }
};

const persistConfig = {
  key: 'root',
  version: 2,
  storage,
  migrate: createMigrate(migrations, { debug: false })
};

🌐 Ecosystem and Storage Engines

The choice of storage engine is often dictated by the platform you are building for.

ngrx-store-localstorage is tightly coupled to the browser's localStorage API. While you can technically inject a different storage service in Angular, the package is optimized and tested primarily for synchronous browser storage. It is not designed for React Native or server-side rendering (SSR) environments out of the box.

// ngrx-store-localstorage: Defaults to window.localStorage
// Best for standard Angular web apps
localStorageSync({ keys: ['cart'] }); 

redux-persist is designed to be storage-agnostic. It works with localStorage, sessionStorage, IndexedDB, and even AsyncStorage for React Native mobile apps. This flexibility makes it the go-to choice for cross-platform applications.

// redux-persist: Swappable storage engines
import AsyncStorage from '@react-native-async-storage/async-storage';

// Works seamlessly in React Native
const persistConfig = {
  key: 'root',
  storage: AsyncStorage 
};

🤝 Similarities: Shared Core Concepts

Despite their architectural differences, both libraries share the same fundamental goal and basic capabilities.

1. 💾 Automatic Syncing

Both libraries automatically save state changes to storage whenever an action updates the store. You don't need to manually call setItem.

// Both: Dispatching an action triggers an auto-save
store.dispatch({ type: 'UPDATE_USER', payload: newUser });
// Data is written to localStorage automatically by both libraries

2. 🔑 Key-Based Selection

Both allow you to limit what gets saved. You rarely want to persist the entire store (e.g., avoiding large API caches or UI states).

// ngrx-store-localstorage
localStorageSync({ keys: ['auth'] });

// redux-persist
whitelist: ['auth']

3. 🧩 Serialization

Both handle converting your JavaScript state objects into JSON strings for storage and parsing them back upon load. They both allow custom serialization logic for non-JSON data types.

// Both support custom serializers for special types like Dates
// ngrx: serialize option
// redux-persist: transforms array

📊 Summary: Key Differences

💡 The Big Picture

ngrx-store-localstorage is the pragmatic choice for Angular developers. It feels like a natural extension of NgRx, leveraging meta-reducers to keep logic functional and centralized. If you are in the Angular ecosystem, this package saves you from fighting against the framework's architecture. It is simple, effective, and "just works" for standard web apps.

redux-persist is the powerhouse for the React and cross-platform world. Its ability to handle asynchronous storage, provide a loading gate, and manage complex state migrations makes it indispensable for large-scale applications or mobile apps (React Native). While it introduces more boilerplate, that complexity buys you significant control and safety when managing state over the long term.

Final Thought: Do not try to force redux-persist into an Angular app if ngrx-store-localstorage meets your needs—the integration will feel unnatural. Conversely, if you are building a React Native app, redux-persist is essentially the only viable option due to its storage engine flexibility. Choose the tool that respects your framework's conventions.