[Docs Rewrite] Create the "Quick Start" page #3675

markerikson · 2020-01-07T05:11:42Z

PR Type

Does this PR add a new page, or update an existing page?

Adds the new "Quick Start" page

Checklist

Is there an existing issue for this PR?
- [Docs Rewrite] Create "Quick Start" page #3674
Have the files been linted and formatted?

What docs page is being added or updated?

Section: Introduction
Page: Quick Start

For Adding New Content

What kind of content category is this page (tutorial, how-to, explanation, reference)?

The "Quick Start" page is a form of tutorial, but intended to demonstrate the "fastest" / "easiest" / "correct" way to use Redux without explaining why things work this way.

Who is the intended target audience?

Beginners who know nothing about Redux, yet.

What knowledge are we assuming they have?

JS syntax: ES6, async/await, object spreads
React: components, hooks
Other: HTTP / AJAX, fetch

What are the intended results or takeaways from reading this page?

Readers should be able to mimic the demonstrated patterns to create a basic React+Redux app that does some CRUD work.

What is the most critical info they should learn?

Redux is a tool for managing state outside of your React components
The Redux Toolkit package is the simplest and recommended way to use Redux
Key React+Redux APIs (configureStore, createSlice, useSelector / useDispatch)
Immutability is vital, but either requires hand-written updates or use of RTK+Immer "magic"

Status

Hacked together this initial skeleton of a page. So far I've done:

Figured out how to use MDX with Docusaurus
Added reusable components for <Note> (including multiple styles based on the Cypress.io docs) and <DetailedExplanation>
Created an empty "Quick Start" page
Added some initial "what is this and why would I use it?" content
Added instructions on creating a project

I got stuck with some yak shaving when I realized that using the diff highlighting format leaves the +- diff signs as copyable characters, and ideally I'd like them not copied or selectable. I tried playing with user-select: none and the :first-letter selector, but it's not quite doing what I want.

Putting this up for ongoing feedback as we work through this.

/cc @taniarascia , @bpas247

netlify · 2020-01-07T05:13:48Z

Deploy preview for redux-docs ready!

Built with commit 6428359

https://deploy-preview-3675--redux-docs.netlify.com

nickserv

Looks good overall! Think this'll really help, and I'll try to review again as progress is made

nickserv · 2020-01-07T05:28:50Z

docs/introduction/QuickStart.mdx

+
+**TODO** figure out what else to put here, or if this should be dropped
+
+</Note>


Personally I don't think this section is needed in a quick start, since it's specifically for getting something quickly rather than overviewing the whole API, which I think the rest of the docs introduce well enough

docs/introduction/QuickStart.mdx

+```diff
+import React from "react";
+import ReactDOM from "react-dom";
+import {configureStore} from "@reduxjs/toolkit";


markerikson · 2020-01-07T15:53:01Z

docs/introduction/QuickStart.mdx

+
+const rootElement = document.getElementById("root");
+ReactDOM.render(<App />, rootElement);
+```


My intent is to have the first step simply be () => "Hello Redux" + const helloText = useSelector(state => state), and get that to show up on screen instead of the initial text in <App>. That gives them some immediate success in seeing something visible change on the page. Then, once they've seen the initial connection sequence, we can move on to filling out actual app logic.

Co-Authored-By: Nick McCurdy <nick@nickmccurdy.com>

into docs/quick-start-page

markerikson · 2020-01-08T03:22:57Z

Finished the "Setup and Installation" part of the page.

I'm feeling very split on the content so far. I think what I've got here is decent, but at the same time I'm worried it's too low-level / introductory, and taking too long to get to anything "useful" and "real".

bpas247

Looking great so far 😄

bpas247 · 2020-01-08T21:20:53Z

docs/introduction/QuickStart.mdx

+- Basic familiarity with HTML & CSS, and the DOM.
+- Basic knowledge of JavaScript and programming.
+- Familiarity with ES6 syntax and features.
+- Basic knowledge of React, including components, props, and state.
+- Node.js and `npm` installed globally.


should we link to external resources here? In case the end user doesn't know these pre-reqs.

Yep, I'm just trying to get a list in place for now.

bpas247 · 2020-01-08T21:28:29Z

docs/introduction/QuickStart.mdx

+It's _possible_ that we could move the store into a separate file, import that store into the `App.js` file, and call `store.getState()`. But, as the
+app gets bigger, we'd have to import the store into _every_ file. That's not a good idea.


