API overview

Exported nameDescriptionSection
(default)The core API of Immer, typically named produce: import produce from "immer"Produce
applyPatchesGiven a base state or draft, and a set of patches, applies the patchesPatches
castDraftConverts any immutable type to its mutable counterpart. This is just a cast and doesn't actually do anything.TypeScript
castImmutableConverts any mutable type to its immutable counterpart. This is just a cast and doesn't actually do anything.TypeScript
createDraftGiven a base state, creates a mutable draft for which any modifications will be recordedAsync
currentGiven a draft object (doesn't have to be a tree root), takes a snapshot of the current state of the draftCurrent
Draft<T>Exposed TypeScript type to convert an immutable type to a mutable typeTypeScript
enableAllPlugins()Enables all plugins mentioned belowInstallation
enableES5()Enables support for older JavaScript engines, such as Internet Explorer and React NativeInstallation
enableMapSet()Enables support for Map and Set collections.Installation
enablePatches()Enables support for JSON patches.Installation
finishDraftGiven an draft created using createDraft, seals the draft and produces and returns the next immutable state that captures all the changesAsync
freeze(obj, deep?)Freezes draftable objects. Returns the original object. By default freezes shallowly, but if the second argument is true it will freeze recursively.
Immerconstructor that can be used to create a second "immer" instance (exposing all APIs listed in this instance), that doesn't share its settings with global instance.
immerableSymbol that can be added to a constructor or prototype, to indicate that Immer should treat the class as something that can be safely draftedClasses
Immutable<T>Exposed TypeScript type to convert mutable types to immutable types
isDraftReturns true if the given object is a draft object
isDraftableReturns true if Immer is capable of turning this object into a draft. Which is true for: arrays, objects without prototype, objects with Object as their prototype, objects that have the immerable symbol on their constructor or prototype
nothingValue that can be returned from a recipe, to indicate that the value undefined should be producedReturn
originalGiven a draft object (doesn't have to be a tree root), returns the original object at the same path in the original state tree, if presentOriginal
PatchExposed TypeScript type, describes the shape of an (inverse) patch objectPatches
produceThe core API of Immer, also exposed as the default exportProduce
produceWithPatchesWorks the same as produce, but instead of just returning the produced object, it returns a tuple, consisting of [result, patches, inversePatches].Patches
setAutoFreezeEnables / disables automatic freezing of the trees produces. By default enabled.Freezing
setUseProxiesCan be used to disable or force the use of Proxy objects. Useful when filing bug reports.

Importing immer#

produce is exposed as the default export, but optionally it can be used as name import as well, as this benefits some older project setups. So the following imports are all correct, where the first is recommended:

import produce from "immer"
import {produce} from "immer"
const {produce} = require("immer")
const produce = require("immer").produce
const produce = require("immer").default
import unleashTheMagic from "immer"
import {produce as unleashTheMagic} from "immer"