Adding Learn docs for RSCs #6502
Conversation
Size changes📦 Next.js Bundle Analysis for react-devThis analysis was generated by the Next.js Bundle Analysis action. 🤖 Three Pages Changed SizeThe following pages changed size from the code in this PR compared to its base branch:
DetailsOnly the gzipped size is provided here based on an expert tip. First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If Any third party scripts you have added directly to your app using the Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 10% or more, there will be a red status indicator applied, indicating that special attention should be given to this. |
|
|
||
| <Intro> | ||
|
|
||
| The data rendered in your React app may come from a variety of sources and in many cases, your components may need to "wait" for the data to be fetched before they can render. |
There was a problem hiding this comment.
| The data rendered in your React app may come from a variety of sources and in many cases, your components may need to "wait" for the data to be fetched before they can render. | |
| The data rendered in your React app may come from a variety of sources, and in many cases, your components may need to wait for the data to be fetched before they can render. |
|
|
||
| * Static and dynamic data and how it affects data access | ||
| * How to fetch data in your components and examples of common data sources | ||
| * How components "wait" for data to be fetched |
There was a problem hiding this comment.
| * How components "wait" for data to be fetched | |
| * How components wait for data to be fetched |
| In our previous React examples, we've used local variables to hold data that our components use. | ||
|
|
||
| ```js | ||
| const ESTABLISHED_YEAR = 1986; |
| ``` | ||
| In this component, the data is the year we store in the local variable `ESTABLISHED_YEAR`. | ||
|
|
||
| Our app may also use ESTABLISHED_YEAR in other places so we can decouple the data from our UI and provide the data in a separate module. |
There was a problem hiding this comment.
| Our app may also use ESTABLISHED_YEAR in other places so we can decouple the data from our UI and provide the data in a separate module. | |
| Since `ESTABLISHED_YEAR` is a variable, and not just information that's directly written in this component, we can re-use the same information in multiple components. We can also define `ESTABLISHED_YEAR` in a separate module and import it. |
| } | ||
| ``` | ||
|
|
||
| In both of these examples, the data is set and read once for `CompanyFooter`. The examples read the data outside of the component function so every-time the component is rendered, it refers to the same data. |
There was a problem hiding this comment.
Is there a place earlier in the docs where we talk about things being defined in the module vs in the component render? If so it might be good to link back to it or to use very similar language here to refer back to the same concept. (I don't see any place that we talk about this, but it seems like something that should be explained clearly so I'm surprised.)
|
|
||
| Now, imagine you are trying to render the component `LATemperature`. The first thing you do is kick off the asynchronous work of reading the temperature file and you've received `tempPromise` as a Promise. Now, you're free to do the next set of work. But wait, the next instruction requires you to know the temperature, yet all we have is a Promise. The Promise may or may not be ready with the actual temperature value. | ||
|
|
||
| Here is where `await` comes in. `await` is a keyword that is used before a Promise and tells JavaScript to pause running the current function and wait for the Promise to resolve.Then, when it is resolved, await will unwrap the Promise container to return the value. We use await on tempPromise to pause our component rendering until the file is read and receive the value returned. |
There was a problem hiding this comment.
| Here is where `await` comes in. `await` is a keyword that is used before a Promise and tells JavaScript to pause running the current function and wait for the Promise to resolve.Then, when it is resolved, await will unwrap the Promise container to return the value. We use await on tempPromise to pause our component rendering until the file is read and receive the value returned. | |
| Here is where `await` comes in. `await` is a keyword that is used before a Promise and tells JavaScript to pause running the current function and wait for the Promise to resolve. Then, when it is resolved, `await` will unwrap the Promise container to return the value. We use `await` on `tempPromise` to pause our component rendering until the file has been read. Once the process is done, we receive the value that was read from the file and assign it to the variable `temp`. |
|
|
||
| Here is where `await` comes in. `await` is a keyword that is used before a Promise and tells JavaScript to pause running the current function and wait for the Promise to resolve.Then, when it is resolved, await will unwrap the Promise container to return the value. We use await on tempPromise to pause our component rendering until the file is read and receive the value returned. | ||
|
|
||
| In our analogy, this would be similar to waiting at the dry cleaners for them to finish because the next chore on your todo list requires those clothes. Thus, preventing you from doing anything else in the meantime. |
There was a problem hiding this comment.
The analogy seems imperfect: This makes it sound like using await is equivalent to using a synchronous API that pauses the main thread.
Maybe you need to introduce another task that depends on the dry cleaning, like packing your suitcase for a trip. You can do other stuff in the meantime, but to finish packing your suitcase you need to get the dry cleaning back.
|
|
||
| </DeepDive> | ||
|
|
||
| You'll notice that our component function declarations now have an `async` prefix. This is also a JavaScript keyword and any function that uses `await` will need to be marked with `async`. If a function `await`s a Promise, it itself becomes asynchronous. |
There was a problem hiding this comment.
This paragraph maybe belongs in the main discussion.
Whenever you use await within a function, you have to add the async keyword to the beginning of the function.
| // expensive calculation | ||
| const offset = calculateNewOffset(lastTouchPoint); | ||
|
|
||
| return ... |
There was a problem hiding this comment.
Example incomplete? It doesn't await anything.
|
|
||
| You'll notice that our component function declarations now have an `async` prefix. This is also a JavaScript keyword and any function that uses `await` will need to be marked with `async`. If a function `await`s a Promise, it itself becomes asynchronous. | ||
|
|
||
| Imagine being the parent function calling the `LATemperature` component function. When you call `LATemperature` and it gets to the instruction of `await`-ing `readFilePromise`, JavaScript execution returns to you and you receive a Promise that promises to give you the completed render of `LATemperature`. |
There was a problem hiding this comment.
LATemperature is a component, not a normal function, so you wouldn't normally call it. Maybe the chaining aspect of promises should be explained with a non-component function: for example, you could create a function readTemperature that reads the file and then parses it and extracts the temperature as a number.
|
I'm glad this is being worked on, thanks! lmk if you'd like community feedback. |
This is a draft PR for the outline shared here: https://docs.google.com/document/d/1rQVqqBI7KXVRQjValsCXqsEFqmGQ6h4fWdFAQ9X0d7o/edit?usp=sharing (TODO: put this up accessible somewhere.
Outline of Changes