docs: react 18, streaming SSR, rsc with new apis

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

@@ -0,0 +1,25 @@
+# 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`.
+
+React 18 is in RC now. Read more about React 18's [release plan](https://github.com/reactwg/react-18/discussions) and discussions from the [working group](https://github.com/reactwg/react-18/discussions).
+
+## React 18 Usage in Next.js
+
+Ensure you have the `rc` npm tag of React installed:
+
+```jsx
+npm install next@latest react@rc react-dom@rc
+```
+
+That's all! You can now start using React 18's new APIs like `startTransition` and `Suspense` in Next.js.
+
+## Streaming SSR (Alpha)
+
+This is an experimental feature in Next.js 12, but once enabled, SSR will use the same [Edge Runtime](/docs/api-reference/edge-runtime.md) as [Middleware](/docs/middleware.md). Checkout [React 18 - Streaming](/docs/react-18/streaming.md) for more details.
+
+## React Server Components (Alpha)
+
+React Server Components is a new feature in React experimental release yet, which let you reduce your code bundle size by separating server and client side code as different kinds of components and streaming the server rendered result to client.
+
+It is still in research and development in React and Next.js provides it as an experimental feature in v12. Checkout [React 18 - Server Components](/docs/react-18/server-components.md) section for details.

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

@@ -0,0 +1,124 @@
+# React Server Components (Alpha)
+
+Server Components allow us to render React components on the server. This is fundamentally different from server-side rendering 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. Then, turn on the `concurrentFeatures` and `serverComponents` options in `next.config.js`:
+
+```jsx
+// next.config.js
+module.exports = {
+  experimental: {
+    concurrentFeatures: true,
+    serverComponents: true,
+  },
+}
+```
+
+Next, if you already have customized `pages/_document` component, you need to remove the `getInitialProps` static method and the `getServerSideProps` export if there’s any, otherwise it won't work with server components. If no custom Document component is provided, Next.js will fallback to a basic functional document component. Check [next/document support](#next/document) for more details.
+
+Then, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information.
+
+### Server Components Convention
+
+To run a component on the server, append `.server.js` to the end of the filename. For example `./pages/home.server.js` is a Server Component.
+
+For client components, add `.client.js`. 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 "universal component" 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 runtime. However `<Content>` will still be hydrated on the client-side, like normal React components.
+
+To see a full example, check out [link to the demo and repository](https://github.com/vercel/next-rsc-demo).
+
+## **Supported Next.js APIs**
+
+### `next/link` and `next/image`
+
+You could 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 custom `_document` To use server components you have to change your `_document` to a functional component like below. Or if you don't have any, Next.js will provide a functional fallback `_document` component.
+
+```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 use `_app.js`, the usage is same with [Custom App](/docs/advanced-features/custom-app).
+If you're use `_app.server.js` as a server component, the signature is changed as below where it only receive the `children` prop as element. You can surly 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
+
+Basic routes with path and queries, dynamic routes are supported as well. If you need to access the router in server components(`.server.js`), They will receive `router` instance as a prop so that you could directly accessing them without using `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 is still in the alpha stage, not all Next.js APIs are supported. The following Next.js APIs have limited functionality within Server Components. Note that React 18 without SSR streaming isn't affected.
+
+#### React internals
+
+Most of React hooks such as `useContext`, `useState`, `useReducer`, `useEffect` and `useLayoutEffect` are not supported as of today since Server Components are executed per requests and aren't stateful.
+
+#### Data Fetching & Styling
+
+Like streaming SSR, styling and data fetching within `Suspense` on 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're still working on them!

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

@@ -0,0 +1,62 @@
+# Streaming SSR (Alpha)
+
+React 18 will include architectural improvements to React server-side rendering (SSR) performance. This means you could use `Suspense` in your React components in streaming SSR mode and React will send render them and send through HTTP streams. React server components is also an experimental feature based on streaming. Next.js will also provide server components related features along with other streaming support through `next/streaming`.
+
+## Enable Streaming SSR
+
+To enable, use the experimental flag `concurrentFeatures: true`:
+
+```jsx
+// next.config.js
+module.exports = {
+  experimental: {
+    concurrentFeatures: true,
+  },
+}
+```
+
+## Streaming Features
+
+### next/dynamic
+
+Using Dynamic import on React components by `React.lazy` have better support in React 18. Previously Next.js support dynamic import internally without require `Suspense` or `React.lazy`, Now to embrace the official APIs on 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-based */}
+        <Content />
+      </Suspense>
+      <Suspense fallback={<Spinner />}>
+        <Profile />
+      </Suspense>
+      <Suspense fallback={<Spinner />}>
+        <Footer />
+      </Suspense>
+    </div>
+  )
+}
+```
+
+Checkout [next/streaming](/docs/api-reference/next/streaming.md) for more details for building Next.js apps in streaming SSR mode.
+
+## Notice
+
+#### Data Fetching
+
+Currently data fetching within suspense boundaries on server side is not fully supported, which could lead to mismatching between server and client. In the short-term, please don't put data fetching within suspense.
+
+#### Styling
+
+Styling your components with styled-jsx or CSS modules are not supported well in streaming SSR. We're still working on them.

docs/api-reference/next/streaming.md

@@ -0,0 +1,11 @@
+---
+description: Use streaming related APIs to build streaming SSR Next.js pages.
+---
+
+# next/streaming
+
+## unstable_useWebVitalsReport
+
+Next.js provides an App component level function `reportWebVitals` for tracking performance metrics, checkout [measuring-performance](docs/advanced-features/measuring-performance) for more details. With moving to streaming SSR, you might not be able to
+
+## unstable_useRefreshRoot