From b34cd8d8c6e8d3d15df59ffa26455a9ebb647579 Mon Sep 17 00:00:00 2001 From: Reece Dunham Date: Wed, 3 Feb 2021 18:27:02 +0000 Subject: [PATCH] Fix installation docs --- website/docs/api.md | 30 +++++++++---------- .../{installation.md => installation.mdx} | 12 +++++--- 2 files changed, 23 insertions(+), 19 deletions(-) rename website/docs/{installation.md => installation.mdx} (89%) diff --git a/website/docs/api.md b/website/docs/api.md index 81711d29..83108987 100644 --- a/website/docs/api.md +++ b/website/docs/api.md @@ -9,30 +9,30 @@ title: API overview | Exported name | Description | Section | | --- | --- | --- | -| `(default)` | The core API of Immer, typically named `produce`: `import produce from "immer"` | [Produce](produce.md) | -| `applyPatches` | Given a base state or draft, and a set of patches, applies the patches | [Patches](patches.md) | -| `castDraft` | Converts any immutable type to its mutable counterpart. This is just a cast and doesn't actually do anything. | [TypeScript](typescript.md) | -| `castImmutable` | Converts any mutable type to its immutable counterpart. This is just a cast and doesn't actually do anything. | [TypeScript](typescript.md) | -| `createDraft` | Given a base state, creates a mutable draft for which any modifications will be recorded | [Async](async.md) | -| `current` | Given a draft object (doesn't have to be a tree root), takes a snapshot of the current state of the draft | [Current](current.md) | -| `Draft` | Exposed TypeScript type to convert an immutable type to a mutable type | [TypeScript](typescript.md) | +| `(default)` | The core API of Immer, typically named `produce`: `import produce from "immer"` | [Produce](produce) | +| `applyPatches` | Given a base state or draft, and a set of patches, applies the patches | [Patches](patches) | +| `castDraft` | Converts any immutable type to its mutable counterpart. This is just a cast and doesn't actually do anything. | [TypeScript](typescript) | +| `castImmutable` | Converts any mutable type to its immutable counterpart. This is just a cast and doesn't actually do anything. | [TypeScript](typescript) | +| `createDraft` | Given a base state, creates a mutable draft for which any modifications will be recorded | [Async](async) | +| `current` | Given a draft object (doesn't have to be a tree root), takes a snapshot of the current state of the draft | [Current](current) | +| `Draft` | Exposed TypeScript type to convert an immutable type to a mutable type | [TypeScript](typescript) | | `enableAllPlugins()` | Enables all plugins mentioned below | [Installation](installation#pick-your-immer-version) | | `enableES5()` | Enables support for older JavaScript engines, such as Internet Explorer and React Native | [Installation](installation#pick-your-immer-version) | | `enableMapSet()` | Enables support for `Map` and `Set` collections. | [Installation](installation#pick-your-immer-version) | | `enablePatches()` | Enables support for JSON patches. | [Installation](installation#pick-your-immer-version) | -| `finishDraft` | Given an draft created using `createDraft`, seals the draft and produces and returns the next immutable state that captures all the changes | [Async](async.md) | +| `finishDraft` | Given an draft created using `createDraft`, seals the draft and produces and returns the next immutable state that captures all the changes | [Async](async) | | `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. | | `Immer` | constructor 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. | -| `immerable` | Symbol that can be added to a constructor or prototype, to indicate that Immer should treat the class as something that can be safely drafted | [Classes](complex-objects.md) | +| `immerable` | Symbol that can be added to a constructor or prototype, to indicate that Immer should treat the class as something that can be safely drafted | [Classes](complex-objects) | | `Immutable` | Exposed TypeScript type to convert mutable types to immutable types | | | `isDraft` | Returns true if the given object is a draft object | | | `isDraftable` | Returns 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 | | -| `nothing` | Value that can be returned from a recipe, to indicate that the value `undefined` should be produced | [Return](return.md) | -| `original` | Given 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 present | [Original](original.md) | -| `Patch` | Exposed TypeScript type, describes the shape of an (inverse) patch object | [Patches](patches.md) | -| `produce` | The core API of Immer, also exposed as the `default` export | [Produce](produce.md) | -| `produceWithPatches` | Works the same as `produce`, but instead of just returning the produced object, it returns a tuple, consisting of `[result, patches, inversePatches]`. | [Patches](patches.md) | -| `setAutoFreeze` | Enables / disables automatic freezing of the trees produces. By default enabled. | [Freezing](freezing.md) | +| `nothing` | Value that can be returned from a recipe, to indicate that the value `undefined` should be produced | [Return](return) | +| `original` | Given 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 present | [Original](original) | +| `Patch` | Exposed TypeScript type, describes the shape of an (inverse) patch object | [Patches](patches) | +| `produce` | The core API of Immer, also exposed as the `default` export | [Produce](produce) | +| `produceWithPatches` | Works the same as `produce`, but instead of just returning the produced object, it returns a tuple, consisting of `[result, patches, inversePatches]`. | [Patches](patches) | +| `setAutoFreeze` | Enables / disables automatic freezing of the trees produces. By default enabled. | [Freezing](freezing) | | `setUseProxies` | Can be used to disable or force the use of `Proxy` objects. Useful when filing bug reports. | | ## Importing immer diff --git a/website/docs/installation.md b/website/docs/installation.mdx similarity index 89% rename from website/docs/installation.md rename to website/docs/installation.mdx index a2fcfddb..e471969b 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.mdx @@ -4,7 +4,11 @@ title: Installation ---
-
+
Immer can be installed as a direct dependency, and will work in any ES5 environment: @@ -27,8 +31,8 @@ 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()` | +| [ES2015 Map and Set support](complex-objects) | To enable Immer to operate on the native `Map` and `Set` collections, enable this feature | `enableMapSet()` | +| [JSON Patch support](patches) | 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: @@ -75,4 +79,4 @@ Import size report for immer: 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()` +Since version 6, support for the fallback implementation has to be explicitly enabled by calling `enableES5()`.