User Tools

Site Tools


Table of Contents

Immutable.js Introduction

Why use Immutable?

1. Getting a nested value from an object without checking if it exists

//in normal Javascript

//define data
const data = { my: { nested: { name: 'Will' } } };

//this data exists
const goodName =;
console.log(goodName); // prints Will

//this does not, and throws an error
const badName =;
// throws error: 'Cannot read name of undefined'

//in Immutable

//define data
const data = fromJS({ my: { nested: { name: 'Will' } } });

//this data exists
const goodName = data.getIn(['my', 'nested', 'name']);
console.log(goodName); // prints Will

//no such data, but no error
const badName = data.getIn(['my', 'lovely', 'name']);
console.log(badName); // prints undefined - no error thrown

2. Chaining manipulations - allows you to do this:

const pets = List(['cat', 'dog']);
const finalPets = pets.push('goldfish').push('tortoise');

3. Immutable data - Well of course =D


Your data structures change predictably

Robust data manipulation

Concise readable code

“ At Pilcro, we introduced Immutable into our applications about 12 months ago. It has been one of the best decisions we have made. Our apps are now much more readable, robust, bug-free and predictable.”

Installing Immutable

For a react or rails/react app, open a terminal, cd to the proper directory, and enter this command

yarn add immutable

Then in app/javascript/packs, create a new .js file. Let's call it “immutable.js”. Paste the following code inside it.

import { Map } from 'immutable';

const immutablePerson = Map({ name: 'Will' });
const person = immutablePerson.toJS();


Then, open a rails view file, and paste this code

<div id=immutable></div>
<%= javascript_pack_tag 'immutable' %>

Finally, run your app, and navigate to the view location

An alert popup should appear, saying “Will”. If that happens, you've properly installed immutable.

Things to remember

Data structures should be thought of as EITHER plain JavaScript OR Immutable.

Operations on an Immutable object return the result of the operation.

Operations on an Immutable object do not change the object itself, but instead create a new object.

Converting into Immutable

In normal JavaScript, we know two common data types: Object {} and Array [].

To translate these into Immutable:

Object {} becomes Map Map({})

Array [] becomes List List([])

To convert normal JavaScript into Immutable, we can use the Map, List, or fromJS functions that Immutable provides:

import { Map, List, fromJS } from 'immutable';

// Normal Javascript
const person = {
  name: 'Will',
  pets: ['cat', 'dog']

// To create the equivalent in Immutable:
const immutablePerson = Map({
  name: 'Will',
  pets: List(['cat', 'dog'])

// Or ...
const immutablePerson = fromJS(person);

fromJS is a useful function that converts nested data into Immutable. It creates Maps and Lists in the conversion.

Converting back from Immutable to normal JavaScript

It is very simple to get your data back from Immutable to plain old JavaScript. You just call the .toJS() method on your Immutable object.

import { Map } from 'immutable';
const immutablePerson = Map({ name: 'Will' });
const person = immutablePerson.toJS();
console.log(person); // prints { name: 'Will' };

Learn more: check out

immutable.js_introduction.txt · Last modified: 2018/09/10 23:26 by