Morph MORPH
SIGN IN SIGN UP
immerjs / immer UNCLAIMED

Create the next immutable state by mutating the current one

28907 0 0 JavaScript
Normal View History Raw
Docs WIP
2019-09-12 20:18:26 +02:00
---
id: installation
title: Installation
---
<div id="codefund"><!-- fallback content --></div>
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>`
Updated docs
2020-02-22 18:14:25 +00:00
## 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](complex-objects.md) | To enable Immer to operate on the native `Map` and `Set` collections, enable this feature | `enableMapSet()` |
| [JSON Patch support](patches.md) | 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:
```typescript
// 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:
```
removed notes file
2020-03-03 19:31:15 +00:00
Import size report for immer:
Updated docs
2020-02-22 18:14:25 +00:00
┌───────────────────────┬───────────┬────────────┬───────────┐
│ (index) │ just this │ cumulative │ increment │
├───────────────────────┼───────────┼────────────┼───────────┤
removed notes file
2020-03-03 19:31:15 +00:00
│ import * from 'immer' │ 5606 │ 0 │ 0 │
│ produce │ 3085 │ 3085 │ 0 │
│ enableES5 │ 3870 │ 3878 │ 793 │
│ enableMapSet │ 3893 │ 4654 │ 776 │
│ enablePatches │ 3826 │ 5387 │ 733 │
│ enableAllPlugins │ 5382 │ 5421 │ 34 │
Updated docs
2020-02-22 18:14:25 +00:00
└───────────────────────┴───────────┴────────────┴───────────┘
(this report was generated by npmjs.com/package/import-size)
```
Docs WIP
2019-09-12 20:18:26 +02:00
## Immer on older JavaScript environments?
Fixes word form The adverb form makes more sense here
2019-11-06 11:56:19 -05:00
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.
Updated docs
2020-02-22 18:14:25 +00:00
Since version 6, support for the fallback implementation has to be explicitly enabled by calling `enableES5()`
Reference in New Issue Copy Permalink