[wip] Init PPR docs

[rickhanlonii]

Long way from finished.

[github-actions]

Size changes

📦 Next.js Bundle Analysis for react-dev

This analysis was generated by the Next.js Bundle Analysis action. 🤖

One Page Changed Size

The following page changed size from the code in this PR compared to its base branch:

Page	Size (compressed)	First Load
/[[...markdownPath]]	129.8 KB (🟡 +26 B)	240.25 KB

Details

Only 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 next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

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.

[gaearon]

this looks like a real npm package, is this meant to be something like readFile?

[rickhanlonii]

Loading from the filesystem is probably not going to work right? Typically it would need to be like redis or s3 or something like that.

What about './your-storge-layer'

[gaearon]

that seems fine, my main point is just it’s hard to imagine what this is supposed to mean if the format isn’t clear (ie is this just JSON?)

i don’t see why it wouldn’t work via file system though

[rickhanlonii]

Yeah we'll clean it up to make it more clear cc @mattcarrollcode

For the file system to work you'd need to serve both the prerender response and the resume request from the same server, which would be uncommon for prod usecases (you're probably scaled to multiple servers, or running vms that can be destroyed between requests, etc). And if you're serving the prerender result from a CDN, it's basically not possible/advisable because you'd need to sync the postpone state to your resume server somehow. So you probably need some kind of permanent storage layer.

[samselikoff]

Serving the prerender + request from the same server could make sense if you wanted to pre-render some dynamic components at build time, no? For example Remix could expose an API to pre-render some route segments that have dynamic loaders() (while deferring other segments' loaders() to execute at request-time).

What about something like this:

import { resume } from 'react-dom/server';
import { storageClient } from './redis'; // or S3, a file, etc.

async function handler(request) {
  const postponed = await storageClient.get(request.url);
  const stream = await resume(<App />, postponed, {
    bootstrapScripts: ['/main.js']
  });

  return new Response(stream, {
    headers: { 'content-type': 'text/html' },
  });
}

Also postponed does have to be JSON, correct? Even though its shape is opaque?