Immutability In React With Immer

Introduction: Why Immutability Matters in React

State management is at the heart of every React application, but the requirement for immutable updates often leads to verbose, error-prone code. Immer (German for "always") is a tiny package that transforms how we approach immutable state, allowing you to write mutation-style code while maintaining all the benefits of immutable data structures.

Whether you're working with complex nested objects or simple arrays, Immer simplifies your state management logic without sacrificing performance or introducing unnecessary dependencies.

What You'll Learn

• How the produce function works under the hood
• Integrating Immer with useState and useImmer hook
• TypeScript support and type-safe patterns
• Performance optimization strategies
• Real-world patterns for production applications

For developers building custom React applications, mastering Immer leads to cleaner codebases and faster development cycles.

Immer Official Documentation provides comprehensive coverage of these concepts and more.

Understanding Immer Fundamentals

What is Immer and How It Works

Immer is a tiny 3KB gzipped package that revolutionizes how we handle immutable state in JavaScript. At its core, Immer uses proxies to track mutations on draft state, then produces a completely new immutable copy based on those changes.

Key benefits of Immer include:

• Structural sharing: Unchanged parts of state are shared in memory
• Auto-freezing: Produced state is frozen to prevent accidental mutations
• Boilerplate reduction: No more spreading objects at every level
• Simpler mental model: Write mutation-style code, get immutable results

The produce Function

The produce function is Immer's core API. It takes a current state and a "recipe" function that describes how to transform it:

import { produce } from 'immer'

const baseState = {
 user: {
 name: 'John',
 preferences: {
 theme: 'dark',
 notifications: true
 }
 }
}

const newState = produce(baseState, (draft) => {
 draft.user.name = 'Jane'
 draft.user.preferences.theme = 'light'
})

The original baseState remains unchanged, while newState contains only the modified parts. Unchanged properties like user.preferences.notifications are structurally shared between both states.

This approach pairs well with custom React hooks for building reusable state logic across your application. For more details on the produce function and its capabilities, see the Immer Official Documentation.

React Integration Patterns

Using Immer with useState

The most common pattern is wrapping state updates with produce. This approach works seamlessly with React's existing state management:

import { useState } from 'react'
import { produce } from 'immer'

function UserProfile() {
 const [user, setUser] = useState({
 name: '',
 email: '',
 preferences: { theme: 'light', notifications: true }
 })

 const updateTheme = (theme) => {
 setUser(produce(user, draft => {
 draft.preferences.theme = theme
 }))
 }

 return (
 <div>
 <button onClick={() => updateTheme('dark')}>Dark Theme</button>
 </div>
 )
}

Why this pattern maintains React's immutability guarantees: The produce function always returns a completely new object reference, even though only the modified properties are actually copied. This means React's reference equality check (Object.is) detects the state change correctly, triggering the appropriate re-renders. Meanwhile, Immer's structural sharing ensures that unchanged portions of state remain the same reference in memory, optimizing memory usage. This dual benefit--correct React updates combined with efficient memory handling--makes the produce wrapper an ideal companion to React's state model.

This pattern aligns with our approach to clean code practices in modern React applications, reducing bugs while maintaining performance.

The useImmer Hook

For even cleaner code, the use-immer package provides a useImmer hook that auto-wraps updates with produce:

Installation:

npm i use-immer

Usage:

import { useImmer } from 'use-immer'

function FormExample() {
 const [formData, updateFormData] = useImmer({
 firstName: '',
 lastName: '',
 email: ''
 })

 const handleChange = (field, value) => {
 updateFormData(draft => {
 draft[field] = value
 })
 }

 const handleSubmit = () => {
 console.log(formData) // Ready to send to API
 }

 return (
 <form>
 <input
 value={formData.firstName}
 onChange={(e) => handleChange('firstName', e.target.value)}
 />
 <button type="button" onClick={handleSubmit}>Submit</button>
 </form>
 )
}

The updateFormData function automatically handles the immutability, so you can focus on your business logic. Combining useImmer with state testing strategies ensures your state management remains reliable as your application grows. For more practical examples, see this Introduction to Immer in React guide.

TypeScript and Immer

Immer has excellent TypeScript support with automatic type inference. When you pass a typed state object to produce, the draft parameter inherits the state type with Immer's Draft utility:

