On this page
15. What is Immer?
Short answer
Immer is a small library that lets you write immutable updates with normal "mutating" syntax. You change a draft (a Proxy of your state), and Immer records the changes and produces a new, immutable state object, reusing every part you did not touch (structural sharing). Redux Toolkit uses Immer inside createSlice and createReducer, and you can use it with useState via produce or the use-immer hook.
Explanation
Immer is like editing a photocopy with tracked changes. You scribble freely on the copy (draft); at the end, Immer produces a clean new document containing only your edits, while the original stays untouched and the unchanged pages are reused, not reprinted.
Why it exists
React and Redux detect changes by reference. Nested immutable updates by hand are verbose and fragile:
// Without Immer
return {
...state,
user: {
...state.user,
address: { ...state.user.address, city: "Pune" },
},
};
// With Immer
state.user.address.city = "Pune";
How it works
baseState --produce(recipe)--> draft (Proxy)
|
recipe mutates draft
|
Immer tracks which paths changed
|
nextState: new objects only along changed paths,
everything else shares the same reference as baseState
(and the result is deep-frozen in development)
Rules
- Either mutate the draft or return a new value, never both in the same recipe.
- Returning
undefinedmeans "use the draft"; to set state toundefinedreturnnothingfrom Immer. - Drafts are only valid inside the recipe. Do not store them or use them in async callbacks; use
current(draft)to log a snapshot. - Primitive state (a number) cannot be mutated; return the new value instead.
Example
import { useState } from "react";
import { produce } from "immer";
import { createSlice } from "@reduxjs/toolkit";
// 1. With useState
export function TodoList() {
const [todos, setTodos] = useState([{ id: 1, text: "Learn Immer", done: false }]);
function toggle(id) {
setTodos(
produce((draft) => {
const todo = draft.find((t) => t.id === id);
if (todo) todo.done = !todo.done;
})
);
}
return (
<ul>
{todos.map((t) => (
<li key={t.id} onClick={() => toggle(t.id)}>
{t.done ? "✓ " : ""}{t.text}
</li>
))}
</ul>
);
}
// 2. Inside Redux Toolkit (Immer is built in)
const counterSlice = createSlice({
name: "counter",
initialState: { value: 0, history: [] },
reducers: {
increment(state) {
state.history.push(state.value); // mutate draft
state.value += 1;
},
reset() {
return { value: 0, history: [] }; // or return a brand-new value
},
},
});
Common mistakes
- Writing
state = newStatein a slice reducer; reassigning the parameter does nothing, you mustreturn newState. - Mutating the draft and also returning a different object, which throws.
- Thinking Immer makes it safe to mutate state outside a reducer or
produce. - Logging a draft with
console.logand seeing a Proxy; usecurrent(draft).
Follow-up questions
- Does Immer hurt performance? Slightly slower than hand-written spreads, but negligible for normal app state; avoid it for very large arrays updated in tight loops.
- What is structural sharing? Unchanged branches of the new state are the same objects as the old state, so memoized selectors and components skip work.
- What is
use-immer? A hook (useImmer) that wrapsuseStateso the setter accepts an Immer recipe.
Quick recap
- Immer turns "mutating" code on a draft into immutable updates.
- It uses Proxies and structural sharing.
- Built into Redux Toolkit's
createSlice. - Mutate the draft or return a new value, not both.