npmBeginner-friendly

immer

Create your next immutable state by mutating the current one

immutablestatereduxreactmutationsmutablecopy-on-writetypescriptimmutablesreducer

The Problem

React and Redux require immutable state updates — you must return a new object instead of modifying the existing one. For deeply nested state, this means writing spread-heavy code like { ...state, user: { ...state.user, address: { ...state.user.address, city: 'New York' } } } just to change one field. Immer makes this readable again.

Mental Model

Immer gives you a draft — a mutable proxy of your current state. You write code as if you're mutating it directly: draft.user.address.city = 'New York'. Behind the scenes, Immer records every change and produces a new immutable object with only those changes applied. Mutations on the draft never touch the original.

60-second start

Install immer

npm install immer
import { } from 'immer';

Use it when

Use Immer whenever you have deeply nested state updates that are painful to write immutably: Redux reducers, Zustand's set function, or React useState with complex objects. It's built into Redux Toolkit's createSlice, so you're probably already using it.

Skip it when

For flat, simple state (a counter, a boolean toggle), immer's overhead isn't worth it — just spread the object. Immer also has edge cases with classes, Maps, and Sets that require using enableMapSet() and enableAllPlugins().

Alternatives

structuredCloneBuilt-in deep clone — sufficient when you just need a copy to mutate, without structural sharing

immutable.jsPersistent immutable data structures with structural sharing — more rigorous but heavier and less ergonomic

Ready to explore the full API?

See every class, function, and relationship in an interactive graph.