I'm not sure how useful this information is to a beginner? Just comes off as more information than needed IMO

Mmm... yes and no. My thought was to justify why React-Redux's API is needed at all.

I guess I'm just worried about this "Quick Start" page having more content than it needs, since in my mind the goal of this page is to provide as minimal information as possibly needed to get started with Redux + React.

If you feel like this content fits that goal then we should definitely keep it 😃

I've seen a lot of beginners try to use vanilla Redux in React apps and they get very confused with how to handle the store. I agree with Mark here that it's important for us to explain why React Redux is helpful right away.

Of course, if we have a guide for non-React users in the future, this wouldn't be necessary.

If this stays, it'd be good to explain why "That's not a good idea." - it will get messy? hard to manage? but there's an easier way?

bpas247 · 2020-01-08T21:30:52Z

docs/introduction/QuickStart.mdx

+The last step for the initial setup is to update our `<App>` component to read the state value from the Redux store.
+
+We've already seen that the React-Redux `<Provider>` component makes the store available to any components inside. To go along with that, React-Redux
+includes a React hook called `useSelector`, which React function components can call to retrieve the state values from the store.


We should link to the React hooks API docs here. Might also be worth mentioning that React hooks is a pre-req for this page, since the end user could be new to the React hooks API as well.

bpas247 · 2020-01-08T21:36:47Z

website/sidebars.js

