Guide · Open source
How to use Immer: install it and update state immutably
Updated · written with AI from the project's own documentation and checked against our catalogue data
Immer is a JavaScript library for updating state without changing the original object directly. You write code that looks like it modifies a draft of your data, and Immer produces a new immutable copy with only the changed parts updated. This guide shows you how to install it, what the library is for, and when it fits your project.
Immerimmerjs/immer · ★ 29k · MIT Install options & downloads Quick start
- 1Check Node.js. Make sure Node.js is installed, since the README lists it as the prerequisite.
- 2Install the package. Run npm install immer in your project folder.
- 3Read the documentation. Open https://immerjs.github.io/immer/ to learn the API and examples.
- 4Apply it to one reducer. Start with one nested state update in a Redux-style reducer and replace the manual copy logic.
- 5Check the release notes. Review https://github.com/immerjs/immer/releases when you upgrade.
What Immer does
Immutable state means you never edit an object in place. Instead you create a new object with the change applied. Writing that by hand, especially for nested data, can be verbose and easy to get wrong.
The Immer README describes the library as a way to create the next immutable state tree by simply modifying the current tree. You modify the draft, and Immer handles producing the new state.
- Good fit: nested state in Redux-style reducers.
- Good fit: developers who want immutable data without learning a new state model.
- Not a full state management framework; it is a focused library for producing new state.
Install Immer with npm
Immer is installed as a package. The README lists Node.js as the prerequisite and gives the npm install command below.
Run this in your project folder:
- Prerequisite: Node.js
- Installation method: package manager (npm)
npm install immerUse Immer in your code
The README excerpt provided for this guide does not describe Immer's APIs in detail, so check the official documentation at https://immerjs.github.io/immer/ for usage examples and function signatures.
Once installed, the core idea is the same across uses: change the draft you are given, and let Immer return the next immutable state.
- Read the documentation at https://immerjs.github.io/immer/ for exact API usage.
- Use it where you would otherwise write manual copy-and-update logic.
Compare Immer with similar libraries
Several projects solve related problems. Immutable.js, Mutative and Redux Toolkit are commonly compared with Immer. Choose based on what your team already uses and how much of the state model you want to adopt.
- Immutable.js
- Mutative
- Redux Toolkit
Get help and release information
Documentation is hosted at https://immerjs.github.io/immer/. Release notes are published on the project's GitHub releases page.
The README also invites support through the Open Collective at https://opencollective.com/immer.
- Documentation: https://immerjs.github.io/immer/
- Release notes: https://github.com/immerjs/immer/releases
What people use it for
- Updating nested objects in Redux-style reducers without manual copying.
- Keeping state immutable in a JavaScript front-end project without adopting a new state model.
- Simplifying update code that is verbose or error-prone when written by hand.
Frequently asked questions
Is Immer free to use?
Immer is released under the MIT licence, according to its repository details. Check the LICENSE file in the repository for the full terms.
What do I need to install Immer?
The README lists Node.js as the prerequisite. Install the package with npm install immer.
How do I install Immer?
Run npm install immer in your project folder. The README gives this as the install method.
What is Immer used for?
Immer lets you write code that modifies a draft of your data while it produces a new immutable state. It is described as useful for Redux-style reducers and nested state.
What are alternatives to Immer?
Comparable projects include Immutable.js, Mutative and Redux Toolkit. Each takes a different approach to immutable state.
Where can I find Immer's documentation?
The documentation is hosted at https://immerjs.github.io/immer/. The README excerpt does not cover the API in detail.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Immer suits JavaScript developers who find hand-written immutable updates verbose, especially for nested state in reducers. Teams that need a full state management framework, or who do not use JavaScript or TypeScript, should look at other options.
Install options & downloads