docs: Update to docusaurus 2

immerjs · Mar 17, 2021 · 42aac95 · 42aac95
2 parents 9b8c9aa + 5d6a5d7
commit 42aac95
Show file tree

Hide file tree

Showing 36 changed files with 6,943 additions and 3,627 deletions.
diff --git a/.gitignore b/.gitignore
@@ -60,4 +60,5 @@ typings/
 .idea
 /dist/
 website/build
+website/.docusaurus
 .rts2*
diff --git a/docs/example-setstate.md b/docs/example-setstate.md
diff --git a/website/core/Footer.js b/website/core/Footer.js
diff --git a/docs/api.md → website/docs/api.md b/docs/api.md → 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<T>` | 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<T>` | 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<T>` | 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/docs/async.md → website/docs/async.mdx b/docs/async.md → website/docs/async.mdx
@@ -5,16 +5,31 @@ sidebar_label: Async produce / createDraft
 ---
 
 <center>
-<div data-ea-publisher="immerjs" data-ea-type="image" class="horizontal bordered"></div>
-</center>
-
-<details>
-    <summary style="color: white; background:#c200c2;padding:5px;margin:5px;border-radius:2px">egghead.io lesson 11: Creating _async_ producers (and why you shouldn’t)</summary>
-    <br>
-    <div style="padding:5px;">
-        <iframe style="border: none;" width=760 height=427 scrolling="no" src="https://egghead.io/lessons/react-write-asynchronous-producers-in-immer-and-why-you-shouldn-t/embed" ></iframe>
-    </div>
-    <a style="font-style:italic;padding:5px;margin:5px;"  href="https://egghead.io/lessons/react-write-asynchronous-producers-in-immer-and-why-you-shouldn-t">Hosted on egghead.io</a>
+	<div
+		data-ea-publisher="immerjs"
+		data-ea-type="image"
+		className="horizontal bordered"
+	></div>
+</center> <details>
+	<summary className="egghead-summary">
+		egghead.io lesson 11: Creating <b>async</b> producers (and why you
+		shouldn’t)
+	</summary>
+	<br />
+	<div>
+		<iframe
+			width="760"
+			height="427"
+			scrolling="no"
+			src="https://egghead.io/lessons/react-write-asynchronous-producers-in-immer-and-why-you-shouldn-t/embed"
+		></iframe>
+	</div>
+	<a
+		className="egghead-link"
+		href="https://egghead.io/lessons/react-write-asynchronous-producers-in-immer-and-why-you-shouldn-t"
+	>
+		Hosted on egghead.io
+	</a>
 </details>
 
 It is allowed to return Promise objects from recipes. Or, in other words, to use `async / await`. This can be pretty useful for long running processes, that only produce the new object once the promise chain resolves. Note that `produce` itself (even in the curried form) will return a promise if the producer is async. Example:

diff --git a/docs/built-with.md → website/docs/built-with.md b/docs/built-with.md → website/docs/built-with.md
diff --git a/docs/complex-objects.md → website/docs/complex-objects.md b/docs/complex-objects.md → website/docs/complex-objects.md
diff --git a/docs/current.md → website/docs/current.md b/docs/current.md → website/docs/current.md
diff --git a/docs/curried-produce.md → website/docs/curried-produce.mdx b/docs/curried-produce.md → website/docs/curried-produce.mdx
@@ -4,16 +4,30 @@ title: Curried producers
 ---
 
 <center>
-<div data-ea-publisher="immerjs" data-ea-type="image" class="horizontal bordered"></div>
-</center>
-
-<details>
-    <summary style="color: white; background:#c200c2;padding:5px;margin:5px;border-radius:2px">egghead.io lesson 6: Simplify code by using curried _reduce_</summary>
-    <br>
-    <div style="padding:5px;">
-        <iframe style="border: none;" width=760 height=427 scrolling="no" src="https://egghead.io/lessons/javascript-simplify-immer-producer-functions-using-currying/embed" ></iframe>
-    </div>
-    <a style="font-style:italic;padding:5px;margin:5px;"  href="https://egghead.io/lessons/javascript-simplify-immer-producer-functions-using-currying">Hosted on egghead.io</a>
+	<div
+		data-ea-publisher="immerjs"
+		data-ea-type="image"
+		className="horizontal bordered"
+	></div>
+</center> <details>
+	<summary className="egghead-summary">
+		egghead.io lesson 6: Simplify code by using curried _reduce_
+	</summary>
+	<br />
+	<div>
+		<iframe
+			width="760"
+			height="427"
+			scrolling="no"
+			src="https://egghead.io/lessons/javascript-simplify-immer-producer-functions-using-currying/embed"
+		></iframe>
+	</div>
+	<a
+		className="egghead-link"
+		href="https://egghead.io/lessons/javascript-simplify-immer-producer-functions-using-currying"
+	>
+		Hosted on egghead.io
+	</a>
 </details>
 
 Passing a function as the first argument to `produce` is intended to be used for currying. This means that you get a pre-bound producer that only needs a state to produce the value from. The producer function gets passed in the draft and any further arguments that were passed to the curried function.

diff --git a/docs/example-reducer.md → website/docs/example-reducer.mdx b/docs/example-reducer.md → website/docs/example-reducer.mdx
@@ -4,23 +4,37 @@ title: Example Reducer
 ---
 
 <center>
-<div data-ea-publisher="immerjs" data-ea-type="image" class="horizontal bordered"></div>
-</center>
-
-<details>
-    <summary style="color: white; background:#c200c2;padding:5px;margin:5px;border-radius:2px">egghead.io lesson 13: Using Immer in a (React) reducer</summary>
-    <br>
-    <div style="padding:5px;">
-        <iframe style="border: none;" width=760 height=427 scrolling="no" src="https://egghead.io/lessons/react-update-immutable-state-with-react-usereducer-through-immer/embed" ></iframe>
-    </div>
-    <a style="font-style:italic;padding:5px;margin:5px;"  href="https://egghead.io/lessons/react-update-immutable-state-with-react-usereducer-through-immer">Hosted on egghead.io</a>
+	<div
+		data-ea-publisher="immerjs"
+		data-ea-type="image"
+		className="horizontal bordered"
+	></div>
+</center> <details>
+	<summary className="egghead-summary">
+		egghead.io lesson 13: Using Immer in a (React) reducer
+	</summary>
+	<br />
+	<div>
+		<iframe
+			width="760"
+			height="427"
+			scrolling="no"
+			src="https://egghead.io/lessons/react-update-immutable-state-with-react-usereducer-through-immer/embed"
+		></iframe>
+	</div>
+	<a
+		className="egghead-link"
+		href="https://egghead.io/lessons/react-update-immutable-state-with-react-usereducer-through-immer"
+	>
+		Hosted on egghead.io
+	</a>
 </details>
 
 Here is a simple example of the difference that Immer could make in practice.
 
 ```javascript
 // Reducer with inital state
