Julien Deniau

Immutable.js: a new website, and a v6 on the way

Immutable.js gets 28 million downloads a week, and the project is a lot more active than most people assume. Case in point: two announcements at once. The website has just been fully rebuilt, and v6 is in beta.

Why redo the website?

Because it was starting to show its age. To give you an idea: the tagline of the documentation had been "Read the docs and eat your vegetables." for years. I like it, but it was a pretty faithful summary of the general vibe of the site.

The documentation itself was already fine: since 5.1.3, we moved from docs autogenerated out of the .d.ts file to real markdown documentation, with runnable examples on almost every method.

What wasn't fine was everything around it: the home page was a raw README render behind an animated cover, there was no dark theme, and on mobile it was hard to find what you were looking for.

Three things changed in particular.

1. A light / dark / auto theme

In 2026, the world is split in two: people who want a readable theme, and people who want a black one. Personally, I read docs in light mode. Fine, ok, I write code in dark mode. So we needed both.

The theme has three states: light, dark, and auto. Auto follows prefers-color-scheme live — if your OS switches to dark at 7pm, the page switches with it, no reload. Your choice is persisted across visits. And the whole site follows the theme, including code blocks and the editor: no more blindingly white code block sitting in the middle of a dark page.

2. Mobile

The site used to be built for desktop, and vaguely adapted for mobile.

Now there is a single sticky header shared by every page (logo, nav, search, theme switch, GitHub star pill) that collapses cleanly into a burger menu. And the docs sidebar folds away behind a toggle instead of eating half the screen.

Not a glamorous thing to write about, but it's what makes the biggest difference when you're looking up the signature of mergeDeep from your phone on the subway.

3. The playground

The playground is now full-viewport, with a real toolbar: presets to get started, a Reset button, a Run button, and two side-by-side editor / result panes.

The genuinely useful part: the Share button. Your code is base64-encoded into the URL hash and restored on load. In practice, that means you can now paste a link to a reproducible case into a GitHub issue or on StackOverflow, without anyone having to install anything.

The rest

For completeness: a new home page (hero, a tour of the collection family, a "why immutable" grid, tabbed examples, a live REPL), three-column docs with a version selector and an on-page table of contents, and a dedicated page for the browser extension with before/after screenshots.

One important point: this is a presentation-layer change only. The MDX content and the generated API definitions haven't moved an inch. Which also means no URL changed.

👉 immutable-js.com

So, what about v6?

The website was the warm-up. The main event is v6, which is in beta.

Moving to modern JavaScript

Until now, Immutable was compiled down to ES2015 with buble. It's 2026, and every browser we seriously target supports classes.

So: buble → babel, and we now only transpile for last 2 versions + not dead.

This is a deliberate breaking change: it means dropping the old browsers that were supported up to v5 (IE ≤ 12, Safari ≤ 8). If you still need to support them, you can transpile node_modules/immutable/dist/immutable.js yourself — and let's be honest, you're probably already doing that for half of your dependencies.

The nice side effect is bundle size:

file before after
immutable.es.js 175ko 148ko
immutable.es.js (gzip) 37ko 32ko
immutable.js 197ko 158ko
immutable.min.js 67ko 57ko

Small note: these numbers only measure the buble → babel migration, not the code cleanup that follows. So they're on the pessimistic side.

Migrating to TypeScript

This is the deep work. The codebase is progressively moving from JavaScript to TypeScript — not the docs, not the .d.ts files (those were already there), but the source code itself.

It started quietly in 5.1.x with isolated files (Iterator.ts, Hash.ts, Math.ts, toJS.ts…) with zero runtime change, and it continues in 6.x on the bigger pieces.

What's in it for you: typing bugs between the implementation and the public definitions disappear by construction. No more cases where the .d.ts promises something the JS doesn't actually do.

For me, as a maintainer: I can finally touch List's trie without being scared. That's not nothing on a library this old.

What breaks

There are breaking changes, but don't worry, the list is short and there are no traps:

  • instanceof no longer works on factories. Map(), List(), Set(), Record(), Seq()… are factories, not class constructors. We used to rely on old class functions, and we don't anymore.

diff

  - m instanceof Map;  // doesn't work anymore
  + Map.isMap(m);      // use this instead

Worth noting: instanceof was never the recommended way to test for an Immutable collection. It just happened to work.

  • Empty collections are no longer singletons. Map() === Map() used to be true, while Set.of('a') !== Set.of('a'). We already fixed that inconsistency for List in 5.0; it's now true everywhere.
  • TypeScript 5 minimum. We use const type parameters for getIn types. TS 5.0 is more than two years old, it's time.
  • transducers-js compatibility is gone. cognitect-labs/transducers-js has been archived since 2023; we weren't going to maintain a bridge to a dead project.
  • The legacy '@@iterator' key is no longer recognized. If you have an object exposing its iterator only under that pre-ES2015 key, it will now be treated as a plain object by Seq(), Collection(), fromJS(). Define a real Symbol.iterator method instead.

The full changelog has all the details, PR by PR.

How do I test the beta?

bash

npm i immutable@next

Here's what I'd suggest: a dedicated branch, install the beta, run your test suite, and see what blows up.

It really is that simple, and it's exactly what I need.

Speaking of which, I need you

Let me be blunt: maintaining a project with 28 million downloads a week and almost no direct feedback is hard.

I see the numbers. I see the issues when something breaks. But I don't know how you use the library day to day, what you're missing, or which v6 decisions are going to hurt you.

So if Immutable.js runs in your stack:

  • Install the beta and tell me what breaks — even "nothing broke" is useful to me.
  • If you have doubts about a breaking change, open a discussion. There's still time to walk something back, and it's far easier now than after the release.
  • And if the new website hurts your eyes somewhere, or you like it, come tell me what you think in this GitHub discussion.

Now is the right time to complain. 🙂