docs(introduction): add "Quick Start" page #3651
Conversation
Adds a Quick Start page, which will be used as a quick copy/paste reference for users wanting to bootstrap their next project.
|
Deploy preview for redux-docs ready! Built with commit 3bf047f |
| const substract = createAction('SUBSTRACT') | ||
| ``` | ||
|
|
||
| Here we're using Redux Toolkit's `createAction` to create the necessary actions we'll be using for the app. |
There was a problem hiding this comment.
Needs to elaborate a bit more on why we define actions.
There was a problem hiding this comment.
Should also link to RTK's createAction docs.
| - The second argument defines a "lookup table" object, where the key is the action type and the value is the reducer function associated with the action. | ||
| - In case you aren't familiar with the weird `[add]` syntax, it is known as the [ES6 object "computed property" syntax](https://javascript.info/object#computed-properties). This allows us to create keys from actions made with `createAction` with ease (since the computed properties ultimately calls `toString()` on those variables, which `createAction` objects overrides with the value of its type property). | ||
|
|
||
| The reducers' implementations should be fairly straightforward, simply adding or subtracting the action payload. |
There was a problem hiding this comment.
This is making an unfair assumption on the reader's knowledge, consider revising the wording here.
|
|
||
| At first glance this may be a little strange to look at, but let's unpack it: | ||
|
|
||
| - The first argument passed into `createReducer` is the initial state, which we'll start at `0`. |
There was a problem hiding this comment.
createReducer should link to RTK's docs.
|
|
||
| Now this may leave you wondering "gee, why do I need to define action creators outside of the reducer? What if there was a way to bake action creators into the reducer itself?" | ||
|
|
||
| Well, that's where `createSlice` from Redux Toolkit comes in :) |
There was a problem hiding this comment.
Should link to RTK's createSlice docs.
| }) | ||
| ``` | ||
|
|
||
| Now the `add` and `subtract` actions will be available via `calculatorSlice.actions` and the reducer function will be available via `calculatorSlice.reducer`. This keeps our "slice" of the store all in one place, so that we'll know where all of the logic for this part of the store resides. |
There was a problem hiding this comment.
Should link to external resource on the concept of "slices" of stores.
| }) | ||
| ``` | ||
|
|
||
| Using Redux Toolkit's `configureStore`, we can setup the store with helpful default middleware out of the box. Unfortunately, this example won't be able to highlight this middleware, but be sure to check out the [included default middleware](https://redux-starter-kit.js.org/api/getDefaultMiddleware#included-default-middleware) to learn more about them. |
There was a problem hiding this comment.
should link to RTK's configureStore docs.
| alright, now we have a simple app setup that utilizes our Redux code to have a functioning calculator app. it will now dispatch actions to update the value in the store, | ||
| depending on which button was clicked. |
There was a problem hiding this comment.
This makes feel like I'm wanting more out of this explanation. Adding external resources might help? Or just a more in-depth explanation.
There was a problem hiding this comment.
Also needs a runnable CodeSandbox here.
| <Button action={add(input)}>Add Amount</Button> | ||
| <Button action={subtract(input)}>Subtract Amount</Button> |
There was a problem hiding this comment.
This looks bad, I'm not sure why. It almost makes this code snippet unusable, since if I'm an end user copy/pasting this code I would most likely re-write this portion entirely.
| - For the `Button` component, we use the `useDispatch` hook in order to dispatch the passed in actions. | ||
| - For the `App` component, we define the input element and its state here so that we can pass down the `value` of the input element to the `Button` components for dispatch. This allows the user to enter in a specified value to either add or subtract. | ||
|
|
||
| Great! Now we have a fully-functioning simple React calculator app :) |
There was a problem hiding this comment.
Link to external resources and runnable CodeSandbox example.
| @@ -2,6 +2,7 @@ | |||
| "docs": { | |||
| "Introduction": [ | |||
| "introduction/getting-started", | |||
| "introduction/quick-start", | |||
There was a problem hiding this comment.
Personally not a fan of this placement. The first section out of this page is about installation, but the next page this navigates to is the Installation page?
|
I actually just opened up #3674 to cover creating a "Quick Start" page, and I'd forgotten that you'd filed this. I just had some discussion with @taniarascia about some ideas for this, and I jotted some notes in that issue. I'm going to skim yours, but then take a stab at putting together my own version. |
Sounds good, should I go ahead and close this then? |
|
Superseded by #3675 |
PR Type
Does this PR add a new page, or update an existing page?
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)?
tutorial.
Who is the intended target audience?
Redux users who want to quickly bootstrap their next project with the latest technologies.
What knowledge are we assuming they have?
Very minimal Redux knowledge, no prior Redux Toolkit experience needed. Basic JS and/or React knowledge.
What are the intended results or takeaways from reading this page?
To be able to gain just enough Redux and Redux Toolkit knowledge to be able to start their next project. They can learn Redux more in-depth in later tutorials.
What is the most critical info they should learn?
Learning the basics of Redux and Redux Toolkit, and how to tie those basics in to building vanilla or React based apps.
TODOs