Immutable-js Dev Tools

The Immutable library is fantastic, but inspecting immutable collections in browser's Dev Tools is awkward. You only see the internal data structure, not the logical contents. For example, when inspecting the contents of an Immutable List, you'd really like to see the items in the list.

Chrome (v47+) and Firefox (116+) has support for custom "formatters". A formatter tells browser's Dev Tools how to display values in the Console, Scope list, etc. This means we can display Lists, Maps and other collections, in a much better way.

Essentially, it turns this:

into:

This library provides a formatter and a browser extension to do just that.

Features

The library currently has formatters for:

• List
• Map & OrderedMap
• Set & OrderedSet
• Stack
• Record
• Range
• Repeat (if you wish this, add 👍 to #22)
• Seq — I do not have an idea how to display it. If you know, write it down into #23

Want something more? Write down your wishes!

Installation

Chrome v47+ / Firefox v116+

In Dev Tools, press F1 to load the Settings. Scroll down to the Console section and tick "Enable custom formatters".

Browser Extension

You can directly install the browser extension for Chrome or Firefox. It automatically installs the formatters when you open the DevTools.

• Firefox: https://addons.mozilla.org/fr/firefox/addon/immutable-js-console-formatter/
• Chrome (not working for now): https://chrome.google.com/webstore/detail/immutablejs-object-format/hgldghadipiblonfkkicmgcbbijnpeog

Install in project

Then, in your project, install via npm:

npm install --save-dev @jdeniau/immutable-devtools

And enable with:

import * as Immutable from 'immutable';
import installDevTools = '@jdeniau/immutable-devtools';

installDevTools(Immutable);

Note: You probably only want this library for debug builds, so perhaps wrap with if (DEBUG) {...} or similar.

Why "@jdeniau" ?

We do not have access to the "@immutable" organization on npm. I have opened a dispute for transfert, but it is not yet resolved. Until then, we will use temporary name "@jdeniau" for the package, but hopefully it will be transfered to the immutable organization in the future. If not, we will rename it to something else.

Using with webpack

You could use webpack.DefinePlugin to create a condition that will be allowed to install immutable-devtools in the debug build but unreachable in the production build:

// webpack.config.js
var webpack = require('webpack');
module.exports = {
  // ...
  plugins: [
    new webpack.DefinePlugin({
      __DEV__: JSON.stringify(process.env.NODE_ENV !== 'production'),
    }),
  ],
};

In your source you'd have something like this...

// index.js
import * as Immutable from 'immutable';
import installDevTools from '@jdeniau/immutable-devtools';

if (__DEV__) {
  installDevTools(immutable);
}

And then by adding the -p shortcut to webpack for production mode which enables dead code elimination, the condition that requires immutable-devtools will be removed.

NODE_ENV=production webpack -p index.js

See #16 for more info.

Contributing

devtools

1. Install yarn berry if you don't have it already
2. Clone the project
3. run yarn install
4. run yarn run build on each file you change
5. open the index.html located in the packages/devtools/demo directory and open the console.

Browser extension

1. yarn install
2. yarn build
3. On Chrome:
   1. Open "chrome://extensions"
   2. Enable "Developer mode"
   3. Click "Load unpacked" and select the "packages/extension/extension" directory
4. On Firefox:
   1. On your console, go to the /packages/extension/extension directory
   2. Run web-ext run (you may need to install web-ext)
5. Open devtools settings and enable custom formatters
6. Open "/packages/extensions/test-page/index.html" to check everything looks as expected.

Make sure to reload the extension after any changes.

Original projects

This projet is a fork of andrewdavey/immutable-devtools by Pavel Lang and Andrew Davey, and mattzeunert/immutable-object-formatter-extension by Matt Zeunert.

I tried to contact them via github and by mail, but I didn't get any answer. So I decided to fork it and maintain it on the immutable-js organization directly.