Guide · Open source

How to use immutable-js: install and work with Immutable collections

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Immutable.js is a JavaScript library that provides persistent collections such as List, Map, Set and Record. Instead of changing data in place, its operations return new updated versions, which makes application state easier to track. This guide shows how to install it, create collections, update them safely, and compare values, so you can decide whether it fits your project.

Immutable.jsimmutable-js/immutable-js · ★ 33k · MIT Install options & downloads

Quick start

1Install the package. Run one of the install commands for npm, Yarn, pnpm or Bun to add the immutable package to your project.
2Import a collection. Import Map, List or another collection type from immutable in the module where you need it.
3Create a collection. Pass a plain JavaScript object or array to the collection constructor to create an immutable value.
4Update with set. Call set on the collection to get a new version, and keep the original if you need it.
5Compare values. Use .equals() or Immutable.is() to check whether two collections hold the same data.
6Add types if you use TypeScript. Set the target or lib option to es2015 in tsconfig.json so the included type definitions work.

Install immutable-js with npm, Yarn, pnpm or Bun

Install the `immutable` package with the package manager your project uses. The README lists commands for all four options. You need Node.js or a bundler, or a package manager such as npm, Yarn, pnpm, or Bun.

npm install immutable
yarn add immutable
pnpm add immutable
bun add immutable

Create a Map and update it without changing the original

Import a collection from the package and create it with plain JavaScript values. Calling `set` does not modify the original collection. It returns a new one, so you keep both versions.

Use `get` to read a value from a collection.
Compare the result of `set` with the original to see the change.

import { Map } from 'immutable';
const map1 = Map({ a: 1, b: 2, c: 3 });
const map2 = map1.set('b', 50);
map1.get('b') + ' vs. ' + map2.get('b'); // 2 vs. 50

Compare collections by value with equals()

Immutable collections should be treated as values rather than objects. Two collections with the same contents are not `===` equal, so use `Immutable.is()` or `.equals()` to check value equality.

`map1.equals(map2)` returns true when contents match.
`map1 === map2` checks reference identity and returns false for separate objects.
If an operation produces an identical collection, Immutable.js returns the existing one, so `===` can detect that nothing changed.

import { Map } from 'immutable';
const map1 = Map({ a: 1, b: 2, c: 3 });
const map2 = Map({ a: 1, b: 2, c: 3 });
map1.equals(map2); // true
map1 === map2; // false

Use TypeScript types with Immutable.js v4

Installing `immutable` through npm includes type definitions for Flow (v0.55.0 or higher) and TypeScript (v4.5 or higher). The README says the type definitions need TypeScript's 2015 lib, so set `"target": "es2015"` or `"lib": "es2015"` in `tsconfig.json`, or pass `--target es2015` or `--lib es2015` to `tsc`.

Set the target or lib option before using the types.
Older v3 setups used a reference path to `immutable.d.ts` instead.

Use a script tag in the browser

Immutable.js has no dependencies. You can use a module bundler such as webpack, rollup or browserify, or include the library directly with a script tag from CDNJS or jsDelivr. The script tag form adds `Immutable` to the global scope.

<script src="immutable.min.js"></script>
<script>
  var map1 = Immutable.Map({ a: 1, b: 2, c: 3 });
  var map2 = map1.set('b', 50);
  map1.get('b'); // 2
  map2.get('b'); // 50
</script>

Know what the library is good for

Immutable data makes change tracking simpler, avoids defensive copying, and supports memoization and change detection with simple logic. The README describes structural sharing, which lets the library avoid copying data unnecessarily. It also provides a lazy `Seq` for chaining `map` and `filter` without intermediate collections.

Use `Seq` with `Range` and `Repeat` to create sequences.
Treat collections as values and use `.equals()` for comparisons.
Persistent collections include List, Stack, Map, OrderedMap, Set, OrderedSet and Record.

What people use it for

Tracking application state in React or Flux-style apps where data flows one way.
Memoizing functions by checking whether input collections changed.
Keeping copies of state cheaply, such as for an undo stack, since copies are only references.
Chaining map and filter over large ranges with the lazy Seq API.

Frequently asked questions

How do I install immutable-js?

Run npm install immutable, yarn add immutable, pnpm add immutable or bun add immutable, depending on your package manager. The package is named immutable, not immutable-js.

Is immutable-js free to use?

The project is licensed under the MIT licence. The source does not give further licensing terms, so check the repository for details if you have specific questions.

Does immutable-js include TypeScript types?

Yes. Installing it through npm brings type definitions for Flow and TypeScript. Your tsconfig.json needs target or lib set to es2015.

Why does map1 === map2 return false when the contents match?

The === operator compares object reference identity. Use .equals() or Immutable.is() to compare value equality instead.

What are alternatives to immutable-js?

The project's comparable projects are Immer, Seamless-Immutable, Mori and Immutable-Data-Structures. The source does not compare them in detail, so review each one against your needs.

Can I use immutable-js without a bundler?

Yes. You can include it with a script tag from CDNJS or jsDelivr, which adds Immutable to the global scope. The README also notes it works with AMD loaders such as RequireJS.

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

Immutable.js suits developers managing frequently updated state, especially in React or Flux-style apps, and TypeScript users who want bundled types. Beginners should first learn plain objects and arrays, and projects that need native arrays and objects to interoperate directly may find the conversion cost and separate types a poor fit.

Install options & downloads