RFC: Streaming `getServerSideProps` #30051

devknoll · 2021-10-19T01:24:54Z

devknoll
Oct 19, 2021

Goals

Improve loading performance by allowing apps to flush important resources early
Provide an incremental path to adopting more granular streaming in React 18

Non-Goals

Rendering placeholder content while data is pending
Supporting more than one additional flush

Background

The getServerSideProps API allows an application to fetch the data required for a page component by returning a serializable value in { props: ... }. This value will be passed to the page component for Server-Side Rendering.

The getServerSideProps function can also be used to perform routing by throwing an error, or returning a { notFound: true } or { redirect: ... } object.

Unfortunately, this coupling of routing and data fetching concerns means that Next.js must always wait until all of the data for a page is fetched before it can begin to flush anything, just in case a redirect happens to be returned. In many cases, this causes several hundred of milliseconds delay to metrics like TTFB, FCP, and LCP.

In React 18, these issues are effectively addressed using Suspense and Server Components. However, it may take some time before these are available and applications adopt them, so we sought a shorter term, incremental solution that more apps could benefit from today.

Proposal

We propose the ability for getServerSideProps functions to separate data fetching concerns from routing, so that Next.js can begin flushing the document earlier, allowing the browser to discover critical resources like CSS and fonts sooner.

Today, an application might write getServerSideProps like so:

export async function getServerSideProps() {
  const user = await getUser();
  if (!user) return { notFound: true };
  const data = await getData(user);
  return {
     props: data
  }
}

There is just one Promise that must wait for both data fetching and routing to complete. To separate these concerns and make them more granular, Next.js could allow individual properties to be generated with separate async functions. These functions would resolve to serializable values. Applications could then write getServerSideProps like so:

async function getServerSideProps() {
  const user = await getUser();
  if (!user) return { notFound: true };
  return {
     props: {
         user: new AsyncProp(async () => {
            const data = await getData(user);
            return data;
         })
     }
  }
}

The framework would then be able to flush early parts of the document (like the <head> tag) as soon as getServerSideProps resolves. Then it could flush the rest of the document when all of the AsyncProps resolve.

Note: Nested async functions are wrapped with AsyncProp, as we explicitly do not want to expose a generic method of serializing Promise<T> values.

The `AsyncProp` Object

The primary addition is the AsyncProp object that can be created in getServerSideProps and consumed via its read() method:

export default function Profile({ user }) {
  const data = user.read()
  
  return data
    ? <div>Hello {data.name}!</div>
    : <div>Data could not be loaded. Please try again.</div>
}

The read() method will only return data when every AsyncProp object included in getServerSideProps successfully resolves. In every other case, including while any AsyncProp is pending, the return value is undefined.

Note: We do not provide a built-in mechanism to differentiate between data that is still in-flight and data that has failed to load, as such placeholders are the purpose of Suspense in React 18. You may optionally choose to catch and serialize errors yourself before your promise resolves, but you must take care that the base case (where read() returns undefined) is always handled.

For non-crawler User Agents, incoming requests will then be handled as follows:

Next.js will first generate a fallback response by attempting to render the page before running any AsyncProps. If an error occurs, Next.js will render a 500 error as usual.
The document will be flushed up to (but not including) the closing tag of </head> with a 200 status code (to allow the browser to begin fetching resources), and AsyncProps will begin executing.
When all of the promises successfully resolve, Next.js will render the page again to generate the final response. If any promise is rejected or if an error occurs during that final render, the fallback response will be used as the final response.

If Next.js detects that the User Agent is a crawler, it will wait until the final response is ready, and send it, along with the appropriate 200 or 500 status code.

Other Changes Required

Access to res in `getServerSideProps`

In some cases, it’s possible to access the res object for a short period of time after getServerSideProps resolves, but before Next.js sends it. With this proposal, Next.js will throw an error if you try to access the res object after getServerSideProps resolves. These cases should migrate to middleware instead.

Use of `next/head`

When streaming, Next.js will flush <head> early. For this reason, it's important to move tags required for the first paint such that they will be rendered as direct children of the page, App, or Document components.

Sometimes, tags such as <title> will be driven by an AsyncProp. In these cases, you should make sure to include a default/fallback in one of the aforementioned components. We recommend the App component to ease any future migration to React 18:

// pages/_app.js
export default function App({ Component, pageProps }) {
  return (
    <>
      <Head>
        <title>MyApp</title>
      </Head>
      <Component {...pageProps} />
    </>
  )
}

// pages/[user].js
export default function Profile({ user }) {
  const data = user.read()

  return data
    ? <ProfileContainer data={data} />
    : <div>Data could not be loaded. Please try again.</div>
}

// components/profile-container.js
function ProfileContainer({ data }) {
  return (
    <>
      <Head>
        <title>{data.name} - MyApp</title>
      </Head>
      <div>Hello {data.name}!</div>
    </>
  )
}

Use of `next/script`

<Script> components using the beforeInteractive strategy should be moved to be direct children of the App or Document component. There is an RFC in progress to support beforeInteractive on a per-page basis in a more limited form.

Functional custom Document and CSS-in-JS libraries

As with React 18 streaming, applications with a custom Document component will need to perform a trivial migration to a functional Document component in order to use getServerSideProps streaming. More details will be provided soon.