-const INITIAL_STATE = {};
+const INITIAL_STATE = {}
 // Shortened, based on: https://github.com/reactjs/redux/blob/master/examples/shopping-cart/src/reducers/products.js
 const byId = (state = INITIAL_STATE, action) => {
 	switch (action.type) {
@@ -44,7 +58,7 @@ After using Immer, our reducer can be expressed as:
 import produce from "immer"
 
 // Reducer with inital state
-const INITIAL_STATE = {};
+const INITIAL_STATE = {}
 
 const byId = produce((draft, action) => {
 	switch (action.type) {

diff --git a/website/docs/example-setstate.mdx b/website/docs/example-setstate.mdx
@@ -0,0 +1,59 @@
+---
+id: example-setstate
+title: React setState example
+---
+
+<center>
+	<div
+		data-ea-publisher="immerjs"
+		data-ea-type="image"
+		className="horizontal bordered"
+	></div>
+</center> <details>
+	<summary className="egghead-summary">
+		egghead.io lesson 8: Using Immer with _useState_. Or: _useImmer_
+	</summary>
+	<br />
+	<div>
+		<iframe
+			width="760"
+			height="427"
+			scrolling="no"
+			src="https://egghead.io/lessons/react-immutable-update-state-inside-react-components-with-useimmer/embed"
+		></iframe>
+	</div>
+	<a
+		className="egghead-link"
+		href="https://egghead.io/lessons/react-immutable-update-state-inside-react-components-with-useimmer"
+	>
+		Hosted on egghead.io
+	</a>
+</details>
+
+Deep updates in the state of React components can be greatly simplified as well by using immer. Take for example the following onClick handlers (Try in [codesandbox](https://codesandbox.io/s/m4yp57632j)):
+
+```javascript
+/**
+ * Classic React.setState with a deep merge
+ */
+onBirthDayClick1 = () => {
+	this.setState(prevState => ({
+		user: {
+			...prevState.user,
+			age: prevState.user.age + 1
+		}
+	}))
+}
+
+/**
+ * ...But, since setState accepts functions,
+ * we can just create a curried producer and further simplify!
+ */
+onBirthDayClick2 = () => {
+	this.setState(
+		produce(draft => {
+			draft.user.age += 1
+		})
+	)
+}
+```
diff --git a/docs/faq.md → website/docs/faq.md b/docs/faq.md → website/docs/faq.md
@@ -22,7 +22,7 @@ A: Yes
 
 ## Q: I can't rely on Proxies being present on my target environments. Can I use Immer?
 
-A: Yes [details](https://immerjs.github.io/immer/docs/installation#immer-on-older-javascript-environments)
+A: Yes - [view details](installation#immer-on-older-javascript-environments)
 
 ## Q: Can I typecheck my data structures when using Immer?
 

diff --git a/docs/freezing.md → website/docs/freezing.mdx b/docs/freezing.md → website/docs/freezing.mdx
@@ -4,16 +4,30 @@ title: Auto freezing
 ---
 
 <center>
-<div data-ea-publisher="immerjs" data-ea-type="image" class="horizontal bordered"></div>
-</center>
-
-<details>
-    <summary style="color: white; background:#c200c2;padding:5px;margin:5px;border-radius:2px">egghead.io lesson 7: Immer automatically freezes data</summary>
-    <br>
-    <div style="padding:5px;">
-        <iframe style="border: none;" width=760 height=427 scrolling="no" src="https://egghead.io/lessons/javascript-produces-immutable-data-and-avoid-unnecessary-creation-of-new-data-trees-with-immer/embed" ></iframe>
-    </div>
-    <a style="font-style:italic;padding:5px;margin:5px;"  href="https://egghead.io/lessons/javascript-produces-immutable-data-and-avoid-unnecessary-creation-of-new-data-trees-with-immer">Hosted on egghead.io</a>
+	<div
+		data-ea-publisher="immerjs"
+		data-ea-type="image"
+		className="horizontal bordered"
+	></div>
+</center> <details>
+	<summary className="egghead-summary">
+		egghead.io lesson 7: Immer automatically freezes data
+	</summary>
+	<br />
+	<div>
+		<iframe
+			width="760"
+			height="427"
+			scrolling="no"
+			src="https://egghead.io/lessons/javascript-produces-immutable-data-and-avoid-unnecessary-creation-of-new-data-trees-with-immer/embed"
+		></iframe>
+	</div>
+	<a
+		className="egghead-link"
+		href="https://egghead.io/lessons/javascript-produces-immutable-data-and-avoid-unnecessary-creation-of-new-data-trees-with-immer"
+	>
+		Hosted on egghead.io
+	</a>
 </details>
 
 Immer automatically freezes any state trees that are modified using `produce`. This protects against accidental modifications of the state tree outside of a producer. In most cases this provides the most optimal behavior, but `setAutoFreeze(true / false)` can be used to explicitly turn this feature on or off.