Suspense: Start Fetching Early (#2551)

content/blog/2019-10-22-react-release-channels.md

@@ -13,7 +13,7 @@ Because the source of truth for React is our [public GitHub repository](https://
 
 We would like to make it even easier for developers to test prerelease builds of React, so we're formalizing our process with three separate release channels.
 
-## Release Channels
+## Release Channels {#release-channels}
 
 > The information in this post is also available on our [Release Channels](/docs/release-channels.html) page. We will update that document whenever there are changes to our release process.
 
@@ -29,7 +29,7 @@ All releases are published to npm, but only Latest uses [semantic versioning](/d
 
 By publishing prereleases to the same registry that we use for stable releases, we are able to take advantage of the many tools that support the npm workflow, like [unpkg](https://unpkg.com) and [CodeSandbox](https://codesandbox.io).
 
-### Latest Channel
+### Latest Channel {#latest-channel}
 
 Latest is the channel used for stable React releases. It corresponds to the `latest` tag on npm. It is the recommended channel for all React apps that are shipped to real users.
 
@@ -37,7 +37,7 @@ Latest is the channel used for stable React releases. It corresponds to the `lat
 
 You can expect updates to Latest to be extremely stable. Versions follow the semantic versioning scheme. Learn more about our commitment to stability and incremental migration in our [versioning policy](/docs/faq-versioning.html).
 
-### Next Channel
+### Next Channel {#next-channel}
 
 The Next channel is a prerelease channel that tracks the master branch of the React repository. We use prereleases in the Next channel as release candidates for the Latest channel. You can think of Next as a superset of Latest that is updated more frequently.
 
@@ -47,7 +47,7 @@ The degree of change between the most recent Next release and the most recent La
 
 Releases in Next are published with the `next` tag on npm. Versions are generated from a hash of the build's contents, e.g. `0.0.0-1022ee0ec`.
 
-#### Using the Next Channel for Integration Testing
+#### Using the Next Channel for Integration Testing {#using-the-next-channel-for-integration-testing}
 
 The Next channel is designed to support integration testing between React and other projects.
 
@@ -73,7 +73,7 @@ If you're the author of a third party React framework, library, developer tool,
 
 A project that uses this workflow is Next.js. (No pun intended! Seriously!) You can refer to their [CircleCI configuration](https://github.com/zeit/next.js/blob/c0a1c0f93966fe33edd93fb53e5fafb0dcd80a9e/.circleci/config.yml) as an example.
 
-### Experimental Channel
+### Experimental Channel {#experimental-channel}
 
 Like Next, the Experimental channel is a prerelease channel that tracks the master branch of the React repository. Unlike Next, Experimental releases include additional features and APIs that are not ready for wider release.
 
@@ -83,7 +83,7 @@ Experimental releases may be significantly different than releases to Next and L
 
 Releases in Experimental are published with the `experimental` tag on npm. Versions are generated from a hash of the build's contents, e.g. `0.0.0-experimental-1022ee0ec`.
 
-#### What Goes Into an Experimental Release?
+#### What Goes Into an Experimental Release? {#what-goes-into-an-experimental-release}
 
 Experimental features are ones that are not ready to be released to the wider public, and may change drastically before they are finalized. Some experiments may never be finalized -- the reason we have experiments is to test the viability of proposed changes.
 
@@ -91,7 +91,7 @@ For example, if the Experimental channel had existed when we announced Hooks, we
 
 You may find it valuable to run integration tests against Experimental. This is up to you. However, be advised that Experimental is even less stable than Next. **We do not guarantee any stability between Experimental releases.**
 
-#### How Can I Learn More About Experimental Features?
+#### How Can I Learn More About Experimental Features? {#how-can-i-learn-more-about-experimental-features}
 
 Experimental features may or may not be documented. Usually, experiments aren't documented until they are close to shipping in Next or Stable.
 

content/blog/2019-11-06-building-great-user-experiences-with-concurrent-mode-and-suspense.md

@@ -11,7 +11,7 @@ At React Conf 2019 we announced an [experimental release](/docs/concurrent-mode-
 
 This post is **aimed at library authors**. If you're primarily an application developer, you might still find some interesting ideas here, but don't feel like you have to read it in its entirety.
 
-## Talk Videos
+## Talk Videos {#talk-videos}
 
 If you prefer to watch videos, some of the ideas from this blog post have been referenced in several React Conf 2019 presentations:
 
@@ -21,7 +21,7 @@ If you prefer to watch videos, some of the ideas from this blog post have been r
 
 This post presents a deeper dive on implementing a data fetching library with Suspense.
 
-## Putting User Experience First
+## Putting User Experience First {#putting-user-experience-first}
 
 The React team and community has long placed a deserved emphasis on developer experience: ensuring that React has good error messages, focusing on components as a way to reason locally about app behavior, crafting APIs that are predictable and encourage correct usage by design, etc. But we haven't provided enough guidance on the best ways to achieve a great *user* experience in large apps.
 
@@ -33,7 +33,7 @@ Thanks to this project, we're more confident than ever that Concurrent Mode and
 
 Relay Hooks -- and GraphQL -- won't be for everyone, and that's ok! Through our work on these APIs we've identified a set of more general patterns for using Suspense. **Even if Relay isn't the right fit for you, we think the key patterns we've introduced with Relay Hooks can be adapted to other frameworks.**
 
-## Best Practices for Suspense
+## Best Practices for Suspense {#best-practices-for-suspense}
 
 It's tempting to focus only on the total startup time for an app -- but it turns out that users' perception of performance is determined by more than the absolute loading time. For example, when comparing two apps with the same absolute startup time, our research shows that users will generally perceive the one with fewer intermediate loading states and fewer layout changes as having loaded faster. Suspense is a powerful tool for carefully orchestrating an elegant loading sequence with a few, well-defined states that progressively reveal content. But improving perceived performance only goes so far -- our apps still shouldn't take forever to fetch all of their code, data, images, and other assets.
 
@@ -43,7 +43,7 @@ It turns out that this approach has some limitations. Consider a page that shows
 
 There's also another often-overlooked downside to this approach. If `<Post>` eagerly requires (or imports) the `<CommentList>` component, our app will have to wait to show the post *body* while the code for the *comments* is downloading. We could lazily load `<CommentList>`, but then that would delay fetching comments data and increase the time to show the full page. How do we resolve this problem without compromising on the user experience?
 
-## Render As You Fetch
+## Render As You Fetch {#render-as-you-fetch}
 
 The fetch-on-render approach is widely used by React apps today and can certainly be used to create great apps. But can we do even better? Let's step back and consider our goal.
 
@@ -59,7 +59,7 @@ This might sound difficult to achieve -- but these constraints are actually incr
 3. Load data incrementally
 4. Treat code like data
 
-### Parallel Data and View Trees
+### Parallel Data and View Trees {#parallel-data-and-view-trees}
 
 One of the most appealing things about the fetch-on-render pattern is that it colocates *what* data a component needs with *how* to render that data. This colocation is great -- an example of how it makes sense to group code by concerns and not by technologies. All the issues we saw above were due to *when* we fetch data in this approach: upon rendering. We need to be able to fetch data *before* we've rendered the component. The only way to achieve that is by extracting the data dependencies into parallel data and view trees. 
 
@@ -93,7 +93,7 @@ Although the GraphQL is written within the component, Relay has a build step (Re
 
 The key is that regardless of the technology we're using to load our data -- GraphQL, REST, etc -- we can separate *what* data to load from how and when to actually load it. But once we do that, how and when *do* we fetch our data?
 
-### Fetch in Event Handlers
+### Fetch in Event Handlers {#fetch-in-event-handlers}
 
 Imagine that we're about to navigate from a list of a user's posts to the page for a specific post. We'll need to download the code for that page -- `Post.js` -- and also fetch its data.
 
@@ -173,7 +173,7 @@ Once we've implemented the ability to start loading code and data for a view ind
 
 Best of all, we can centralize that logic in a few key places -- a router or core UI components -- and get any performance benefits automatically throughout our app. Of course preloading isn't always beneficial. It's something an application would tune based on the user's device or network speed to avoid eating up user's data plans. But the pattern here makes it easier to centralize the implementation of preloading and the decision of whether to enable it or not.
 
-### Load Data Incrementally
+### Load Data Incrementally {#load-data-incrementally}
 
 The above patterns -- parallel data/view trees and fetching in event handlers -- let us start loading all the data for a view earlier. But we still want to be able to show more important parts of the view without waiting for *all* of our data. At Facebook we've implemented support for this in GraphQL and Relay in the form of some new GraphQL directives (annotations that affect how/when data is delivered, but not what data). These new directives, called `@defer` and `@stream`, allow us to retrieve data incrementally. For example, consider our `<Post>` component from above. We want to show the body without waiting for the comments to be ready. We can achieve this with `@defer` and `<Suspense>`:
 
@@ -205,17 +205,17 @@ function Post(props) {
 
 Here, our GraphQL server will stream back the results, first returning the `author` and `title` fields and then returning the comment data when it's ready. We wrap `<CommentList>` in a `<Suspense>` boundary so that we can render the post body before `<CommentList>` and its data are ready. This same pattern can be applied to other frameworks as well. For example, apps that call a REST API might make parallel requests to fetch the body and comments data for a post to avoid blocking on all the data being ready.
 
-### Treat Code Like Data
+### Treat Code Like Data {#treat-code-like-data}
 
 But there's one thing that's still missing. We've shown how to preload *data* for a route -- but what about code? The example above cheated a bit and used `React.lazy`. However, `React.lazy` is, as the name implies, *lazy*. It won't start downloading code until the lazy component is actually rendered -- it's "fetch-on-render" for code!
 
 To solve this, the React team is considering APIs that would allow bundle splitting and eager preloading for code as well. That would allow a user to pass some form of lazy component to a router, and for the router to trigger loading the code alongside its data as early as possible.
 
-## Putting It All Together
+## Putting It All Together {#putting-it-all-together}
 
 To recap, achieving a great loading experience means that we need to **start loading code and data as early as possible, but without waiting for all of it to be ready**. Parallel data and view trees allow us to load the data for a view in parallel with loading the view (code) itself. Fetching in an event handler means we can start loading data as early as possible, and even optimistically preload a view when we have enough confidence that a user will navigate to it. Loading data incrementally allows us to load important data earlier without delaying the fetching of less important data. And treating code as data -- and preloading it with similar APIs -- allows us to load it earlier too.
 
-## Using These Patterns
+## Using These Patterns {#using-these-patterns}
 
 These patterns aren't just ideas -- we've implemented them in Relay Hooks and are using them in production throughout the new facebook.com (which is currently in beta testing). If you're interested in using or learning more about these patterns, here are some resources:
 

content/docs/concurrent-mode-suspense.md

@@ -36,6 +36,7 @@ Suspense for Data Fetching is a new feature that lets you also use `<Suspense>`
   - [Approach 1: Fetch-on-Render (not using Suspense)](#approach-1-fetch-on-render-not-using-suspense)
   - [Approach 2: Fetch-Then-Render (not using Suspense)](#approach-2-fetch-then-render-not-using-suspense)
   - [Approach 3: Render-as-You-Fetch (using Suspense)](#approach-3-render-as-you-fetch-using-suspense)
+- [Start Fetching Early](#start-fetching-early)
   - [We’re Still Figuring This Out](#were-still-figuring-this-out)
 - [Suspense and Race Conditions](#suspense-and-race-conditions)
   - [Race Conditions with useEffect](#race-conditions-with-useeffect)
@@ -364,6 +365,56 @@ This has an interesting implication. Even if we use a GraphQL client that collec
 
 Note how we eliminated the `if (...)` "is loading" checks from our components. This doesn't only remove boilerplate code, but it also simplifies making quick design changes. For example, if we wanted profile details and posts to always "pop in" together, we could delete the `<Suspense>` boundary between them. Or we could make them independent from each other by giving each *its own* `<Suspense>` boundary. Suspense lets us change the granularity of our loading states and orchestrate their sequencing without invasive changes to our code.
 
+## Start Fetching Early {#start-fetching-early}
+
+If you're working on a data fetching library, there's a crucial aspect of Render-as-You-Fetch you don't want to miss. **We kick off fetching _before_ rendering.** Look at this code example closer:
+
+```js
+// Start fetching early!
+const resource = fetchProfileData();
+
+// ...
+
+function ProfileDetails() {
+  // Try to read user info
+  const user = resource.user.read();
+  return <h1>{user.name}</h1>;
+}
+```
+
+**[Try it on CodeSandbox](https://codesandbox.io/s/frosty-hermann-bztrp)**
+
+Note that the `read()` call in this example doesn't *start* fetching. It only tries to read the data that is **already being fetched**. This difference is crucial to creating fast applications with Suspense. We don't want to delay loading data until a component starts rendering. As a data fetching library author, you can enforce this by making it impossible to get a `resource` object without also starting a fetch. Every demo on this page using our "fake API" enforces this.
+
+You might object that fetching "at the top level" like in this example is impractical. What are we going to do if we navigate to another profile's page? We might want to fetch based on props. The answer to this is **we want to start fetching in the event handlers instead**. Here is a simplified example of navigating between user's pages:
+
+```js{1,2,10,11}
+// First fetch: as soon as possible
+const initialResource = fetchProfileData(0);
+
+function App() {
+  const [resource, setResource] = useState(initialResource);
+  return (
+    <>
+      <button onClick={() => {
+        const nextUserId = getNextId(resource.userId);
+        // Next fetch: when the user clicks
+        setResource(fetchProfileData(nextUserId));
+      }}>
+        Next
+      </button>
+      <ProfilePage resource={resource} />
+    </>
+  );
+}
+```
+
+**[Try it on CodeSandbox](https://codesandbox.io/s/infallible-feather-xjtbu)**
+
+With this approach, we can **fetch code and data in parallel**. When we navigate between pages, we don't need to wait for a page's code to load to start loading its data. We can start fetching both code and data at the same time (during the link click), delivering a much better user experience.
+
+This poses a question of how do we know *what* to fetch before rendering the next screen. There are several ways to solve this (for example, by integrating data fetching closer with your routing solution). If you work on a data fetching library, [Building Great User Experiences with Concurrent Mode and Suspense](/blog/2019/11/06/building-great-user-experiences-with-concurrent-mode-and-suspense.html) presents a deep dive on how to accomplish this and why it's important.
+
 ### We're Still Figuring This Out {#were-still-figuring-this-out}
 
 Suspense itself as a mechanism is flexible and doesn't have many constraints. Product code needs to be more constrained to ensure no waterfalls, but there are different ways to provide these guarantees. Some questions that we're currently exploring include:

content/docs/release-channels.md

@@ -22,7 +22,7 @@ All releases are published to npm, but only Latest uses [semantic versioning](/d
 
 By publishing prereleases to the same registry that we use for stable releases, we are able to take advantage of the many tools that support the npm workflow, like [unpkg](https://unpkg.com) and [CodeSandbox](https://codesandbox.io).
 
-### Latest Channel
+### Latest Channel {#latest-channel}
 
 Latest is the channel used for stable React releases. It corresponds to the `latest` tag on npm. It is the recommended channel for all React apps that are shipped to real users.
 
@@ -30,7 +30,7 @@ Latest is the channel used for stable React releases. It corresponds to the `lat
 
 You can expect updates to Latest to be extremely stable. Versions follow the semantic versioning scheme. Learn more about our commitment to stability and incremental migration in our [versioning policy](/docs/faq-versioning.html).
 
-### Next Channel
+### Next Channel {#next-channel}
 
 The Next channel is a prerelease channel that tracks the master branch of the React repository. We use prereleases in the Next channel as release candidates for the Latest channel. You can think of Next as a superset of Latest that is updated more frequently.
 
@@ -40,7 +40,7 @@ The degree of change between the most recent Next release and the most recent La
 
 Releases in Next are published with the `next` tag on npm. Versions are generated from a hash of the build's contents, e.g. `0.0.0-1022ee0ec`.
 
-#### Using the Next Channel for Integration Testing
+#### Using the Next Channel for Integration Testing {#using-the-next-channel-for-integration-testing}
 
 The Next channel is designed to support integration testing between React and other projects.
 
@@ -66,7 +66,7 @@ If you're the author of a third party React framework, library, developer tool,
 
 A project that uses this workflow is Next.js. (No pun intended! Seriously!) You can refer to their [CircleCI configuration](https://github.com/zeit/next.js/blob/c0a1c0f93966fe33edd93fb53e5fafb0dcd80a9e/.circleci/config.yml) as an example.
 
-### Experimental Channel
+### Experimental Channel {#experimental-channel}
 
 Like Next, the Experimental channel is a prerelease channel that tracks the master branch of the React repository. Unlike Next, Experimental releases include additional features and APIs that are not ready for wider release.
 
@@ -76,7 +76,7 @@ Experimental releases may be significantly different than releases to Next and L
 
 Releases in Experimental are published with the `experimental` tag on npm. Versions are generated from a hash of the build's contents, e.g. `0.0.0-experimental-1022ee0ec`.
 
-#### What Goes Into an Experimental Release?
+#### What Goes Into an Experimental Release? {#what-goes-into-an-experimental-release}
 
 Experimental features are ones that are not ready to be released to the wider public, and may change drastically before they are finalized. Some experiments may never be finalized -- the reason we have experiments is to test the viability of proposed changes.
 
@@ -84,7 +84,7 @@ For example, if the Experimental channel had existed when we announced Hooks, we
 
 You may find it valuable to run integration tests against Experimental. This is up to you. However, be advised that Experimental is even less stable than Next. **We do not guarantee any stability between Experimental releases.**
 
-#### How Can I Learn More About Experimental Features?
+#### How Can I Learn More About Experimental Features? {#how-can-i-learn-more-about-experimental-features}
 
 Experimental features may or may not be documented. Usually, experiments aren't documented until they are close to shipping in Next or Stable.