React 18 Migration

When used with React 18, the read() method of AsyncProp will suspend while data is pending, instead of returning undefined. Applications can add <Suspense> boundaries as usual to customize these loading states.

Changelog

Dec 13th, 2021: Revised with AsyncProp for an improved React 18 migration story
Oct 25th, 2021: Initial version.

Special Thanks

Special thanks to

@kara for her design input, feedback and edits to this proposal, the implementation, and the Next.js Conf presentation
@Janpot for proposing a variation of the API that we ultimately decided to go with

Janpot · 2021-10-26T11:57:21Z

Janpot
Oct 26, 2021

regrading error handling, it concerns me a bit that there's difference in rendering between streaming and non-streaming. Wouldn't it be possible to render the error page content instead, just like you would do with non-streaming rendering? I feel like it would be more beneficial to educate users on the following pattern instead:

async function getServerSideProps() {
  return {
     props: async () => {
       try {
         const data = await getData(user);
         return { data };
       } catch (error) {
         return { error: error.message }
       }
     },
  }
}

This has the benefit that the error handling behavior can be defined in the type definitions of the page properties and be enforced by a type checker both in getServerSideProps and Page component.

1 reply

devknoll Oct 26, 2021
Author

Yep, that’s the intended approach. I’ll make sure we explicitly call this out in the next update of the text 👍

stefanprobst · 2021-10-27T13:11:17Z

stefanprobst
Oct 27, 2021

hi, what are the implications of this for <title> and <meta> tags that depend on data from page props, e.g. a blog post page, which sets the page title to <title>{pageProps.title} | My blog</title>?

1 reply

devknoll Oct 30, 2021
Author

Apologies for the delay! This is an excellent question, thank you. We are planning on updating the text of the RFC next week with more details.

The short version is that we plan on still allowing that pattern, just in a more limited fashion (e.g. only title or meta tags), and with additional dev mode checks and linting recommendations.

hamlim · 2021-12-07T11:43:41Z

hamlim
Dec 7, 2021

Have there been any updates on this RFC? It looks like aspects of this api design are partially supported in Next today, however it seems like it may only eagerly handle 404's and redirects.

We experimented with this a bit in dev but we didn't notice anything different from our regular setup returning an object of props instead of an async function, however we'd be really interested to see this feature be fully supported!

1 reply

kara Dec 7, 2021

It hasn't been implemented yet, but expect another update to the RFC later this week!

devknoll · 2021-12-13T17:49:46Z

devknoll
Dec 13, 2021
Author

I've updated the body of the RFC with our latest thinking. Our goal with these changes is to put anyone who adopts this RFC in React 17 ahead on adopting React 18.

@Janpot I would love if you could provide feedback on the latest iteration.

1 reply

Janpot Mar 25, 2022

Aw man, I'm sorry. I've started writing a feedback about 3 times and never got around finishing it and get closure on my thoughts, then it completely slipped my mind

devknoll · 2022-03-25T17:21:33Z

devknoll
Mar 25, 2022
Author

Thank you everyone who read and participated in this RFC. Your feedback has been greatly appreciated!

When we first designed this RFC, React 18 and React Server Components support in Next.js was further away. Now, however, they are much closer and we have a clearer picture of the user journey. In light of that new information, we've decided that it does not make sense to further pursue this proposal at this time.

Keep an eye out for updates!

The Chrome Aurora team

0 replies

balazsorban44 · 2022-11-07T18:04:35Z

balazsorban44
Nov 7, 2022
Collaborator

Hi, Streaming support as documented here has landed as part of the app/ directory, introduced in Next.js 13. We appreciate the feedback provided by @devknoll and the community!

0 replies

RFC: Streaming getServerSideProps #30051

Uh oh!

Uh oh!

devknoll Oct 19, 2021

Goals

Non-Goals

Background

Proposal

The AsyncProp Object

Other Changes Required

Access to res in getServerSideProps

Use of next/head

Use of next/script

Functional custom Document and CSS-in-JS libraries

React 18 Migration

Changelog

Special Thanks

Replies: 6 comments · 4 replies

Uh oh!

Janpot Oct 26, 2021

Uh oh!

devknoll Oct 26, 2021 Author

Uh oh!

stefanprobst Oct 27, 2021

Uh oh!

Uh oh!

devknoll Oct 30, 2021 Author

Uh oh!

hamlim Dec 7, 2021

Uh oh!

kara Dec 7, 2021

Uh oh!

devknoll Dec 13, 2021 Author

Uh oh!

Janpot Mar 25, 2022

Uh oh!

devknoll Mar 25, 2022 Author

Uh oh!

balazsorban44 Nov 7, 2022 Collaborator

RFC: Streaming `getServerSideProps` #30051

devknoll
Oct 19, 2021

The `AsyncProp` Object

Access to res in `getServerSideProps`

Use of `next/head`

Use of `next/script`

Replies: 6 comments 4 replies

Janpot
Oct 26, 2021

devknoll Oct 26, 2021
Author

stefanprobst
Oct 27, 2021

devknoll Oct 30, 2021
Author

hamlim
Dec 7, 2021

devknoll
Dec 13, 2021
Author

devknoll
Mar 25, 2022
Author

balazsorban44
Nov 7, 2022
Collaborator