Skip to content

Latest commit

 

History

History
75 lines (55 loc) · 4.05 KB

installation.md

File metadata and controls

75 lines (55 loc) · 4.05 KB
Raw
id title
installation
Installation

Immer can be installed as a direct dependency, and will work in any ES5 environment:

  • Yarn: yarn add immer
  • NPM: npm install immer
  • CDN: Exposed global is immer
    • Unpkg: <script src="https://unpkg.com/immer/dist/immer.umd.js"></script>
    • JSDelivr: <script src="https://cdn.jsdelivr.net/npm/immer/dist/immer.umd.js"></script>

Pick your Immer version

This section only applies to version 6 and later

To make sure Immer is as small as possible, features that are not required by every project has been made opt-in, and have to be enabled explicitly. This ensures that when bundling your application for production, unused features don't take any space.

The following features can be opt-in to:

Feature Description Method to call
ES 5 support If your application needs to be able to run on older JavaScript environments, such as Internet Explorer or React Native, enable this feature. enableES5()
ES2015 Map and Set support To enable Immer to operate on the native Map and Set collections, enable this feature enableMapSet()
JSON Patch support Immer can keep track of all the changes you make to draft objects. This can be useful for communicating changes using JSON patches enablePatches()
All of the above Unsure what features you need? We recommend to enable all of the features above by default on new projects. Premature optimization of a few KB might not be worth the initial trouble. Also, enabling or disabling features doesn't impact the performance of Immer itself enableAllPlugins()

For example, if you want to use produce on a Map, you need to enable this feature once during the start of your application:

// In your application's entrypoint
import {enableMapSet} from "immer"

enableMapSet()

// ...later
import produce from "immer"

const usersById_v1 = new Map([
	["michel", {name: "Michel Weststrate", country: "NL"}]
])

const usersById_v2 = produce(usersById_v1, draft => {
	draft.get("michel").country = "UK"
})

expect(usersById_v1.get("michel").country).toBe("NL")
expect(usersById_v2.get("michel").country).toBe("UK")

Vanilla Immer kicks in at ~3KB gzipped. Every plugin that is enabled adds < 1 KB to that. The breakdown is as follows:

Import size report for immer (minified, gzipped, in bytes):
┌───────────────────────┬───────────┬────────────┬───────────┐
│        (index)        │ just this │ cumulative │ increment │
├───────────────────────┼───────────┼────────────┼───────────┤
│ import * from 'immer' │   5610    │     0      │     0     │
│        produce        │   3141    │    3141    │     0     │
│       enableES5       │   3926    │    3934    │    793    │
│     enableMapSet      │   3940    │    4704    │    770    │
│     enablePatches     │   3839    │    5391    │    687    │
│   enableAllPlugins    │   5387    │    5425    │    34     │
└───────────────────────┴───────────┴────────────┴───────────┘
(this report was generated by npmjs.com/package/import-size)

Immer on older JavaScript environments?

By default produce tries to use proxies for optimal performance. However, on older JavaScript engines Proxy is not available. For example, when running Microsoft Internet Explorer or React Native (if < v0.59 or when using the Hermes engine) on Android. In such cases, Immer will fallback to an ES5 compatible implementation which works identically, but is a bit slower.

Since version 6, support for the fallback implementation has to be explicitly enabled by calling enableES5()