From 826965e307817ea55a7c964927931c04c6250f2d Mon Sep 17 00:00:00 2001 From: Mark Erikson Date: Sat, 26 Jun 2021 13:37:50 -0400 Subject: [PATCH 1/4] Rename "recipes" folder to "usage" --- docs/{recipes => usage}/CodeSplitting.md | 0 docs/{recipes => usage}/ComputingDerivedData.md | 0 docs/{recipes => usage}/ConfiguringYourStore.md | 0 docs/{recipes => usage}/ImplementingUndoHistory.md | 0 docs/{recipes => usage}/IsolatingSubapps.md | 0 docs/{recipes => usage}/MigratingToRedux.md | 0 docs/{recipes => usage}/README.md | 0 docs/{recipes => usage}/ReducingBoilerplate.md | 0 docs/{recipes => usage}/ServerRendering.md | 0 docs/{recipes => usage}/Troubleshooting.md | 0 docs/{recipes => usage}/UsageWithTypescript.md | 0 docs/{recipes => usage}/UsingObjectSpreadOperator.md | 0 docs/{recipes => usage}/WritingTests.md | 0 .../structuring-reducers/BasicReducerStructure.md | 0 .../structuring-reducers/BeyondCombineReducers.md | 0 .../structuring-reducers/ImmutableUpdatePatterns.md | 0 docs/{recipes => usage}/structuring-reducers/InitializingState.md | 0 .../structuring-reducers/NormalizingStateShape.md | 0 .../structuring-reducers/PrerequisiteConcepts.md | 0 .../structuring-reducers/RefactoringReducersExample.md | 0 .../structuring-reducers/ReusingReducerLogic.md | 0 .../structuring-reducers/SplittingReducerLogic.md | 0 .../structuring-reducers/StructuringReducers.md | 0 .../structuring-reducers/UpdatingNormalizedData.md | 0 .../structuring-reducers/UsingCombineReducers.md | 0 25 files changed, 0 insertions(+), 0 deletions(-) rename docs/{recipes => usage}/CodeSplitting.md (100%) rename docs/{recipes => usage}/ComputingDerivedData.md (100%) rename docs/{recipes => usage}/ConfiguringYourStore.md (100%) rename docs/{recipes => usage}/ImplementingUndoHistory.md (100%) rename docs/{recipes => usage}/IsolatingSubapps.md (100%) rename docs/{recipes => usage}/MigratingToRedux.md (100%) rename docs/{recipes => usage}/README.md (100%) rename docs/{recipes => usage}/ReducingBoilerplate.md (100%) rename docs/{recipes => usage}/ServerRendering.md (100%) rename docs/{recipes => usage}/Troubleshooting.md (100%) rename docs/{recipes => usage}/UsageWithTypescript.md (100%) rename docs/{recipes => usage}/UsingObjectSpreadOperator.md (100%) rename docs/{recipes => usage}/WritingTests.md (100%) rename docs/{recipes => usage}/structuring-reducers/BasicReducerStructure.md (100%) rename docs/{recipes => usage}/structuring-reducers/BeyondCombineReducers.md (100%) rename docs/{recipes => usage}/structuring-reducers/ImmutableUpdatePatterns.md (100%) rename docs/{recipes => usage}/structuring-reducers/InitializingState.md (100%) rename docs/{recipes => usage}/structuring-reducers/NormalizingStateShape.md (100%) rename docs/{recipes => usage}/structuring-reducers/PrerequisiteConcepts.md (100%) rename docs/{recipes => usage}/structuring-reducers/RefactoringReducersExample.md (100%) rename docs/{recipes => usage}/structuring-reducers/ReusingReducerLogic.md (100%) rename docs/{recipes => usage}/structuring-reducers/SplittingReducerLogic.md (100%) rename docs/{recipes => usage}/structuring-reducers/StructuringReducers.md (100%) rename docs/{recipes => usage}/structuring-reducers/UpdatingNormalizedData.md (100%) rename docs/{recipes => usage}/structuring-reducers/UsingCombineReducers.md (100%) diff --git a/docs/recipes/CodeSplitting.md b/docs/usage/CodeSplitting.md similarity index 100% rename from docs/recipes/CodeSplitting.md rename to docs/usage/CodeSplitting.md diff --git a/docs/recipes/ComputingDerivedData.md b/docs/usage/ComputingDerivedData.md similarity index 100% rename from docs/recipes/ComputingDerivedData.md rename to docs/usage/ComputingDerivedData.md diff --git a/docs/recipes/ConfiguringYourStore.md b/docs/usage/ConfiguringYourStore.md similarity index 100% rename from docs/recipes/ConfiguringYourStore.md rename to docs/usage/ConfiguringYourStore.md diff --git a/docs/recipes/ImplementingUndoHistory.md b/docs/usage/ImplementingUndoHistory.md similarity index 100% rename from docs/recipes/ImplementingUndoHistory.md rename to docs/usage/ImplementingUndoHistory.md diff --git a/docs/recipes/IsolatingSubapps.md b/docs/usage/IsolatingSubapps.md similarity index 100% rename from docs/recipes/IsolatingSubapps.md rename to docs/usage/IsolatingSubapps.md diff --git a/docs/recipes/MigratingToRedux.md b/docs/usage/MigratingToRedux.md similarity index 100% rename from docs/recipes/MigratingToRedux.md rename to docs/usage/MigratingToRedux.md diff --git a/docs/recipes/README.md b/docs/usage/README.md similarity index 100% rename from docs/recipes/README.md rename to docs/usage/README.md diff --git a/docs/recipes/ReducingBoilerplate.md b/docs/usage/ReducingBoilerplate.md similarity index 100% rename from docs/recipes/ReducingBoilerplate.md rename to docs/usage/ReducingBoilerplate.md diff --git a/docs/recipes/ServerRendering.md b/docs/usage/ServerRendering.md similarity index 100% rename from docs/recipes/ServerRendering.md rename to docs/usage/ServerRendering.md diff --git a/docs/recipes/Troubleshooting.md b/docs/usage/Troubleshooting.md similarity index 100% rename from docs/recipes/Troubleshooting.md rename to docs/usage/Troubleshooting.md diff --git a/docs/recipes/UsageWithTypescript.md b/docs/usage/UsageWithTypescript.md similarity index 100% rename from docs/recipes/UsageWithTypescript.md rename to docs/usage/UsageWithTypescript.md diff --git a/docs/recipes/UsingObjectSpreadOperator.md b/docs/usage/UsingObjectSpreadOperator.md similarity index 100% rename from docs/recipes/UsingObjectSpreadOperator.md rename to docs/usage/UsingObjectSpreadOperator.md diff --git a/docs/recipes/WritingTests.md b/docs/usage/WritingTests.md similarity index 100% rename from docs/recipes/WritingTests.md rename to docs/usage/WritingTests.md diff --git a/docs/recipes/structuring-reducers/BasicReducerStructure.md b/docs/usage/structuring-reducers/BasicReducerStructure.md similarity index 100% rename from docs/recipes/structuring-reducers/BasicReducerStructure.md rename to docs/usage/structuring-reducers/BasicReducerStructure.md diff --git a/docs/recipes/structuring-reducers/BeyondCombineReducers.md b/docs/usage/structuring-reducers/BeyondCombineReducers.md similarity index 100% rename from docs/recipes/structuring-reducers/BeyondCombineReducers.md rename to docs/usage/structuring-reducers/BeyondCombineReducers.md diff --git a/docs/recipes/structuring-reducers/ImmutableUpdatePatterns.md b/docs/usage/structuring-reducers/ImmutableUpdatePatterns.md similarity index 100% rename from docs/recipes/structuring-reducers/ImmutableUpdatePatterns.md rename to docs/usage/structuring-reducers/ImmutableUpdatePatterns.md diff --git a/docs/recipes/structuring-reducers/InitializingState.md b/docs/usage/structuring-reducers/InitializingState.md similarity index 100% rename from docs/recipes/structuring-reducers/InitializingState.md rename to docs/usage/structuring-reducers/InitializingState.md diff --git a/docs/recipes/structuring-reducers/NormalizingStateShape.md b/docs/usage/structuring-reducers/NormalizingStateShape.md similarity index 100% rename from docs/recipes/structuring-reducers/NormalizingStateShape.md rename to docs/usage/structuring-reducers/NormalizingStateShape.md diff --git a/docs/recipes/structuring-reducers/PrerequisiteConcepts.md b/docs/usage/structuring-reducers/PrerequisiteConcepts.md similarity index 100% rename from docs/recipes/structuring-reducers/PrerequisiteConcepts.md rename to docs/usage/structuring-reducers/PrerequisiteConcepts.md diff --git a/docs/recipes/structuring-reducers/RefactoringReducersExample.md b/docs/usage/structuring-reducers/RefactoringReducersExample.md similarity index 100% rename from docs/recipes/structuring-reducers/RefactoringReducersExample.md rename to docs/usage/structuring-reducers/RefactoringReducersExample.md diff --git a/docs/recipes/structuring-reducers/ReusingReducerLogic.md b/docs/usage/structuring-reducers/ReusingReducerLogic.md similarity index 100% rename from docs/recipes/structuring-reducers/ReusingReducerLogic.md rename to docs/usage/structuring-reducers/ReusingReducerLogic.md diff --git a/docs/recipes/structuring-reducers/SplittingReducerLogic.md b/docs/usage/structuring-reducers/SplittingReducerLogic.md similarity index 100% rename from docs/recipes/structuring-reducers/SplittingReducerLogic.md rename to docs/usage/structuring-reducers/SplittingReducerLogic.md diff --git a/docs/recipes/structuring-reducers/StructuringReducers.md b/docs/usage/structuring-reducers/StructuringReducers.md similarity index 100% rename from docs/recipes/structuring-reducers/StructuringReducers.md rename to docs/usage/structuring-reducers/StructuringReducers.md diff --git a/docs/recipes/structuring-reducers/UpdatingNormalizedData.md b/docs/usage/structuring-reducers/UpdatingNormalizedData.md similarity index 100% rename from docs/recipes/structuring-reducers/UpdatingNormalizedData.md rename to docs/usage/structuring-reducers/UpdatingNormalizedData.md diff --git a/docs/recipes/structuring-reducers/UsingCombineReducers.md b/docs/usage/structuring-reducers/UsingCombineReducers.md similarity index 100% rename from docs/recipes/structuring-reducers/UsingCombineReducers.md rename to docs/usage/structuring-reducers/UsingCombineReducers.md From 5b1f1692e971b08be87bdc1ddcdfe1df826e59d4 Mon Sep 17 00:00:00 2001 From: Mark Erikson Date: Sat, 26 Jun 2021 14:31:10 -0400 Subject: [PATCH 2/4] Rename "Recipes" section to "Using Redux" - Renamed the "recipes" folder to "usage" - Changed the title to "Using Redux" - Updated all links that pointed to "Recipes" - Updated redirects file to point to new URLs - Removed links to pages for "Migrating" and "Object Spread" . Didn't delete them entirely - some of the material could maybe go somewhere else --- README.md | 9 +- docs/api/createStore.md | 2 +- docs/faq/Actions.md | 4 +- docs/faq/DesignDecisions.md | 4 +- docs/faq/ImmutableData.md | 10 +- docs/faq/OrganizingState.md | 4 +- docs/faq/Performance.md | 8 +- docs/faq/ReactRedux.md | 9 +- docs/faq/Reducers.md | 6 +- docs/introduction/Examples.md | 2 +- docs/introduction/GettingStarted.md | 4 +- docs/style-guide/style-guide.md | 4 +- .../essentials/part-2-app-structure.md | 2 +- .../part-6-performance-normalization.md | 4 +- .../fundamentals/part-7-standard-patterns.md | 2 +- .../fundamentals/part-8-modern-redux.md | 2 +- docs/tutorials/typescript.md | 2 +- .../history-and-design/PriorArt.md | 2 +- docs/usage/ServerRendering.md | 2 +- docs/usage/Troubleshooting.md | 7 +- docs/usage/WritingTests.md | 2 +- docs/usage/{README.md => index.md} | 14 +-- website/_redirects | 95 +++++++++++-------- website/docusaurus.config.js | 2 + website/sidebars.js | 74 +++++++++------ 25 files changed, 152 insertions(+), 124 deletions(-) rename docs/usage/{README.md => index.md} (57%) diff --git a/README.md b/README.md index bf3651abee..1a6d5c9650 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,11 @@ For more details, see [the Installation docs page](https://redux.js.org/introduc The Redux docs are located at **https://redux.js.org**: - [Introduction](https://redux.js.org/introduction/getting-started) -- [Recipes](https://redux.js.org/recipes/recipe-index) +- [Tutorials](https://redux.js.org/tutorials/index) +- [Usage Guides](https://redux.js.org/usage/index) - [FAQ](https://redux.js.org/faq) - [API Reference](https://redux.js.org/api/api-reference) -For PDF, ePub, and MOBI exports for offline reading, and instructions on how to create them, please see: [paulkogel/redux-offline-docs](https://github.com/paulkogel/redux-offline-docs). - -For Offline docs, please see: [devdocs](https://devdocs.io/redux/) - ## Learn Redux ### Redux Essentials Tutorial @@ -62,7 +59,7 @@ The [**Redux Fundamentals tutorial**](https://redux.js.org/tutorials/fundamental ### Other Resources -- The **[Redux FAQ](https://redux.js.org/faq)** answers many common questions about how to use Redux, and the **["Recipes" docs section](https://redux.js.org/recipes/recipe-index)** has information on handling derived data, testing, structuring reducer logic, and reducing boilerplate. +- The **[Redux FAQ](https://redux.js.org/faq)** answers many common questions about how to use Redux, and the **["Using Redux" docs section](https://redux.js.org/usage/index)** has information on handling derived data, testing, structuring reducer logic, and reducing boilerplate. - Redux maintainer Mark Erikson's **["Practical Redux" tutorial series](https://blog.isquaredsoftware.com/series/practical-redux/)** demonstrates real-world intermediate and advanced techniques for working with React and Redux (also available as **[an interactive course on Educative.io](https://www.educative.io/collection/5687753853370368/5707702298738688)**). - The **[React/Redux links list](https://github.com/markerikson/react-redux-links)** has categorized articles on working with [reducers and selectors](https://github.com/markerikson/react-redux-links/blob/master/redux-reducers-selectors.md), [managing side effects](https://github.com/markerikson/react-redux-links/blob/master/redux-side-effects.md), [Redux architecture and best practices](https://github.com/markerikson/react-redux-links/blob/master/redux-architecture.md), and more. - Our community has created thousands of Redux-related libraries, addons, and tools. The **["Ecosystem" docs page](https://redux.js.org/introduction/ecosystem)** lists our recommendations, and also there's a complete listing available in the **[Redux addons catalog](https://github.com/markerikson/redux-ecosystem-links)**. diff --git a/docs/api/createStore.md b/docs/api/createStore.md index 943f35bfbb..c663130228 100644 --- a/docs/api/createStore.md +++ b/docs/api/createStore.md @@ -55,7 +55,7 @@ console.log(store.getState()) - Redux state is normally plain JS objects and arrays. -- If your state is a plain object, make sure you never mutate it! For example, instead of returning something like `Object.assign(state, newData)` from your reducers, return `Object.assign({}, state, newData)`. This way you don't override the previous `state`. You can also write `return { ...state, ...newData }` if you enable the [object spread operator proposal](../recipes/UsingObjectSpreadOperator.md). +- If your state is a plain object, make sure you never mutate it! Immutable updates require making copies of each level of data, typically using the object spread operator ( `return { ...state, ...newData }` ). - For universal apps that run on the server, create a store instance with every request so that they are isolated. Dispatch a few data fetching actions to a store instance and wait for them to complete before rendering the app on the server. diff --git a/docs/faq/Actions.md b/docs/faq/Actions.md index 1676e0ccab..d1c87c63e0 100644 --- a/docs/faq/Actions.md +++ b/docs/faq/Actions.md @@ -35,7 +35,7 @@ Encapsulating and centralizing commonly used pieces of code is a key concept in **Documentation** -- [Reducing Boilerplate](../recipes/ReducingBoilerplate.md#actions) +- [Using Redux: Reducing Boilerplate](../usage/ReducingBoilerplate.md#actions) **Discussion** @@ -55,7 +55,7 @@ No. We suggest you write independent small reducer functions that are each respo **Documentation** - [Fundamentals: State, Actions, Reducers](../tutorials/fundamentals/part-3-state-actions-reducers.md) -- [Recipes: Structuring Reducers](../recipes/structuring-reducers/StructuringReducers.md) +- [Using Redux: Structuring Reducers](../usage/structuring-reducers/StructuringReducers.md) **Discussions** diff --git a/docs/faq/DesignDecisions.md b/docs/faq/DesignDecisions.md index 68e5060036..d70144b006 100644 --- a/docs/faq/DesignDecisions.md +++ b/docs/faq/DesignDecisions.md @@ -93,7 +93,7 @@ The [curried function signature](https://github.com/reactjs/redux/issues/1744) o ### Why doesn't `combineReducers` include a third argument with the entire state when it calls each reducer? -`combineReducers` is opinionated to encourage splitting reducer logic by domain. As stated in [Beyond `combineReducers`](../recipes/structuring-reducers/BeyondCombineReducers.md),`combineReducers` is deliberately limited to handle a single common use case: updating a state tree that is a plain Javascript object by delegating the work of updating each slice of state to a specific slice reducer. +`combineReducers` is opinionated to encourage splitting reducer logic by domain. As stated in [Beyond `combineReducers`](../usage/structuring-reducers/BeyondCombineReducers.md),`combineReducers` is deliberately limited to handle a single common use case: updating a state tree that is a plain Javascript object by delegating the work of updating each slice of state to a specific slice reducer. It's not immediately obvious what a potential third argument to each reducer should be: the entire state tree, some callback function, some other part of the state tree, etc. If `combineReducers` doesn't fit your use case, consider using libraries like [combineSectionReducers](https://github.com/ryo33/combine-section-reducers) or [reduceReducers](https://github.com/acdlite/reduce-reducers) for other options with deeply nested reducers and reducers that require access to the global state. @@ -103,7 +103,7 @@ If none of the published utilities solve your use case, you can always write a f **Articles** -- [Beyond `combineReducers`](../recipes/structuring-reducers/BeyondCombineReducers.md) +- [Beyond `combineReducers`](../usage/structuring-reducers/BeyondCombineReducers.md) **Discussions** diff --git a/docs/faq/ImmutableData.md b/docs/faq/ImmutableData.md index 13e43361d6..7b4e201b0c 100644 --- a/docs/faq/ImmutableData.md +++ b/docs/faq/ImmutableData.md @@ -52,7 +52,7 @@ In particular, immutability in the context of a Web app enables sophisticated ch **Documentation** -- [Recipes: Prerequisite Reducer Concepts](../recipes/structuring-reducers/PrerequisiteConcepts.md) +- [Using Redux: Prerequisite Reducer Concepts](../usage/structuring-reducers/PrerequisiteConcepts.md) **Discussions** @@ -274,8 +274,8 @@ The store will still be updated with the new values for the root state, but beca **Documentation** -- [Recipes: Immutable Update Patterns](../recipes/structuring-reducers/ImmutableUpdatePatterns.md) -- [Troubleshooting: Never mutate reducer arguments](../recipes/Troubleshooting.md#never-mutate-reducer-arguments) +- [Using Redux: Immutable Update Patterns](../usage/structuring-reducers/ImmutableUpdatePatterns.md) +- [Troubleshooting: Never mutate reducer arguments](../usage/Troubleshooting.md#never-mutate-reducer-arguments) ### Why does a reducer mutating the state prevent React-Redux from re-rendering a wrapped component? @@ -451,7 +451,7 @@ JavaScript was never designed to provide guaranteed immutable operations. Accord With JavaScript, you can accidentally mutate an object (such as the Redux state tree) quite easily without realizing it. For example, updating deeply nested properties, creating a new _reference_ to an object instead of a new object, or performing a shallow copy rather than a deep copy, can all lead to inadvertent object mutations, and can trip up even the most experienced JavaScript coder. -To avoid these issues, ensure you follow the recommended [immutable update patterns for ES6](../recipes/structuring-reducers/ImmutableUpdatePatterns.md). +To avoid these issues, ensure you follow the recommended [immutable update patterns for ES6](../usage/structuring-reducers/ImmutableUpdatePatterns.md). ### Verbose Code @@ -469,7 +469,7 @@ In contrast, immutable libraries such as Immer can employ structural sharing, wh **Documentation** -- [Immutable Update Patterns for ES6](../recipes/structuring-reducers/ImmutableUpdatePatterns.md) +- [Immutable Update Patterns for ES6](../usage/structuring-reducers/ImmutableUpdatePatterns.md) **Articles** diff --git a/docs/faq/OrganizingState.md b/docs/faq/OrganizingState.md index ca1ffd889f..c44d4ecefb 100644 --- a/docs/faq/OrganizingState.md +++ b/docs/faq/OrganizingState.md @@ -96,8 +96,8 @@ Data with IDs, nesting, or relationships should generally be stored in a “norm - [Redux Fundamentals: Async Logic and Data Flow](../tutorials/fundamentals/part-6-async-logic.md) - [Redux Fundamentals: Standard Redux Patterns](../tutorials/fundamentals/part-7-standard-patterns.md) - [Examples: Real World example](../introduction/Examples.md#real-world) -- [Recipes: Structuring Reducers - Prerequisite Concepts](../recipes/structuring-reducers/PrerequisiteConcepts.md#normalizing-data) -- [Recipes: Structuring Reducers - Normalizing State Shape](../recipes/structuring-reducers/NormalizingStateShape.md) +- [Using Redux: Structuring Reducers - Prerequisite Concepts](../usage/structuring-reducers/PrerequisiteConcepts.md#normalizing-data) +- [Using Redux: Structuring Reducers - Normalizing State Shape](../usage/structuring-reducers/NormalizingStateShape.md) - [Examples: Tree View](https://github.com/reduxjs/redux/tree/master/examples/tree-view) **Articles** diff --git a/docs/faq/Performance.md b/docs/faq/Performance.md index e7f073b90a..11e36cdf34 100644 --- a/docs/faq/Performance.md +++ b/docs/faq/Performance.md @@ -42,7 +42,7 @@ As for architecture, anecdotal evidence is that Redux works well for varying pro **Documentation** -- [Recipes: Structuring Reducers - Normalizing State Shape](../recipes/structuring-reducers/NormalizingStateShape.md) +- [Using Redux: Structuring Reducers - Normalizing State Shape](../usage/structuring-reducers/NormalizingStateShape.md) **Articles** @@ -103,8 +103,8 @@ However, you _do_ need to create a copied and updated object for each level of n **Documentation** -- [Recipes: Structuring Reducers - Prerequisite Concepts](../recipes/structuring-reducers/PrerequisiteConcepts.md) -- [Recipes: Structuring Reducers - Immutable Update Patterns](../recipes/structuring-reducers/ImmutableUpdatePatterns.md) +- [Using Redux: Structuring Reducers - Prerequisite Concepts](../usage/structuring-reducers/PrerequisiteConcepts.md) +- [Using Redux: Structuring Reducers - Immutable Update Patterns](../usage/structuring-reducers/ImmutableUpdatePatterns.md) **Discussions** @@ -183,7 +183,7 @@ First, only cache as much data as the user needs. If your application displays a Second, cache an abbreviated form of a record when possible. Sometimes a record includes data that is not relevant to the user. If the application does not depend on this data, it can be omitted from the cache. -Third, only cache a single copy of a record. This is especially important when records contain copies of other records. Cache a unique copy for each record and replace each nested copy with a reference. This is called normalization. Normalization is the preferred approach to storing relational data for [several reasons](../recipes/structuring-reducers/NormalizingStateShape.md#designing-a-normalized-state), including efficient memory consumption. +Third, only cache a single copy of a record. This is especially important when records contain copies of other records. Cache a unique copy for each record and replace each nested copy with a reference. This is called normalization. Normalization is the preferred approach to storing relational data for [several reasons](../usage/structuring-reducers/NormalizingStateShape.md#designing-a-normalized-state), including efficient memory consumption. #### Further information diff --git a/docs/faq/ReactRedux.md b/docs/faq/ReactRedux.md index 2eef37e9a0..d01ca9be0d 100644 --- a/docs/faq/ReactRedux.md +++ b/docs/faq/ReactRedux.md @@ -64,11 +64,10 @@ Note that “updating data immutably” does _not_ mean that you must use [Immer **Documentation** -- [Troubleshooting](../recipes/Troubleshooting.md) +- [Troubleshooting](../usage/Troubleshooting.md) - [React Redux: Troubleshooting](https://react-redux.js.org/troubleshooting) -- [Recipes: Using the Object Spread Operator](../recipes/UsingObjectSpreadOperator.md) -- [Recipes: Structuring Reducers - Prerequisite Concepts](../recipes/structuring-reducers/PrerequisiteConcepts.md) -- [Recipes: Structuring Reducers - Immutable Update Patterns](../recipes/structuring-reducers/ImmutableUpdatePatterns.md) +- [Using Redux: Structuring Reducers - Prerequisite Concepts](../usage/structuring-reducers/PrerequisiteConcepts.md) +- [Using Redux: Structuring Reducers - Immutable Update Patterns](../usage/structuring-reducers/ImmutableUpdatePatterns.md) **Articles** @@ -131,7 +130,7 @@ While React Redux does work to minimize the number of times that your `mapStateT **Documentation** -- [Recipes: Computed Derived Data](../recipes/ComputingDerivedData.md) +- [Using Redux: Computed Derived Data](../usage/ComputingDerivedData.md) **Articles** diff --git a/docs/faq/Reducers.md b/docs/faq/Reducers.md index 82f72edd0f..bbac5f622f 100644 --- a/docs/faq/Reducers.md +++ b/docs/faq/Reducers.md @@ -35,7 +35,7 @@ In general, remember that reducers are just functions—you can organize them an **Documentation** - [API: combineReducers](../api/combineReducers.md) -- [Recipes: Structuring Reducers](../recipes/structuring-reducers/StructuringReducers.md) +- [Using Redux: Structuring Reducers](../usage/structuring-reducers/StructuringReducers.md) **Discussions** @@ -53,8 +53,8 @@ No. You are welcome to use any approach you'd like to respond to an action in a **Documentation** -- [Recipes: Reducing Boilerplate](../recipes/ReducingBoilerplate.md) -- [Recipes: Structuring Reducers - Splitting Reducer Logic](../recipes/structuring-reducers/SplittingReducerLogic.md) +- [Using Redux: Reducing Boilerplate](../usage/ReducingBoilerplate.md) +- [Using Redux: Structuring Reducers - Splitting Reducer Logic](../usage/structuring-reducers/SplittingReducerLogic.md) **Discussions** diff --git a/docs/introduction/Examples.md b/docs/introduction/Examples.md index 1b07857c16..c3ee19ddf2 100644 --- a/docs/introduction/Examples.md +++ b/docs/introduction/Examples.md @@ -171,7 +171,7 @@ npm install npm start ``` -This is a basic demonstration of [server rendering](../recipes/ServerRendering.md) with Redux and React. It shows how to prepare the initial store state on the server, and pass it down to the client so the client store can boot up from an existing state. +This is a basic demonstration of [server rendering](../usage/ServerRendering.md) with Redux and React. It shows how to prepare the initial store state on the server, and pass it down to the client so the client store can boot up from an existing state. ## Real World diff --git a/docs/introduction/GettingStarted.md b/docs/introduction/GettingStarted.md index f408ecdcb5..3bfbec40e3 100644 --- a/docs/introduction/GettingStarted.md +++ b/docs/introduction/GettingStarted.md @@ -7,8 +7,6 @@ description: 'Introduction > Getting Started: Resources to get started learning import LiteYouTubeEmbed from 'react-lite-youtube-embed'; import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css' -# Getting Started with Redux - Redux is a predictable state container for JavaScript apps. It helps you write applications that behave consistently, run in different environments (client, server, and native), and are easy to test. On top of that, it provides a great developer experience, such as [live code editing combined with a time traveling debugger](https://github.com/reduxjs/redux-devtools). @@ -203,7 +201,7 @@ See [the "Learn Modern Redux" show notes page](https://www.learnwithjason.dev/le ### Other Resources -- The **[Redux FAQ](../FAQ.md)** answers many common questions about how to use Redux, and the **["Recipes" docs section](../recipes/README.md)** has information on handling derived data, testing, structuring reducer logic, and reducing boilerplate. +- The **[Redux FAQ](../FAQ.md)** answers many common questions about how to use Redux, and the **["Using Redux" docs section](../usage/index.md)** has information on handling derived data, testing, structuring reducer logic, and reducing boilerplate. - Redux maintainer Mark Erikson's **["Practical Redux" tutorial series](https://blog.isquaredsoftware.com/series/practical-redux/)** demonstrates real-world intermediate and advanced techniques for working with React and Redux (also available as **[an interactive course on Educative.io](https://www.educative.io/collection/5687753853370368/5707702298738688)**). - The **[React/Redux links list](https://github.com/markerikson/react-redux-links)** has categorized articles on working with [reducers and selectors](https://github.com/markerikson/react-redux-links/blob/master/redux-reducers-selectors.md), [managing side effects](https://github.com/markerikson/react-redux-links/blob/master/redux-side-effects.md), [Redux architecture and best practices](https://github.com/markerikson/react-redux-links/blob/master/redux-architecture.md), and more. - Our community has created thousands of Redux-related libraries, addons, and tools. The **["Ecosystem" docs page](./Ecosystem.md)** lists our recommendations, and there's a complete listing available in the **[Redux addons catalog](https://github.com/markerikson/redux-ecosystem-links)**. diff --git a/docs/style-guide/style-guide.md b/docs/style-guide/style-guide.md index 3368865467..0639291634 100644 --- a/docs/style-guide/style-guide.md +++ b/docs/style-guide/style-guide.md @@ -173,7 +173,7 @@ case "todos/toggleTodo": However, doing the logic in the reducer is preferable for several reasons: - Reducers are always easy to test, because they are pure functions - you just call `const result = reducer(testState, action)`, and assert that the result is what you expected. So, the more logic you can put in a reducer, the more logic you have that is easily testable. -- Redux state updates must always follow [the rules of immutable updates](../recipes/structuring-reducers/ImmutableUpdatePatterns.md). Most Redux users realize they have to follow the rules inside a reducer, but it's not obvious that you _also_ have to do this if the new state is calculated _outside_ the reducer. This can easily lead to mistakes like accidental mutations, or even reading a value from the Redux store and passing it right back inside an action. Doing all of the state calculations in a reducer avoids those mistakes. +- Redux state updates must always follow [the rules of immutable updates](../usage/structuring-reducers/ImmutableUpdatePatterns.md). Most Redux users realize they have to follow the rules inside a reducer, but it's not obvious that you _also_ have to do this if the new state is calculated _outside_ the reducer. This can easily lead to mistakes like accidental mutations, or even reading a value from the Redux store and passing it right back inside an action. Doing all of the state calculations in a reducer avoids those mistakes. - If you are using Redux Toolkit or Immer, it is much easier to write immutable update logic in reducers, and Immer will freeze the state and catch accidental mutations. - Time-travel debugging works by letting you "undo" a dispatched action, then either do something different or "redo" the action. In addition, hot-reloading of reducers normally involves re-running the new reducer with the existing actions. If you have a correct action but a buggy reducer, you can edit the reducer to fix the bug, hot-reload it, and you should get the correct state right away. If the action itself was wrong, you'd have to re-run the steps that led to that action being dispatched. So, it's easier to debug if more logic is in the reducer. - Finally, putting logic in reducers means you know where to look for the update logic, instead of having it scattered in random other parts of the application code. @@ -362,7 +362,7 @@ Now, since you're defining behavior per state instead of per action, you also pr Many applications need to cache complex data in the store. That data is often received in a nested form from an API, or has relations between different entities in the data (such as a blog that contains Users, Posts, and Comments). -**Prefer storing that data in [a "normalized" form](../recipes/structuring-reducers/NormalizingStateShape.md) in the store**. This makes it easier to look up items based on their ID and update a single item in the store, and ultimately leads to better performance patterns. +**Prefer storing that data in [a "normalized" form](../usage/structuring-reducers/NormalizingStateShape.md) in the store**. This makes it easier to look up items based on their ID and update a single item in the store, and ultimately leads to better performance patterns. ### Model Actions as Events, Not Setters diff --git a/docs/tutorials/essentials/part-2-app-structure.md b/docs/tutorials/essentials/part-2-app-structure.md index c7dbaa603b..cf42def430 100644 --- a/docs/tutorials/essentials/part-2-app-structure.md +++ b/docs/tutorials/essentials/part-2-app-structure.md @@ -413,7 +413,7 @@ On the other hand, the `incrementByAmount` reducer _does_ need to know something :::info Want to Know More? -For more information on immutability and writing immutable updates, see [the "Immutable Update Patterns" docs page](../../recipes/structuring-reducers/ImmutableUpdatePatterns.md) and [The Complete Guide to Immutability in React and Redux](https://daveceddia.com/react-redux-immutability-guide/). +For more information on immutability and writing immutable updates, see [the "Immutable Update Patterns" docs page](../../usage/structuring-reducers/ImmutableUpdatePatterns.md) and [The Complete Guide to Immutability in React and Redux](https://daveceddia.com/react-redux-immutability-guide/). ::: diff --git a/docs/tutorials/essentials/part-6-performance-normalization.md b/docs/tutorials/essentials/part-6-performance-normalization.md index 7d5cda5cc9..99ac1cdee8 100644 --- a/docs/tutorials/essentials/part-6-performance-normalization.md +++ b/docs/tutorials/essentials/part-6-performance-normalization.md @@ -676,7 +676,7 @@ const userObject = state.users.entities[userId] :::info -For more details on why normalizing state is useful, see [Normalizing State Shape](../../recipes/structuring-reducers/NormalizingStateShape.md) and the Redux Toolkit Usage Guide section on [Managing Normalized Data](https://redux-toolkit.js.org/usage/usage-guide#managing-normalized-data). +For more details on why normalizing state is useful, see [Normalizing State Shape](../../usage/structuring-reducers/NormalizingStateShape.md) and the Redux Toolkit Usage Guide section on [Managing Normalized Data](https://redux-toolkit.js.org/usage/usage-guide#managing-normalized-data). ::: @@ -1004,7 +1004,7 @@ The concepts we've covered in this tutorial should be enough to get you started The Redux Essentials tutorial focused on "how to use Redux correctly", rather than "how it works" or "why it works this way". In particular, Redux Toolkit is a higher-level set of abstractions and utilities, and it's helpful to understand what the abstractions in RTK are actually doing for you. Reading through the ["Redux Fundamentals" tutorial](../fundamentals/part-1-overview.md) will help you understand how to write Redux code "by hand", and why we recommend Redux Toolkit as the default way to write Redux logic. -The [Recipes](../../recipes/README.md) section has information on a number of important concepts, like [how to structure your reducers](../../recipes/structuring-reducers/StructuringReducers.md), and [our Style Guide page](../../style-guide/style-guide) has important information on our recommended patterns and best practices. +The [Using Redux](../../usage/index.md) section has information on a number of important concepts, like [how to structure your reducers](../../usage/structuring-reducers/StructuringReducers.md), and [our Style Guide page](../../style-guide/style-guide) has important information on our recommended patterns and best practices. If you'd like to know more about _why_ Redux exists, what problems it tries to solve, and how it's meant to be used, see Redux maintainer Mark Erikson's posts on [The Tao of Redux, Part 1: Implementation and Intent](https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-1/) and [The Tao of Redux, Part 2: Practice and Philosophy](https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/). diff --git a/docs/tutorials/fundamentals/part-7-standard-patterns.md b/docs/tutorials/fundamentals/part-7-standard-patterns.md index 9f89caf9fe..3a70972121 100644 --- a/docs/tutorials/fundamentals/part-7-standard-patterns.md +++ b/docs/tutorials/fundamentals/part-7-standard-patterns.md @@ -864,7 +864,7 @@ For now, the important things to understand are: For more details on why normalization is useful with Redux, see: -- [Structuring Reducers: Normalizing State Shape](../../recipes/structuring-reducers/NormalizingStateShape.md) +- [Structuring Reducers: Normalizing State Shape](../../usage/structuring-reducers/NormalizingStateShape.md) ::: diff --git a/docs/tutorials/fundamentals/part-8-modern-redux.md b/docs/tutorials/fundamentals/part-8-modern-redux.md index ae8b680d37..8150e63aba 100644 --- a/docs/tutorials/fundamentals/part-8-modern-redux.md +++ b/docs/tutorials/fundamentals/part-8-modern-redux.md @@ -868,7 +868,7 @@ However, our [**"Redux Essentials" tutorial**](../essentials/part-1-overview-con At the same time, the concepts we've covered in this tutorial should be enough to get you started building your own applications using React and Redux. Now's a great time to try working on a project yourself to solidify these concepts and see how they work in practice. If you're not sure what kind of a project to build, see [this list of app project ideas](https://github.com/florinpop17/app-ideas) for some inspiration. -The [Recipes](../../recipes/README.md) section has information on a number of important concepts, like [how to structure your reducers](../../recipes/structuring-reducers/StructuringReducers.md), and [**our Style Guide page**](../../style-guide/style-guide) has important information on our recommended patterns and best practices. +The [Using Redux](../../usage/index.md) section has information on a number of important concepts, like [how to structure your reducers](../../usage/structuring-reducers/StructuringReducers.md), and [**our Style Guide page**](../../style-guide/style-guide) has important information on our recommended patterns and best practices. If you'd like to know more about _why_ Redux exists, what problems it tries to solve, and how it's meant to be used, see Redux maintainer Mark Erikson's posts on [The Tao of Redux, Part 1: Implementation and Intent](https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-1/) and [The Tao of Redux, Part 2: Practice and Philosophy](https://blog.isquaredsoftware.com/2017/05/idiomatic-redux-tao-of-redux-part-2/). diff --git a/docs/tutorials/typescript.md b/docs/tutorials/typescript.md index 62f8168b10..0465ac4eb6 100644 --- a/docs/tutorials/typescript.md +++ b/docs/tutorials/typescript.md @@ -172,4 +172,4 @@ export function Counter() { ## What's Next? -See [the "Usage with TypeScript" page](../recipes/UsageWithTypescript.md) for extended details on how to use Redux Toolkit's APIs with TypeScript. +See [the "Usage with TypeScript" page](../usage/UsageWithTypescript.md) for extended details on how to use Redux Toolkit's APIs with TypeScript. diff --git a/docs/understanding/history-and-design/PriorArt.md b/docs/understanding/history-and-design/PriorArt.md index ae48e9786f..c02f04f85a 100644 --- a/docs/understanding/history-and-design/PriorArt.md +++ b/docs/understanding/history-and-design/PriorArt.md @@ -14,7 +14,7 @@ Redux was inspired by several important qualities of [Flux](https://facebook.git Unlike Flux, **Redux does not have the concept of a Dispatcher**. This is because it relies on pure functions instead of event emitters, and pure functions are easy to compose and don't need an additional entity managing them. Depending on how you view Flux, you may see this as either a deviation or an implementation detail. Flux has often been [described as `(state, action) => state`](https://speakerdeck.com/jmorrell/jsconf-uy-flux-those-who-forget-the-past-dot-dot-dot-1). In this sense, Redux is true to the Flux architecture, but makes it simpler thanks to pure functions. -Another important difference from Flux is that **Redux assumes you never mutate your data**. You can use plain objects and arrays for your state just fine, but mutating them inside the reducers is strongly discouraged. You should always return a new object, which can be done using the [object spread operator](../../recipes/UsingObjectSpreadOperator.md) or [the Immer immutable update library](https://immerjs.github.io/immer/). +Another important difference from Flux is that **Redux assumes you never mutate your data**. You can use plain objects and arrays for your state just fine, but mutating them inside the reducers is strongly discouraged. You should always return a new object, which can be done using the object spread operator or [the Immer immutable update library](https://immerjs.github.io/immer/). While it is technically _possible_ to [write impure reducers](https://github.com/reduxjs/redux/issues/328#issuecomment-125035516) that mutate the data for performance corner cases, we actively discourage you from doing this. Development features like time travel, record/replay, or hot reloading will break. Moreover it doesn't seem like immutability poses performance problems in most real apps, because, as [Om](https://github.com/omcljs/om) demonstrates, even if you lose out on object allocation, you still win by avoiding expensive re-renders and re-calculations, as you know exactly what changed thanks to reducer purity. diff --git a/docs/usage/ServerRendering.md b/docs/usage/ServerRendering.md index 9de5b6f8eb..b35af14faa 100644 --- a/docs/usage/ServerRendering.md +++ b/docs/usage/ServerRendering.md @@ -124,7 +124,7 @@ function renderFullPage(html, preloadedState) {
${html}