Redux Cookies Middleware

Common errors

• Redux state is unexpectedly mutated after initial load during hydration from cookies.

  cause Prior to v0.2.0, `getStateFromCookies` could directly mutate the `initialState` object passed to it when merging cookie data.
  fix Upgrade to `redux-cookies-middleware` v0.2.0 or higher to utilize the fixed, non-mutating `getStateFromCookies` implementation.

• SyntaxError: Unexpected token <character> in JSON at position <number> when reading cookies.

  cause `redux-cookies-middleware` attempted to JSON parse cookie values that were not valid JSON strings (e.g., simple strings or corrupted data), leading to parsing errors.
  fix Upgrade to `redux-cookies-middleware` v0.2.0 or higher, which includes improved error handling and robustness when attempting to parse potentially malformed JSON cookie values.

Warnings

• breaking The `redux-cookies-middleware` project appears to be abandoned, with no commits since November 2018. This means it may not be compatible with newer versions of React, Redux, or modern JavaScript build toolchains (e.g., ESM-only environments). Consider using a more actively maintained state persistence library.
  Fix: Evaluate alternatives like `redux-persist` or implement custom cookie logic for state persistence in modern applications.
• gotcha Version 0.2.0 introduced a 'full re-write' of the `getStoreFromCookies` API. Although noted as 'non breaking', significant internal changes can sometimes lead to subtle behavioral differences or edge-case regressions not immediately apparent.
  Fix: Thoroughly test state hydration logic when upgrading from versions prior to 0.2.0 to ensure expected behavior, especially with complex initial state structures or diverse cookie values.
• gotcha The library explicitly uses dot-notation strings to define paths for state serialization. This pattern can be fragile if your Redux state shape frequently changes or if refactoring renames deeply nested keys.
  Fix: Use constants for path strings where possible, and ensure robust testing of cookie persistence logic whenever your Redux state shape evolves.
• gotcha The `paths` configuration allows custom `equalityCheck` and `deleteCheck` functions. If these functions are not robust or introduce side effects, they could lead to unexpected cookie updates or deletions, or performance issues.
  Fix: Ensure custom `equalityCheck` and `deleteCheck` functions are pure, performant, and thoroughly tested, especially when dealing with complex data structures. Leverage a reliable deep equality checker if necessary (e.g., `lodash.isequal`).

Install

• npm install redux-cookies-middleware npm
• yarn add redux-cookies-middleware yarn
• pnpm add redux-cookies-middleware pnpm

Imports

• reduxCookiesMiddleware
  wrong:

  const reduxCookiesMiddleware = require('redux-cookies-middleware');

  correct:

  import reduxCookiesMiddleware from 'redux-cookies-middleware';

  The library primarily uses ES Module syntax in its documentation, but older Node.js environments or tooling might require CommonJS.
• getStateFromCookies
  wrong:

  const getStateFromCookies = require('redux-cookies-middleware/getStateFromCookies');

  correct:

  import getStateFromCookies from 'redux-cookies-middleware/getStateFromCookies';

  This utility is imported from a submodule, not directly from the main package export. It's used to rehydrate state from cookies.
• Paths Configuration Object

  const paths = { 'auth.token': { name: 'my_app_token' } };

  The `paths` object is a crucial configuration for both `reduxCookiesMiddleware` and `getStateFromCookies`, defining which state slices map to which cookie names. It's not a direct import but a fundamental configuration pattern.

Quickstart

This quickstart demonstrates how to set up `redux-cookies-middleware` to persist specific parts of the Redux state ('auth.token' and 'session') into browser cookies, and how to hydrate the initial state from those cookies upon application load.

import { applyMiddleware, createStore, compose } from 'redux';
import reduxCookiesMiddleware from 'redux-cookies-middleware';
import getStateFromCookies from 'redux-cookies-middleware/getStateFromCookies';

// A dummy reducer for demonstration purposes
const reducer = (state = {}, action) => {
  switch (action.type) {
    case 'SET_AUTH_TOKEN':
      return { ...state, auth: { ...state.auth, token: action.payload } };
    case 'SET_SESSION':
      return { ...state, session: action.payload };
    default:
      return state;
  }
};

// Initial state structure
let initialState = {
  auth: {
    token: null,
    key: 'some_key'
  },
  session: null
};

// Define which parts of the state to persist in cookies and their cookie names
const paths = {
  'auth.token': { name: 'my_app_token' },
  'session': { name: 'my_app_session', httpOnly: false, secure: process.env.NODE_ENV === 'production' }
};

// Read stored data from cookies and merge it with the initial state
// This should happen before creating the store to ensure initial state is hydrated.
initialState = getStateFromCookies(initialState, paths);

// Create Redux store with the middleware
const store = createStore(
  reducer,
  initialState,
  applyMiddleware(reduxCookiesMiddleware(paths))
);

// Example dispatch to demonstrate persistence
store.dispatch({ type: 'SET_AUTH_TOKEN', payload: 'new-auth-token-123' });
store.dispatch({ type: 'SET_SESSION', payload: 'user-session-abc' });

console.log('Store state after dispatches:', store.getState());
// In a browser, you would now see 'my_app_token' and 'my_app_session' cookies.
// For Node.js, this example would require a cookie-aware environment or mocking.