@@ -2,6 +2,7 @@ module.exports = {
  docs: {
    Introduction: [
      'introduction/getting-started',
+      'introduction/quick-start',


The placement of this page is a bit awkward. Are we assuming that the end users are going to directly navigate to the "Quick Start" page rather than reading the "Getting Started" page first? Since both of these pages start out with the same information, and have a lot of duplicate information.

Also a bit strange that we go over installation in this page, but then the next page the user might navigate to is the "Installation" page.

Yeah, agree that there's overlap, and that needs to be sorted out. For now, my focus is on the actual content of this page.

bpas247 · 2020-01-10T02:39:23Z

website/package.json

+    "@docusaurus/core": "2.0.0-alpha.40",
+    "@docusaurus/preset-classic": "2.0.0-alpha.40",


Outta curiosity, is there a specific reason that these are getting version bumps in this PR? Might be better to branch out these version bumps to a separate PR.

DylanVann · 2020-01-19T02:46:01Z

I think you should get the users to have some simple working code and get them interested/excited about it before going into a bunch of explanations and prerequisites and stuff.

1. Create a Create React App app:

npx create-react-app redux-counter-example

2. Install `@reduxjs/toolkit-react`

yarn add @reduxjs/toolkit-react

3. Paste this example into `index.js`

import React from "react"
import { render } from "react-dom"
import {
  Provider
  useSelector,
  useDispatch,
  createAction as createEvent,
  configureStore as createStore,
  createReducer,
} from "@reduxjs/toolkit-react"

const onIncrementClicked = createEvent("incrementClicked")
const onDecrementClicked = createEvent("decrementClicked")

const counterReducer = createReducer(0, builder =>
  builder
    .addCase(onIncrementClicked, state => state + 1)
    .addCase(onDecrementClicked, state => state - 1),
)

const store = createStore({
  reducer: {
    counter: counterReducer,
  },
})

function App() {
  const count = useSelector(state => state.counter)
  const dispatch = useDispatch()
  return (
    <div>
      <button onClick={() => dispatch(onDecrementClicked())}>-</button>
      {count}
      <button onClick={() => dispatch(onIncrementClicked())}>+</button>
    </div>
  )
}

render(
  <Provider store={store}>
    <App />
  </Provider>,
  document.getElementById("root"),
)

Open the Redux DevTools and try (there should be some gifs showing how to do this stuff):

Clicking the buttons to see events.
Viewing the state changes that happen on the events.
Using time travel debugging to see earlier states of the app.

Basically I think "Quick Start" should be small and quick. It would be fine to have lots of links at the end. Or just a link at the end going to a more in depth tutorial after people are excited about having something working.

The idea of @reduxjs/toolkit-react would be to make it so people only have to install one package. It would just look like:

export * from 'redux'
export * from 'react-redux'
export * from '@reduxjs/toolkit'

It would be nice to have a toggle somewhere on the page to change the code to TypeScript and change the CRA command to use the TS template.

taniarascia · 2020-01-19T23:36:39Z

@DylanVann In general, I agree - less is more. However, instead of "paste the all this code into index.js", I think it would be better to break it into chunks.

We'll be creating a simple counter application. First, makeindex.js file and import all dependencies.

import React from "react"
import { render } from "react-dom"
import {
  Provider
  useSelector,
  useDispatch,
  createAction as createEvent,
  configureStore as createStore,
  createReducer,
} from "@reduxjs/toolkit-react"

Next, create two events - one for incrementing, one for decrementing.

const onIncrementClicked = createEvent("incrementClicked")
const onDecrementClicked = createEvent("decrementClicked")

Then we'll create a reducer.

const counterReducer = createReducer(0, builder =>
  builder
    .addCase(onIncrementClicked, state => state + 1)
    .addCase(onDecrementClicked, state => state - 1),
)

...etc.

Then at the very end, have the full index.js file for them to compare with if they went wrong anywhere.

nickserv · 2020-01-20T00:07:52Z

docs/introduction/QuickStart.mdx

+
+#### Key Concept: "Reducers"
+
+A **_reducer_** is a function that know how to calculate a new state value when asked. A Redux store requires a single reducer function


Suggested change

A **_reducer_** is a function that know how to calculate a new state value when asked. A Redux store requires a single reducer function

A **_reducer_** is a function that knows how to calculate a new state value when asked. A Redux store requires a single reducer function

"A reducer is a function that calculates a new state value."

nickserv · 2020-01-20T00:09:16Z

docs/introduction/QuickStart.mdx

+
+- Reducers must always return a state value, never `undefined`
+- Reducers can only decide what the next state value should be by looking at the `state` and `action` arguments
+- Reducers are not allowed to make changes to the `state` argument, or anything else. They can only create the new state value by making copies of the originals, and updating the copies.


This might be confusing to Redux Toolkit users (and we recommend it to beginners), as mutations are supported via Immer and are recommended in the docs.

Yeah this is a good point. Later on, it would be good to show "here's the hard way (ignoring that immer is installed)" and "here's the easy way because of immer".

Yep, this is still my number one concern with trying to explain use of RTK in general, and especially in this page.

nickserv · 2020-01-20T00:12:43Z

docs/introduction/QuickStart.mdx

+It's _possible_ that we could move the store into a separate file, import that store into the `App.js` file, and call `store.getState()`. But, as the
+app gets bigger, we'd have to import the store into _every_ file. That's not a good idea.


I've seen a lot of beginners try to use vanilla Redux in React apps and they get very confused with how to handle the store. I agree with Mark here that it's important for us to explain why React Redux is helpful right away.

Of course, if we have a guide for non-React users in the future, this wouldn't be necessary.

nickserv · 2020-01-20T00:16:05Z

docs/introduction/QuickStart.mdx

+```
+
+We import the `useSelector` function from React-Redux, and then create a function called `selectHelloText`. It receives whatever state is in the Redux
+store as an argument. For now, we'll just return that entire state value.


I've seen beginners frequently return the entire state when they don't need to in mapStateToProps, causing unnecessary rerenders and defeating the purpose of this API. I understand that there's just one value in the store in this case, but I think we should at least note that only the state the component needs should be returned, as Redux optimizes rerenders based on the result. Also would help to mention that selectors getting the same data should be extracted into functions so they can be shared across components or even other selectors.

nickserv · 2020-01-20T00:18:43Z

Sorry I fucked up that last review, those comments are supposed to be part of my suggested changes

dceddia

I left a few comments on the quick start page. I think at a high level, it might be better to show a working React example and "refactor it" to use Redux & RTK. I think it'd be more useful if the React app had at least a small bit of state that could be extracted out into Redux.

And since this is a Quick Start, maybe just show the full working React + Redux example right up top, ready to copy-paste, and leave the explanation for afterward.

dceddia · 2020-01-21T19:45:04Z

docs/introduction/QuickStart.mdx

+
+It helps you write applications that behave consistently and can run in different environments (client, server, and native).
+It also helps you to write code that is testable, and enables you to better understand when, where, why, and how the data in your
+application has changed.


I know the "predictable state container" is the official descriptor but to a newcomer I don't think it means much. I think I'd jump right to the big why:

Redux helps you to write code that is testable, and helps you to understand when, where, why, and how the data in your application has changed.

dceddia · 2020-01-21T19:50:12Z

docs/introduction/QuickStart.mdx

+
+### How does Redux work with a UI?
+
+Redux, by itself, is a plain JavaScript library. You can use Redux together with React, or with any other UI view library.


I get the impression that the vast majority of people use Redux with React, and the second sentence makes it clear that it works with other libraries. I'd make the title "How does Redux work with React?" to align with most people's expectations and make it feel like they're in the right place.

dceddia · 2020-01-21T19:53:34Z

docs/introduction/QuickStart.mdx

+
+Redux, by itself, is a plain JavaScript library. You can use Redux together with React, or with any other UI view library.
+
+To help make this possible, there are additional bindings libraries that connect together a Redux store and your UI components. Each different


This "To help make this possible..." sentence could be cut - this guide isn't going to cover other bindings libraries (I think?). The next sentence makes it clear enough imo.

dceddia · 2020-01-21T19:55:49Z

docs/introduction/QuickStart.mdx

+[CodeSandbox.io](https://codesandbox.io) is an online IDE that lets you create entire web applications in your browser, without needing to
+install anything locally.
+
+Create a new React project sandbox by browsing to the [CodeSandbox "Create Sandbox" page](https://codesandbox.io/s/) and selecting the official React template.


Link directly to https://codesandbox.io/s/new for a new React app so we can skip the "browsing" instructions.

dceddia · 2020-01-21T19:56:22Z

docs/introduction/QuickStart.mdx

+
+Create a new React project sandbox by browsing to the [CodeSandbox "Create Sandbox" page](https://codesandbox.io/s/) and selecting the official React template.
+
+Once the sandbox has been created, click the "Add Dependency" button on the left, search for `@reduxjs/toolkit`, add it, and then do the same for `react-redux`.


Could add a screenshot/GIF here?

dceddia · 2020-01-21T20:13:28Z

docs/introduction/QuickStart.mdx

+#### Key Concept: "Reducers"
+
+A **_reducer_** is a function that know how to calculate a new state value when asked. A Redux store requires a single reducer function
+when it is created, which we call the "root reducer" to say that it is the starting point for any other reducer functions inside.


Maybe skip talking about "root reducers" until later. Get one working first before revealing that there can be a tree of them.

dceddia · 2020-01-21T20:15:48Z

docs/introduction/QuickStart.mdx

+A **_reducer_** is a function that know how to calculate a new state value when asked. A Redux store requires a single reducer function
+when it is created, which we call the "root reducer" to say that it is the starting point for any other reducer functions inside.
+
+Every reducer is called with two arguments: the current `state`, and an object called an **`action`**. We'll look at actions a bit later.


Mention here that the reducer "returns the new computed state".

Could also add a few words to describe actions so it's not gnawing at them - "...an object called an action that describes how to update the state"

dceddia · 2020-01-21T20:20:11Z

docs/introduction/QuickStart.mdx

+
+- Reducers must always return a state value, never `undefined`
+- Reducers can only decide what the next state value should be by looking at the `state` and `action` arguments
+- Reducers are not allowed to make changes to the `state` argument, or anything else. They can only create the new state value by making copies of the originals, and updating the copies.


Yeah this is a good point. Later on, it would be good to show "here's the hard way (ignoring that immer is installed)" and "here's the easy way because of immer".

dceddia · 2020-01-21T20:23:33Z

docs/introduction/QuickStart.mdx

+It's _possible_ that we could move the store into a separate file, import that store into the `App.js` file, and call `store.getState()`. But, as the
+app gets bigger, we'd have to import the store into _every_ file. That's not a good idea.


If this stays, it'd be good to explain why "That's not a good idea." - it will get messy? hard to manage? but there's an easier way?

dceddia · 2020-01-21T20:24:57Z

docs/introduction/QuickStart.mdx

+
+#### Key Concept: "Selectors"
+
+A **_selector_** is a function that takes the Redux store state as an argument, and returns some part of that store state.


It quite literally "selects" a portion of the state.

markerikson · 2020-01-23T05:06:29Z

Haven't given up on this, but I decided I ought to take a step back and take notes on several excellent React+Redux tutorials (and some totally non-Redux-related tutorials) to get a feel for how they handle explanations first. Then I'll try to take some inspiration from those and take another stab at this.

markerikson · 2020-05-23T16:33:29Z

Should have closed this a while ago.

markerikson added 5 commits January 6, 2020 21:48

Update Docusaurus to v2.alpha.40

6ebed7f

Update CSS to allow multiple note colors and more details blocks

bae55be

Add empty Quick Start page

d201489

Test MDX content

503c15d

Initial Quick start partial content

e813599

nickserv suggested changes Jan 7, 2020

View reviewed changes

markerikson and others added 3 commits January 7, 2020 07:53

Update docs/introduction/QuickStart.mdx

6063b94

Co-Authored-By: Nick McCurdy <nick@nickmccurdy.com>

Finish app setup steps

09542a3

Merge branch 'docs/quick-start-page' of https://github.com/reduxjs/redux

6428359

into docs/quick-start-page

bpas247 reviewed Jan 8, 2020

View reviewed changes

bpas247 reviewed Jan 10, 2020

View reviewed changes

nickserv reviewed Jan 20, 2020

View reviewed changes

nickserv suggested changes Jan 20, 2020

View reviewed changes

dceddia reviewed Jan 21, 2020

View reviewed changes

TODO sales pitch

9a08a9f

bpas247 mentioned this pull request Mar 21, 2020

docs(introduction): add "Quick Start" page #3651

Closed

5 tasks

markerikson mentioned this pull request Mar 29, 2020

Create the Redux Essentials page, take 2 #3740

Merged

2 tasks

markerikson closed this May 23, 2020

aryaemami59 deleted the docs/quick-start-page branch January 3, 2025 07:46


		TODO figure out what else to put here, or if this should be dropped

		</Note>

		It's _possible_ that we could move the store into a separate file, import that store into the `App.js` file, and call `store.getState()`. But, as the
		app gets bigger, we'd have to import the store into _every_ file. That's not a good idea.

		"@docusaurus/core": "2.0.0-alpha.40",
		"@docusaurus/preset-classic": "2.0.0-alpha.40",


		#### Key Concept: "Reducers"

		A _reducer_ is a function that know how to calculate a new state value when asked. A Redux store requires a single reducer function

	A _reducer_ is a function that know how to calculate a new state value when asked. A Redux store requires a single reducer function
	A _reducer_ is a function that knows how to calculate a new state value when asked. A Redux store requires a single reducer function


		### How does Redux work with a UI?

		Redux, by itself, is a plain JavaScript library. You can use Redux together with React, or with any other UI view library.


		Redux, by itself, is a plain JavaScript library. You can use Redux together with React, or with any other UI view library.

		To help make this possible, there are additional bindings libraries that connect together a Redux store and your UI components. Each different


		Create a new React project sandbox by browsing to the [CodeSandbox "Create Sandbox" page](https://codesandbox.io/s/) and selecting the official React template.

		Once the sandbox has been created, click the "Add Dependency" button on the left, search for `@reduxjs/toolkit`, add it, and then do the same for `react-redux`.


		#### Key Concept: "Selectors"

		A _selector_ is a function that takes the Redux store state as an argument, and returns some part of that store state.

[Docs Rewrite] Create the "Quick Start" page #3675

[Docs Rewrite] Create the "Quick Start" page #3675

Conversation

markerikson commented Jan 7, 2020

PR Type

Checklist

What docs page is being added or updated?

For Adding New Content

What kind of content category is this page (tutorial, how-to, explanation, reference)?

Who is the intended target audience?

What knowledge are we assuming they have?

What are the intended results or takeaways from reading this page?

What is the most critical info they should learn?

Status

netlify bot commented Jan 7, 2020 • edited Loading

nickserv left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as resolved.

This comment was marked as resolved.

markerikson Jan 7, 2020 • edited Loading

Choose a reason for hiding this comment

markerikson commented Jan 8, 2020

bpas247 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bpas247 Jan 10, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bpas247 Jan 10, 2020 • edited Loading

Choose a reason for hiding this comment

DylanVann commented Jan 19, 2020

1. Create a Create React App app:

2. Install @reduxjs/toolkit-react

3. Paste this example into index.js

taniarascia commented Jan 19, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markerikson Jan 23, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nickserv Jan 20, 2020 • edited Loading

Choose a reason for hiding this comment

nickserv commented Jan 20, 2020

dceddia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

markerikson commented Jan 23, 2020

markerikson commented May 23, 2020

netlify bot commented Jan 7, 2020 •

edited

Loading

markerikson Jan 7, 2020 •

edited

Loading

bpas247 Jan 10, 2020 •

edited

Loading

bpas247 Jan 10, 2020 •

edited

Loading

2. Install `@reduxjs/toolkit-react`

3. Paste this example into `index.js`

taniarascia commented Jan 19, 2020 •

edited

Loading

markerikson Jan 23, 2020 •

edited

Loading

nickserv Jan 20, 2020 •

edited

Loading