Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revamp "Redux Essentials" tutorial to be TS-first and update contents #4706

Merged
merged 42 commits into from
Aug 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
67e60e6
Export AppDispatch type in TS page
markerikson May 12, 2024
3bad830
Expand setup instructions with TS details
markerikson May 12, 2024
a1a74c2
Add store setup instructions
markerikson May 12, 2024
1b38f38
Show h4 headings in TOCs
markerikson May 12, 2024
28b1859
Update existing Part 3 content with TS info
markerikson May 12, 2024
a792bec
Update post editing and payload creators
markerikson May 15, 2024
226526c
Update author handling
markerikson May 17, 2024
36dfbeb
Update reaction buttons
markerikson May 17, 2024
8aa8994
Add auth and `extraReducers` section
markerikson Jun 4, 2024
f925670
Fix assorted typos
markerikson Jun 9, 2024
72ed3d4
Flesh out thunk explanations
markerikson Jun 9, 2024
8bd4f9b
Add selectors section
markerikson Jun 9, 2024
532166b
Cover thunk dispatches and thunks in slices
markerikson Jun 12, 2024
1ba6132
Update existing Part 6 content
markerikson Jun 16, 2024
92acadc
Mention "pure" and "side effects"
markerikson Jun 16, 2024
db1c510
Add listener middleware section
markerikson Jun 16, 2024
883ee54
Fill out Part 7
markerikson Jun 19, 2024
b4737f5
Revamp most of Part 8
markerikson Jun 23, 2024
c0cb825
Add `AppThunk` description
markerikson Jun 29, 2024
1650a33
Finish revamping Part 8
markerikson Jun 29, 2024
1e0e65e
Replace "AJAX" with "HTTP"
markerikson Jun 30, 2024
8f9261a
Tweak tutorial intro pages
markerikson Jun 30, 2024
ac3a0a2
Add brief links to Replay for debugging
markerikson Jun 30, 2024
cec44b9
Revamp Part 2
markerikson Jul 7, 2024
696c01d
Revamp parts 3, 4, and half of 5 based on review feedback
markerikson Jul 20, 2024
7b21b84
Stop using backticks with Promise
markerikson Jul 27, 2024
b11ffca
Finish part 5
markerikson Jul 27, 2024
fed5edd
Update Part 6
markerikson Jul 27, 2024
13ccf68
Remove Replay mentions
markerikson Jul 28, 2024
e1ece05
Update Part 7
markerikson Jul 28, 2024
0adf680
Update createRoot examples
markerikson Jul 28, 2024
ede759c
Update most of Part 8
markerikson Jul 28, 2024
b16f3a2
Rewrite "Optimist/Streaming Updates" sections
markerikson Jul 29, 2024
a3358f3
Update Part 2 sandbox and images
markerikson Jul 30, 2024
c2f0389
Part 1-2 edits
markerikson Jul 30, 2024
6ad07fe
Part 3 sandbox and images
markerikson Jul 30, 2024
90b3352
Screenshots and sandboxes for Parts 4 and 5
markerikson Jul 31, 2024
945f98a
Add missing code snippets for Part 8
markerikson Jul 31, 2024
e4864ca
Part 6 screenshots and sandbox
markerikson Jul 31, 2024
2d1a07c
Part 7 screenshots and sandbox
markerikson Jul 31, 2024
dd8d6ff
Part 8 screenshots
markerikson Jul 31, 2024
41e746b
Final sandbox updates
markerikson Aug 1, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions docs/tutorials/essentials/part-1-overview-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,28 +19,29 @@ import { DetailedExplanation } from '../../components/DetailedExplanation'

Welcome to the Redux Essentials tutorial! **This tutorial will introduce you to Redux and teach you how to use it the right way, using our latest recommended tools and best practices**. By the time you finish, you should be able to start building your own Redux applications using the tools and patterns you've learned here.

In Part 1 of this tutorial, we'll cover the key concepts and terms you need to know to use Redux, and in [Part 2: Redux App Structure](./part-2-app-structure.md) we'll examine a basic React + Redux app to see how the pieces fit together.
In Part 1 of this tutorial, we'll cover the key concepts and terms you need to know to use Redux, and in [Part 2: Redux App Structure](./part-2-app-structure.md) we'll examine a typical React + Redux app to see how the pieces fit together.

Starting in [Part 3: Basic Redux Data Flow](./part-3-data-flow.md), we'll use that knowledge to build a small social media feed app with some real-world features, see how those pieces actually work in practice, and talk about some important patterns and guidelines for using Redux.

### How to Read This Tutorial

This page will focus on showing you _how_ to use Redux the right way, and explain just enough of the concepts so that you can understand how to build Redux apps correctly.
This tutorial focuses on showing you _how_ to use Redux the right way, and explains concepts along the way so that you can understand how to build Redux apps correctly.

We've tried to keep these explanations beginner-friendly, but we do need to make some assumptions about what you know already:

:::important Prerequisites

