docs: React 18, streaming SSR, RSC with new APIs. (#33986)

docs/advanced-features/react-18/overview.md

@@ -0,0 +1,28 @@
+# React 18
+
+[React 18](https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html) adds new features including Suspense, automatic batching of updates, APIs like `startTransition`, and a new streaming API for server rendering with support for `React.lazy`.
+Next.js also provides streaming related APIs, please checkout [next/streaming](/docs/api-reference/next/streaming.md) for details.
+
+React 18 is now in Release Candidate (RC). Read more about React 18's [release plan](https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html) and discussions from the [working group](https://github.com/reactwg/react-18/discussions).
+
+## Using React 18 with Next.js
+
+Install the RC version of React 18:
+
+```jsx
+npm install next@latest react@rc react-dom@rc
+```
+
+You can now start using React 18's new APIs like `startTransition` and `Suspense` in Next.js.
+
+## Streaming SSR (Alpha)
+
+Streaming server-rendering (SSR) is an experimental feature in Next.js 12. When enabled, SSR will use the same [Edge Runtime](/docs/api-reference/edge-runtime.md) as [Middleware](/docs/middleware.md).
+
+[Learn how to enable streaming in Next.js.](/docs/react-18/streaming.md)
+
+## React Server Components (Alpha)
+
+Server Components are a new feature in React that let you reduce your JavaScript bundle size by separating server and client-side code. Server Components allow developers to build apps that span the server and client, combining the rich interactivity of client-side apps with the improved performance of traditional server rendering.
+
+Server Components are still in research and development. [Learn how to try Server Components](/docs/react-18/server-components.md) as an experimental feature in Next.js.

docs/advanced-features/react-18/server-components.md

@@ -0,0 +1,132 @@
+# React Server Components (Alpha)
+
+Server Components allow us to render React components on the server. This is fundamentally different from server-side rendering (SSR) where you're pre-generating HTML on the server. With Server Components, there's **zero client-side JavaScript needed,** making page rendering faster. This improves the user experience of your application, pairing the best parts of server-rendering with client-side interactivity.
+
+### Enable React Server Components
+
+To use React Server Components, ensure you have React 18 installed:
+
+```jsx
+npm install next@latest react@rc react-dom@rc
+```
+
+Then, update your `next.config.js`:
+
+```jsx
+// next.config.js
+module.exports = {
+  experimental: {
+    runtime: 'nodejs',
+    serverComponents: true,
+  },
+}
+```
+
+Using `runtime` also enables [Streaming SSR](/docs/advanced-features/react-18/streaming). When setting `runtime` to `'edge'`, the server will be running entirely in the [Edge Runtime](https://nextjs.org/docs/api-reference/edge-runtime).
+
+Now, you can start using React Server Components in Next.js. [See our example](https://github.com/vercel/next-rsc-demo) for more information.
+
+### Server Components Conventions
+
+To run a component on the server, append `.server.js` to the end of the filename. For example, `./pages/home.server.js` will be treated as a Server Component.
+
+For client components, append `.client.js` to the filename. For example, `./components/avatar.client.js`.
+
+You can then import other server or client components from any server component. Note: a server component **can not** be imported by a client component. Components without "server/client" extensions will be treated as shared components and can be used and rendered by both sides, depending on where it is imported. For example:
+
+```jsx
+// pages/home.server.js
+
+import { Suspense } from 'react'
+
+import Profile from '../components/profile.server'
+import Content from '../components/content.client'
+
+export default function Home() {
+  return (
+    <div>
+      <h1>Welcome to React Server Components</h1>
+      <Suspense fallback={'Loading...'}>
+        <Profile />
+      </Suspense>
+      <Content />
+    </div>
+  )
+}
+```
+
+The `<Home>` and `<Profile>` components will always be server-side rendered and streamed to the client, and will not be included by the client-side JavaScript. However, `<Content>` will still be hydrated on the client-side, like normal React components.
+
+> Make sure you're using default imports and exports for server components (`.server.js`). The support of named exports are a work in progress!
+
+To see a full example, check out the [hello world example](https://github.com/vercel/next.js/tree/canary/examples/react-server-components) or the larger [vercel/next-rsc-demo demo](https://github.com/vercel/next-rsc-demo).
+
+## Supported Next.js APIs
+
+### `next/link` and `next/image`
+
+You can use `next/link` and `next/image` like before and they will be treated as client components to keep the interaction on client side.
+
+### `next/document`
+
+If you have a custom `_document`, you have to change your `_document` to a functional component like below to use server components. If you don't have one, Next.js will use the default `_document` component for you.
+
+```jsx
+// pages/_document.js
+import { Html, Head, Main, NextScript } from 'next/document'
+
+export default function Document() {
+  return (
+    <Html>
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  )
+}
+```
+
+### `next/app`
+
+If you're using `_app.js`, the usage is the same as [Custom App](/docs/advanced-features/custom-app).
+If you're using `_app.server.js` as a server component, see the example below where it only receives the `children` prop as React elements. You can wrap any other client or server components around `children` to customize the layout of your app.
+
+```js
+// pages/_app.server.js
+export default function App({ children }) {
+  return children
+}
+```
+
+### Routing
+
+Both basic routes with path and queries and dynamic routes are supported. If you need to access the router in server components(`.server.js`), they will receive `router` instance as a prop so that you can directly access them without using the `useRouter()` hook.
+
+```jsx
+// pages/index.server.js
+
+export default function Index({ router }) {
+  // You can access routing information by `router.pathname`, etc.
+  return 'hello'
+}
+```
+
+### Unsupported Next.js APIs
+
+While RSC and SSR streaming are still in the alpha stage, not all Next.js APIs are supported. The following Next.js APIs have limited functionality within Server Components. React 18 use without SSR streaming is not affected.
+
+#### React internals
+
+Most React hooks, such as `useContext`, `useState`, `useReducer`, `useEffect` and `useLayoutEffect`, are not supported as of today since server components are executed per request and aren't stateful.
+
+#### Data Fetching & Styling
+
+Like streaming SSR, styling and data fetching within `Suspense` on the server side are not well supported. We're still working on them.
+
+Page level exported methods like `getInitialProps`, `getStaticProps` and `getStaticPaths` are not supported.
+
+#### `next/head` and I18n
+
+We are still working on support for these features.

docs/advanced-features/react-18/streaming.md

@@ -0,0 +1,71 @@
+# Streaming SSR (Alpha)
+
+React 18 will include architectural improvements to React server-side rendering (SSR) performance. This means you can use `Suspense` in your React components in streaming SSR mode and React will render them on the server and send them through HTTP streams.
+It's worth noting that another experimental feature, React Server Components, is based on streaming. You can read more about server components related streaming APIs in [`next/streaming`](docs/api-reference/next/streaming.md). However, this guide focuses on basic React 18 streaming.
+
+## Enable Streaming SSR
+
+Enabling streaming SSR means React renders your components into streams and the client continues receiving updates from these streams even after the initial SSR response is sent. In other words, when any suspended components resolve down the line, they are rendered on the server and streamed to the client. With this strategy, the app can start emitting HTML even before all the data is ready, improving your app's loading performance. As an added bonus, in streaming SSR mode, the client will also use selective hydration strategy to prioritize component hydration which based on user interaction.
+
+To enable streaming SSR, set the experimental option `runtime` to either `'nodejs'` or `'edge'`:
+
+```jsx
+// next.config.js
+module.exports = {
+  experimental: {
+    runtime: 'nodejs',
+  },
+}
+```
+
+This option determines the environment in which streaming SSR will be happening. When setting to `'edge'`, the server will be running entirely in the [Edge Runtime](https://nextjs.org/docs/api-reference/edge-runtime).
+
+## Streaming Features
+
+### next/dynamic
+
+Dynamic imports through `React.lazy` have better support in React 18. Previously, Next.js supported dynamic imports internally without requiring `Suspense` or `React.lazy`. Now to embrace the official APIs on the React side, we provide you with `options.suspense` in `next/dynamic`.
+
+```jsx
+import dynamic from 'next/dynamic'
+import { lazy, Suspense } from 'react'
+
+import Content from '../components/content'
+
+// These two ways are identical:
+const Profile = dynamic(() => import('./profile'), { suspense: true })
+const Footer = lazy(() => import('./footer'))
+
+export default function Home() {
+  return (
+    <div>
+      <Suspense fallback={<Spinner />}>
+        {/* A component that uses Suspense */}
+        <Content />
+      </Suspense>
+      <Suspense fallback={<Spinner />}>
+        <Profile />
+      </Suspense>
+      <Suspense fallback={<Spinner />}>
+        <Footer />
+      </Suspense>
+    </div>
+  )
+}
+```
+
+Check out [`next/streaming`](/docs/api-reference/next/streaming.md) for more details on building Next.js apps in streaming SSR mode.
+
+## Important Notes
+
+#### `next/head` and `next/script`
+
+Using resource tags (e.g. scripts or stylesheets) in `next/head` won't work as intended with streaming, as the loading order and timing of `next/head` tags can no longer be guaranteed once you add Suspense boundaries. We suggest moving resource tags to `next/script` with the `afterInteractive` or `lazyOnload` strategy, or to `_document`. For similar reasons, we also suggest migrating `next/script` instances with the `beforeInteractive` strategy to `_document`.
+
+#### Data Fetching
+
+Currently, data fetching within `Suspense` boundaries on the server side is not fully supported, which could lead to mismatching between server and client. In the short-term, please don't try data fetching within `Suspense`.
+
+#### Styling
+
+The Next.js team is working on support for `styled-jsx` and CSS modules in streaming SSR. Stay tuned for updates.