Redux State Freeze Middleware

0.1.7 verified Thu Apr 23 auth: no javascript abandoned

Redux-freeze is a Redux middleware designed to prevent accidental state mutations within a Redux application by deeply freezing the state object after each dispatched action. This mechanism helps enforce the core Redux principle of immutability during development, throwing a runtime error if any part of the state is modified directly. It is intended strictly as a development-time tool to catch bugs early, as its deep freezing operation introduces performance overhead unsuitable for production environments. The package is currently at version 0.1.7. Based on the lack of recent activity and a last commit several years ago, the project appears to be abandoned, with no active release cadence. Its primary differentiator is its straightforward, single-purpose approach to ensuring immutability, making it a clear diagnostic tool for identifying unintentional side effects in state management.

Common errors

error TypeError: Cannot assign to read only property '...' of object '#<Object>' ↓

cause This error occurs when you attempt to directly mutate a property of your Redux state object while `redux-freeze` middleware is active. The middleware makes the state immutable.

fix

Always update Redux state immutably. Instead of state.prop = newValue;, create a new object or array with the updated values. For objects, use the spread operator: { ...state, prop: newValue }. For arrays, use [...state, newItem] or state.map(...).

error TypeError: (0 , redux_freeze__WEBPACK_IMPORTED_MODULE_0__.default) is not a function ↓

cause This error (or similar like 'freeze is not a function') typically indicates an incorrect import statement, often attempting a named import when the package provides a default export (common in ESM when using `import { freeze } from 'redux-freeze'`).

fix

Ensure you are using the correct import syntax for a default export. For ES Modules, use import freeze from 'redux-freeze';. For CommonJS, use const freeze = require('redux-freeze');.

Warnings

gotcha Using `redux-freeze` in production environments will incur significant performance overhead due to the deep freezing of the entire state tree on every `dispatch`. It is designed exclusively for development-time debugging. ↓

fix Ensure `redux-freeze` is only included in your Redux middleware stack during development builds, typically guarded by `process.env.NODE_ENV !== 'production'` or a similar conditional check specific to your build setup.

gotcha The middleware performs a deep freeze, which can be computationally intensive for applications with very large or deeply nested state objects. Even in development, this could lead to noticeable delays, impacting hot module replacement or developer experience. ↓

fix If performance in development becomes an issue, consider alternative immutability checks that might be less aggressive or optimize your Redux state structure to avoid excessive depth. For extreme cases, temporary disabling might be needed for specific development tasks.

breaking Older versions (prior to 0.1.7) contained a bug where the state might not be fully frozen before the very first dispatch, potentially allowing initial mutations to go undetected. ↓

fix Upgrade to version `0.1.7` or newer to ensure consistent state freezing behavior from the initial store setup and first dispatch.

Install

npm install redux-freeze

yarn add redux-freeze

pnpm add redux-freeze

Imports

freeze
wrong
```
import { freeze } from 'redux-freeze';
```
correct
```
import freeze from 'redux-freeze';
```
The `redux-freeze` package exports a default function. For ES Modules, use the default import syntax without curly braces.
freeze
wrong
```
const { freeze } = require('redux-freeze');
```
correct
```
const freeze = require('redux-freeze');
```
For CommonJS environments, the `require` statement directly imports the default exported function. Do not use destructuring.
applyMiddleware
```
import { createStore, applyMiddleware } from 'redux';
```
The `freeze` middleware is typically used in conjunction with Redux's `applyMiddleware` function when creating your store. This is a standard Redux import, not specific to `redux-freeze`.

Quickstart

This quickstart demonstrates how to integrate `redux-freeze` into a Redux store and shows how it catches both direct state mutations within reducers and mutations on state objects retrieved from the store.

import { createStore, applyMiddleware } from 'redux';
import freeze from 'redux-freeze'; // Or `const freeze = require('redux-freeze');` for CJS

// A basic reducer to demonstrate state mutation
const initialState = {
  user: {
    name: 'Alice',
    preferences: { theme: 'dark' }
  },
  items: []
};

function rootReducer(state = initialState, action) {
  switch (action.type) {
    case 'UPDATE_USER_NAME_MUTATE':
      // This line intentionally mutates the state, which redux-freeze will catch
      state.user.name = action.payload; 
      return state;
    case 'ADD_ITEM':
      return {
        ...state,
        items: [...state.items, action.payload]
      };
    default:
      return state;
  }
}

// Create the Redux store with redux-freeze middleware
// In a real application, you would typically only apply this in development mode.
const store = createStore(rootReducer, applyMiddleware(freeze));

console.log('Initial state:', store.getState());

try {
  console.log('\nAttempting to dispatch an action that mutates state...');
  store.dispatch({ type: 'UPDATE_USER_NAME_MUTATE', payload: 'Bob' });
} catch (error) {
  console.error('ERROR: Caught expected state mutation error:', error.message);
  // Expected: "Cannot assign to read only property 'name' of object '#<Object>'"
}

console.log('\nDispatching an action that correctly updates state immutably...');
store.dispatch({ type: 'ADD_ITEM', payload: { id: 1, name: 'New Item' } });

console.log('State after immutable update:', store.getState());

// Demonstrating that the retrieved state is also frozen
try {
  console.log('\nAttempting to mutate state directly after retrieval...');
  store.getState().user.preferences.theme = 'light';
} catch (error) {
  console.error('ERROR: Caught expected mutation error on retrieved state:', error.message);
}