- Familiarity with [HTML & CSS](https://internetingishard.netlify.app/html-and-css/index.html).
- Familiarity with [ES2015 syntax and features](https://www.taniarascia.com/es6-syntax-and-feature-overview/)
- Knowledge of React terminology: [JSX](https://react.dev/learn/writing-markup-with-jsx), [State](https://react.dev/learn/state-a-components-memory), [Function Components](https://react.dev/learn/your-first-component), [Props](https://react.dev/learn/passing-props-to-a-component), and [Hooks](https://react.dev/reference/react)
- Knowledge of [asynchronous JavaScript](https://javascript.info/promise-basics) and [making AJAX requests](https://javascript.info/fetch)
- Knowledge of React terminology: [JSX](https://react.dev/learn/writing-markup-with-jsx), [Function Components](https://react.dev/learn/your-first-component), [Props](https://react.dev/learn/passing-props-to-a-component), [State](https://react.dev/learn/state-a-components-memory), and [Hooks](https://react.dev/reference/react)
- Knowledge of [asynchronous JavaScript](https://javascript.info/promise-basics) and [making HTTP requests](https://javascript.info/fetch)
- Basic understanding of [TypeScript syntax and usage](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)

:::

**If you're not already comfortable with those topics, we encourage you to take some time to become comfortable with them first, and then come back to learn about Redux**. We'll be here when you're ready!

You should make sure that you have the React and Redux DevTools extensions installed in your browser:
You should also make sure that you have the React and Redux DevTools extensions installed in your browser:

- React DevTools Extension:
- [React DevTools Extension for Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
Expand All @@ -53,7 +54,7 @@ You should make sure that you have the React and Redux DevTools extensions insta

It helps to understand what this "Redux" thing is in the first place. What does it do? What problems does it help me solve? Why would I want to use it?

**Redux is a pattern and library for managing and updating application state, using events called "actions".** It serves as a centralized store for state that needs to be used across your entire application, with rules ensuring that the state can only be updated in a predictable fashion.
**Redux is a pattern and library for managing and updating global application state, where the UI triggers events called "actions" to describe what happened, and separate update logic called "reducers" updates the state in response.** It serves as a centralized store for state that needs to be used across your entire application, with rules ensuring that the state can only be updated in a predictable fashion.

### Why Should I Use Redux?

Expand Down Expand Up @@ -87,16 +88,16 @@ If you're not sure whether Redux is a good choice for your app, these resources

### Redux Libraries and Tools

Redux is a small standalone JS library. However, it is commonly used with several other packages:

#### React-Redux

Redux can integrate with any UI framework, and is most frequently used with React. [**React-Redux**](https://react-redux.js.org/) is our official package that lets your React components interact with a Redux store by reading pieces of state and dispatching actions to update the store.
Redux at its core is a small standalone JS library. It is commonly used with several other packages:

#### Redux Toolkit

[**Redux Toolkit**](https://redux-toolkit.js.org) is our recommended approach for writing Redux logic. It contains packages and functions that we think are essential for building a Redux app. Redux Toolkit builds in our suggested best practices, simplifies most Redux tasks, prevents common mistakes, and makes it easier to write Redux applications.

#### React-Redux

Redux can integrate with any UI framework, and is most frequently used with React. [**React-Redux**](https://react-redux.js.org/) is our official package that lets your React components interact with a Redux store by reading pieces of state and dispatching actions to update the store.

#### Redux DevTools Extension

The [**Redux DevTools Extension**](https://github.com/reduxjs/redux-devtools/tree/main/extension) shows a history of the changes to the state in your Redux store over time. This allows you to debug your applications effectively, including using powerful techniques like "time-travel debugging".
Expand Down Expand Up @@ -205,7 +206,7 @@ const arr3 = arr.slice()
arr3.push('c')
```

**Redux expects that all state updates are done immutably**. We'll look at where and how this is important a bit later, as well as some easier ways to write immutable update logic.
**React and Redux expect that all state updates are done immutably**. We'll look at where and how this is important a bit later, as well as some easier ways to write immutable update logic.

:::info Want to Know More?

Expand Down Expand Up @@ -264,7 +265,7 @@ Reducers must _always_ follow some specific rules:

- They should only calculate the new state value based on the `state` and `action` arguments
- They are not allowed to modify the existing `state`. Instead, they must make _immutable updates_, by copying the existing `state` and making changes to the copied values.
- They must not do any asynchronous logic, calculate random values, or cause other "side effects"
- They must be "pure" - they cannot do any asynchronous logic, calculate random values, or cause other "side effects"

We'll talk more about the rules of reducers later, including why they're important and how to follow them correctly.

Expand Down Expand Up @@ -442,18 +443,18 @@ Redux does have a number of new terms and concepts to remember. As a reminder, h

- **Redux is a library for managing global application state**
- Redux is typically used with the React-Redux library for integrating Redux and React together
- Redux Toolkit is the recommended way to write Redux logic
- Redux Toolkit is the standard way to write Redux logic
- **Redux's update pattern separates "what happened" from "how the state changes"**
- _Actions_ are plain objects with a `type` field, and describe "what happened" in the app
- _Reducers_ are functions that calculate a new state value based on previous state + an action
- A Redux _store_ runs the root reducer whenever an action is _dispatched_
- **Redux uses a "one-way data flow" app structure**
- State describes the condition of the app at a point in time, and UI renders based on that state
- When something happens in the app:
- The UI dispatches an action
- The store runs the reducers, and the state is updated based on what occurred
- The store notifies the UI that the state has changed
- The UI re-renders based on the new state
- **Redux uses several types of code**
- _Actions_ are plain objects with a `type` field, and describe "what happened" in the app
- _Reducers_ are functions that calculate a new state value based on previous state + an action
- A Redux _store_ runs the root reducer whenever an action is _dispatched_

:::

Expand Down
Loading