import { produce, Draft } from 'immer'

interface UserState {
 id: string
 name: string
 preferences: {
 theme: 'light' | 'dark'
 notifications: boolean
 }
}

const updateUser = (
 state: UserState, 
 newTheme: 'light' | 'dark'
): UserState => {
 return produce(state, (draft: Draft<UserState>) => {
 draft.preferences.theme = newTheme
 // TypeScript knows: draft.id, draft.name, draft.preferences
 })
}

Type-Safe Custom Hooks

Create reusable typed hooks for your application:

import { useImmer, UseImmerState } from 'use-immer'

interface FormState {
 firstName: string
 lastName: string
 email: string
}

export function useFormState(initialValue: FormState): [
 FormState,
 (updater: (draft: FormState) => void) => void
] {
 return useImmer(initialValue)
}

This pattern complements our TypeScript type patterns guide for building type-safe applications. For a detailed comparison of Immer with other immutability libraries including TypeScript considerations, see this Immer vs Immutable.js Comparison.

Immer vs Alternative Approaches

Why Immer Wins for Most React Applications

Immer vs Manual Spread Operators:

Immer vs Immutable.js:

While Immutable.js from Facebook offers powerful data structures, Immer provides a more intuitive API that feels like natural JavaScript. For React applications, Immer's smaller footprint and simpler API make it the preferred choice. When building modern JavaScript applications, choosing the right tools for state management significantly impacts developer productivity and code maintainability. The detailed comparison between Immer and Immutable.js highlights these advantages clearly.

Best Practices and Performance Tips

When to Use Immer

Immer shines in scenarios with:

• Deeply nested state objects - Eliminates complex spread chains
• Frequent state updates - Structural sharing reduces memory pressure
• TypeScript projects - Excellent type inference
• Team environments - Cleaner code is easier to maintain

For simple, shallow state updates, the traditional spread operator may be more appropriate.

Performance Optimization

import { useMemo, useCallback } from 'react'
import { produce } from 'immer'

function OptimizedComponent({ data }) {
 // Memoize expensive produce operations
 const processedData = useMemo(() => {
 return produce(data, (draft) => {
 draft.items.sort((a, b) => a.rank - b.rank)
 })
 }, [data])

 // Memoize callback to prevent unnecessary re-renders
 const handleUpdate = useCallback((id, value) => {
 setData(produce(data, (draft) => {
 const item = draft.items.find(i => i.id === id)
 if (item) item.value = value
 }))
 }, [data])

 return <List data={processedData} onUpdate={handleUpdate} />
}

Key optimizations:

1. Use useMemo for expensive transformations
2. Memoize callbacks with useCallback
3. Let Immer handle structural sharing automatically
4. Enable auto-freeze in development to catch bugs early

These patterns integrate seamlessly with React performance optimization techniques for building high-performance applications. For more on immutability patterns in React, see LogRocket's guide on Immutability in React with Immer.

Integration with Next.js

Immer works seamlessly with Next.js App Router. Since Immer is a client-side library, ensure proper usage in client components:

'use client'

import { useImmer } from 'use-immer'

export default function Dashboard() {
 const [metrics, setMetrics] = useImmer({
 pageViews: 0,
 uniqueVisitors: 0,
 bounceRate: 0
 })

 const trackVisit = () => {
 setMetrics(draft => {
 draft.pageViews += 1
 draft.uniqueVisitors += 1
 })
 }

 return (
 <div onClick={trackVisit}>
 <h1>Dashboard</h1>
 <p>Page Views: {metrics.pageViews}</p>
 </div>
 )
}

SEO and Performance Benefits

Using Immer contributes to better web performance in several ways:

• Smaller bundle size leaves more room for critical rendering resources
• Efficient updates mean faster React reconciliation cycles
• Structural sharing reduces memory churn in long-running applications

For optimal Core Web Vitals, combine Immer with proper code splitting and server-side rendering where appropriate. This approach aligns with our Next.js development services philosophy of building performant web applications.

Sources

1. Immer Official Documentation - Primary source for Immer API and core concepts
2. LogRocket - Immutability in React with Immer - Comprehensive guide on React integration patterns
3. DEV Community - Introduction to Immer in React - Practical code examples and useImmer hook
4. DhiWise - Immer vs Immutable.js Comparison - Performance benchmarks and library comparison