From 4eeca9332bb42e571762404dce5dc3ae6eb25185 Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Tue, 1 Feb 2022 17:01:44 +0100 Subject: [PATCH 01/16] docs: react 18, streaming SSR, rsc with new apis --- docs/advanced-features/react-18.md | 154 ------------------ docs/advanced-features/react-18/basic.md | 25 +++ .../react-18/server-components.md | 124 ++++++++++++++ docs/advanced-features/react-18/streaming.md | 62 +++++++ docs/api-reference/next/streaming.md | 11 ++ docs/manifest.json | 15 +- 6 files changed, 236 insertions(+), 155 deletions(-) delete mode 100644 docs/advanced-features/react-18.md create mode 100644 docs/advanced-features/react-18/basic.md create mode 100644 docs/advanced-features/react-18/server-components.md create mode 100644 docs/advanced-features/react-18/streaming.md create mode 100644 docs/api-reference/next/streaming.md diff --git a/docs/advanced-features/react-18.md b/docs/advanced-features/react-18.md deleted file mode 100644 index 1d82c82b71b47..0000000000000 --- a/docs/advanced-features/react-18.md +++ /dev/null @@ -1,154 +0,0 @@ -# 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. - -### Enable SSR Streaming (Alpha) - -Concurrent features in React 18 include built-in support for server-side Suspense and SSR streaming support, allowing you to server-render pages using HTTP streaming. - -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). - -To enable, use the experimental flag `concurrentFeatures: true`: - -```jsx -// next.config.js -module.exports = { - experimental: { - concurrentFeatures: true, - }, -} -``` - -Once enabled, you can use Suspense and SSR streaming for all pages. This also means that you can use Suspense-based data-fetching, `next/dynamic`, and React's built-in `React.lazy` with Suspense boundaries. - -```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 ( -
- }> - {/* A component that uses Suspense-based */} - - - }> - - - }> -
- -
- ) -} -``` - -## React Server Components - -React Server Components allow us to render everything, including the components themselves, 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 (Alpha) - -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 default one like below. - -```jsx -// pages/_document.js -import { Html, Head, Main, NextScript } from 'next/document' - -export default function Document() { - return ( - - - -
- - - - ) -} -``` - -Then, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. - -### Server Components APIs (Alpha) - -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 ( -
-

Welcome to React Server Components

- - - - -
- ) -} -``` - -The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However `` 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` / `next/image` -- `next/document` / `next/app` -- Dynamic routing - -## **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 inside Server Components: - -- 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. -- `next/head` -- Partial: Note that Inside `.client.js` components `useRouter` is supported -- Styled JSX -- CSS Modules -- Next.js I18n -- `getInitialProps`, `getStaticProps` and `getStaticPaths` - -React 18 without SSR streaming isn't affected. diff --git a/docs/advanced-features/react-18/basic.md b/docs/advanced-features/react-18/basic.md new file mode 100644 index 0000000000000..4ed6648a1e00b --- /dev/null +++ b/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. diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md new file mode 100644 index 0000000000000..efe00c463ede9 --- /dev/null +++ b/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 ( +
+

Welcome to React Server Components

+ + + + +
+ ) +} +``` + +The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However `` 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 ( + + + +
+ + + + ) +} +``` + +### `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! diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md new file mode 100644 index 0000000000000..096c2e6465e34 --- /dev/null +++ b/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 ( +
+ }> + {/* A component that uses Suspense-based */} + + + }> + + + }> +
+ +
+ ) +} +``` + +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. diff --git a/docs/api-reference/next/streaming.md b/docs/api-reference/next/streaming.md new file mode 100644 index 0000000000000..926a3a09c61ef --- /dev/null +++ b/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 diff --git a/docs/manifest.json b/docs/manifest.json index 56886a0a60b53..4f67241d723c3 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -283,7 +283,20 @@ }, { "title": "React 18", - "path": "/docs/advanced-features/react-18.md" + "routes": [ + { + "title": "Basic", + "path": "/docs/advanced-features/react-18/basic.md" + }, + { + "title": "Streaming SSR", + "path": "/docs/advanced-features/react-18/streaming.md" + }, + { + "title": "React Server Components", + "path": "/docs/advanced-features/react-18/server-components.md" + } + ] } ] }, From a3343267a5ccbb407bd8139364239d90523d0c9f Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Fri, 4 Feb 2022 15:46:39 +0100 Subject: [PATCH 02/16] document next/streaming module --- docs/api-reference/next/streaming.md | 88 +++++++++++++++++++++++++++- docs/manifest.json | 4 ++ 2 files changed, 90 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/next/streaming.md b/docs/api-reference/next/streaming.md index 926a3a09c61ef..32142ee7e9ead 100644 --- a/docs/api-reference/next/streaming.md +++ b/docs/api-reference/next/streaming.md @@ -1,11 +1,95 @@ --- -description: Use streaming related APIs to build streaming SSR Next.js pages. +description: Streaming related APIs to build Next.js apps in streaming SSR or with React Server Components. --- # next/streaming +The `next/streaming` module provides streaming related APIs to port the existing functionality of Next.js app to streaming scenarios or assign users ability to interact much easier with React Server Components. + ## 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 +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 server components, you might have a pure server side custom `_app` component which doesn't run client effects. + +With this API, you're able to track web vitals metrics through this hook in client components. + +```jsx +// pages/_app.js +import { unstable_useWebVitalsReport } from 'next/streaming' + +export default function Home() { + unstable_useWebVitalsReport((data) => { + console.log(data) + }) + + return
Home Page
+} +``` + +Or it could also be an alternative way for you to replace static exported `reportWebVitals` function in your existing \_app. + +```jsx +// pages/_app.server.js +import Layout from '../components/layout.client.js' + +export default function App({ children }) { + return {children} +} +``` + +```jsx +// components/layout.client.js +import { unstable_useWebVitalsReport as useWebVitalsReport } from 'next/streaming' + +export default function Layout() { + useWebVitalsReport((data) => { + console.log(data) + }) + + return ( +
+

Hello

+
{children}
+
+ ) +} +``` ## unstable_useRefreshRoot + +Since server components are rendered on server side when requesting to server, in some case you might need to partially refresh server rendered content. + +For instance, you build a search bar in client component and display few search results by server components, you'd like to update the search results while typing. Then you'd like to re-render the results list in a certain frequency, it could be each typing, or be batched by debounce. + +The hook `unstable_useRefreshRoot` returns a `refresh` API to let you rerender the React tree smoothly without flicking. This is only allowed to be used on client side and will only effect server components so far. + +```jsx +// pages/index.server.js +import Search from '../components/search.client.js' +import SearchResults from '../components/search-results.server.js' + +function Home() { + return ( +
+ + +
+ ) +} +``` + +```jsx +// components/search.client.js +import { unstable_useRefreshRoot as useRefreshRoot } from 'next/streaming' + +export default function Search() { + const refresh = useRefreshRoot() + + return ( + { + refresh() + }} + /> + ) +} +``` diff --git a/docs/manifest.json b/docs/manifest.json index 4f67241d723c3..c635c73c565d8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -365,6 +365,10 @@ "title": "next/server", "path": "/docs/api-reference/next/server.md" }, + { + "title": "next/streaming", + "path": "/docs/api-reference/next/streaming.md" + }, { "title": "Edge Runtime", "path": "/docs/api-reference/edge-runtime.md" From 239201357396a47bceebd9469aa8f08a6fa05719 Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Fri, 4 Feb 2022 16:02:30 +0100 Subject: [PATCH 03/16] fix typos and update link --- docs/advanced-features/react-18/basic.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced-features/react-18/basic.md b/docs/advanced-features/react-18/basic.md index 4ed6648a1e00b..35cfeaaf837ed 100644 --- a/docs/advanced-features/react-18/basic.md +++ b/docs/advanced-features/react-18/basic.md @@ -2,7 +2,7 @@ [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 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://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html). ## React 18 Usage in Next.js @@ -20,6 +20,6 @@ This is an experimental feature in Next.js 12, but once enabled, SSR will use th ## 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. +React Server Components is a new feature in React experimental release, which lets 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. From d17ef8cd335515d4afead9379343f28a9ee4f428 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Sat, 5 Feb 2022 09:52:59 -0600 Subject: [PATCH 04/16] Apply suggestions from code review Co-authored-by: Kara Co-authored-by: Alexander Kachkaev --- docs/advanced-features/react-18/basic.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/advanced-features/react-18/basic.md b/docs/advanced-features/react-18/basic.md index 35cfeaaf837ed..cb6d49f78bd16 100644 --- a/docs/advanced-features/react-18/basic.md +++ b/docs/advanced-features/react-18/basic.md @@ -1,25 +1,27 @@ # 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](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://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html). +React 18 is in RC now. 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). -## React 18 Usage in Next.js +## Using React 18 with Next.js -Ensure you have the `rc` npm tag of React installed: +Install the Release Candidate version of React 18: ```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. +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. +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) -React Server Components is a new feature in React experimental release, which lets 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. +Server Components are a new feature in React that lets 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. -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. +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. From 26c87470b9cbf0a2b1b8d7900bad8391e7f3a7f5 Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Mon, 7 Feb 2022 14:38:47 +0100 Subject: [PATCH 05/16] Apply suggestions from code review Co-authored-by: Kara Co-authored-by: Alexander Kachkaev --- .../react-18/server-components.md | 24 +++++++++---------- docs/advanced-features/react-18/streaming.md | 14 +++++------ docs/api-reference/next/streaming.md | 12 +++++----- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index efe00c463ede9..c40d22527c8e1 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -1,6 +1,6 @@ # 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. +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 @@ -20,13 +20,13 @@ Next, if you already have customized `pages/_document` component, you need to re Then, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. -### Server Components Convention +### 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` is a Server Component. +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, add `.client.js`. For example, `./components/avatar.client.js`. +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 "universal component" and can be used and rendered by both sides, depending on where it is imported. For example: +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 components" and can be used and rendered by both sides, depending on where it is imported. For example: ```jsx // pages/home.server.js @@ -49,19 +49,19 @@ export default function Home() { } ``` -The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However `` will still be hydrated on the client-side, like normal React components. +The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However, `` 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** +## 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. +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 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. +If you have custom `_document`, you have to change your `_document` to a functional component like below to use server components. Or if you don't have any, Next.js will provide a functional fallback `_document` component. ```jsx // pages/_document.js @@ -82,8 +82,8 @@ export default function Document() { ### `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. +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, the signature is changed as below where it only receives the `children` prop as elements. You can wrap any other client or server components around `children` to customize the layout of your app. ```js // pages/_app.server.js @@ -105,7 +105,7 @@ export default function Index({ router }) { } ``` -### **Unsupported Next.js APIs** +### 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. diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index 096c2e6465e34..97cdf0ba3ebf5 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -4,7 +4,7 @@ React 18 will include architectural improvements to React server-side rendering ## Enable Streaming SSR -To enable, use the experimental flag `concurrentFeatures: true`: +To enable streaming, use the experimental flag `concurrentFeatures: true`: ```jsx // next.config.js @@ -19,7 +19,7 @@ module.exports = { ### 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`. +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' @@ -35,7 +35,7 @@ export default function Home() { return (
}> - {/* A component that uses Suspense-based */} + {/* A component that uses Suspense */} }> @@ -49,14 +49,14 @@ export default function Home() { } ``` -Checkout [next/streaming](/docs/api-reference/next/streaming.md) for more details for building Next.js apps in streaming SSR mode. +Check out [next/streaming](/docs/api-reference/next/streaming.md) for more details for building Next.js apps in streaming SSR mode. -## Notice +## Important Notes #### 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. +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 -Styling your components with styled-jsx or CSS modules are not supported well in streaming SSR. We're still working on them. +The Next.js team is still working on support for styled-jsx and CSS modules in streaming SSR. Please stay tuned for updates! diff --git a/docs/api-reference/next/streaming.md b/docs/api-reference/next/streaming.md index 32142ee7e9ead..b690b68ec6afd 100644 --- a/docs/api-reference/next/streaming.md +++ b/docs/api-reference/next/streaming.md @@ -4,13 +4,13 @@ description: Streaming related APIs to build Next.js apps in streaming SSR or wi # next/streaming -The `next/streaming` module provides streaming related APIs to port the existing functionality of Next.js app to streaming scenarios or assign users ability to interact much easier with React Server Components. +The experimental `next/streaming` module provides streaming related APIs to port the existing functionality of Next.js apps to streaming scenarios and facilitate the usage of React Server Components. ## 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 server components, you might have a pure server side custom `_app` component which doesn't run client effects. -With this API, you're able to track web vitals metrics through this hook in client components. +With the new `unstable_useWebVitalsReport` API, you're able to track web vitals metrics in client components. ```jsx // pages/_app.js @@ -25,7 +25,7 @@ export default function Home() { } ``` -Or it could also be an alternative way for you to replace static exported `reportWebVitals` function in your existing \_app. +This method could also be used to replace static exported `reportWebVitals` functions in your existing `_app`. ```jsx // pages/_app.server.js @@ -56,11 +56,11 @@ export default function Layout() { ## unstable_useRefreshRoot -Since server components are rendered on server side when requesting to server, in some case you might need to partially refresh server rendered content. +Since server components are rendered on the server side when requesting to server, in some cases you might need to partially refresh server rendered content. -For instance, you build a search bar in client component and display few search results by server components, you'd like to update the search results while typing. Then you'd like to re-render the results list in a certain frequency, it could be each typing, or be batched by debounce. +For instance, let's say you build a search bar in a client component and display search results through server components. You'd want to update the search results while typing and re-render the results list with a certain frequency (e.g. with each keystroke or on a debounce). -The hook `unstable_useRefreshRoot` returns a `refresh` API to let you rerender the React tree smoothly without flicking. This is only allowed to be used on client side and will only effect server components so far. +The `unstable_useRefreshRoot` hook returns a `refresh` API to let you re-render the React tree smoothly without flickering. This is only allowed to be used on the client side and will only affect server components at the moment. ```jsx // pages/index.server.js From 3c8e77042c32dafa1fae0f9281b9757335d19a0c Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Mon, 7 Feb 2022 15:17:32 +0100 Subject: [PATCH 06/16] add more streaming intro --- docs/advanced-features/react-18/server-components.md | 8 +++++--- docs/advanced-features/react-18/streaming.md | 7 +++++-- docs/api-reference/next/streaming.md | 2 +- 3 files changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index c40d22527c8e1..ac4f71d0b1894 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -16,9 +16,9 @@ module.exports = { } ``` -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. +Next, if you already have a customized `pages/_document` component. If no custom Document component is provided, Next.js will fallback to a basic functional document component. Take a look at [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. +Once you've made these changes, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. ### Server Components Conventions @@ -51,7 +51,9 @@ export default function Home() { The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However, `` 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). +> Notice that make sure you're using default imports for server and client components at the moment. The the support of named exports are working in progress! + +To see a full example, check out the [vercel/next-rsc-demo demo](https://github.com/vercel/next-rsc-demo). ## Supported Next.js APIs diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index 97cdf0ba3ebf5..bfee7100713a1 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -1,10 +1,13 @@ # 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`. +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 like [`next/streaming`](docs/api-reference/next/streaming.md). However, this guide focuses on basic React 18 streaming. ## Enable Streaming SSR -To enable streaming, use the experimental flag `concurrentFeatures: true`: +Enabling streaming SSR means React renders your components into streams and client continues receiving the updating fragments from server, which lets you start emitting the HTML as early as possible. You can break down your app into few smaller independent units by `Suspense`. The client will use selective hydration strategy to prioritize the components hydration which lets users interact with the them efficiently. + +To enable streaming SSR, set the experimental flag `concurrentFeatures` to `true`: ```jsx // next.config.js diff --git a/docs/api-reference/next/streaming.md b/docs/api-reference/next/streaming.md index b690b68ec6afd..8b484cfc3bd68 100644 --- a/docs/api-reference/next/streaming.md +++ b/docs/api-reference/next/streaming.md @@ -8,7 +8,7 @@ The experimental `next/streaming` module provides streaming related APIs to port ## 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 server components, you might have a pure server side custom `_app` component which doesn't run client effects. +Next.js provides an `_app` component level function, [`reportWebVitals`](docs/advanced-features/measuring-performance), for tracking performance metrics. With server components, you may have a pure server-side custom `_app` component which doesn't run client effects, so this existing API won't work. With the new `unstable_useWebVitalsReport` API, you're able to track web vitals metrics in client components. From 3c1a31d2a81de5112457e886fa3def3fab23d175 Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Mon, 7 Feb 2022 15:26:49 +0100 Subject: [PATCH 07/16] Notes for next head and script --- docs/advanced-features/react-18/streaming.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index bfee7100713a1..63b2a7d8c0bb8 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -56,6 +56,10 @@ Check out [next/streaming](/docs/api-reference/next/streaming.md) for more detai ## Important Notes +#### `next/head` and `next/script` + +Using resource tags in `next/head` won't work, and `next/script` instances with `beforeInteractive` will need to be in the `_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`. From 4e002ee22a0c34d790dabe60c24edb44b0274604 Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Tue, 8 Feb 2022 12:10:18 +0100 Subject: [PATCH 08/16] Apply suggestions from code review Co-authored-by: Kara --- docs/advanced-features/react-18/basic.md | 2 +- .../react-18/server-components.md | 15 +++++++-------- docs/advanced-features/react-18/streaming.md | 6 +++--- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/advanced-features/react-18/basic.md b/docs/advanced-features/react-18/basic.md index cb6d49f78bd16..02b405acdffc9 100644 --- a/docs/advanced-features/react-18/basic.md +++ b/docs/advanced-features/react-18/basic.md @@ -22,6 +22,6 @@ Streaming server-rendering (SSR) is an experimental feature in Next.js 12. When ## React Server Components (Alpha) -Server Components are a new feature in React that lets 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 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. diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index ac4f71d0b1894..5da0e61571305 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -16,9 +16,8 @@ module.exports = { } ``` -Next, if you already have a customized `pages/_document` component. If no custom Document component is provided, Next.js will fallback to a basic functional document component. Take a look at [next/document support](#next/document) for more details. -Once you've made these changes, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. +Once you've made this change, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. ### Server Components Conventions @@ -51,7 +50,7 @@ export default function Home() { The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However, `` will still be hydrated on the client-side, like normal React components. -> Notice that make sure you're using default imports for server and client components at the moment. The the support of named exports are working in progress! +> Make sure you're using default imports for server and client components. The support of named exports are a work in progress! To see a full example, check out the [vercel/next-rsc-demo demo](https://github.com/vercel/next-rsc-demo). @@ -63,7 +62,7 @@ You can use `next/link` and `next/image` like before and they will be treated as ### `next/document` -If you have custom `_document`, you have to change your `_document` to a functional component like below to use server components. Or if you don't have any, Next.js will provide a functional fallback `_document` component. +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 provide a functional fallback `_document` component for you. ```jsx // pages/_document.js @@ -96,7 +95,7 @@ export default function App({ 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. +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 @@ -109,15 +108,15 @@ export default function Index({ router }) { ### 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. +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. Note that React 18 use 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. +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 server side are not well supported. We're still working on them. +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. diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index 63b2a7d8c0bb8..0ba5555bdd6ff 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -1,11 +1,11 @@ # 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 like [`next/streaming`](docs/api-reference/next/streaming.md). However, this guide focuses on basic React 18 streaming. +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 client continues receiving the updating fragments from server, which lets you start emitting the HTML as early as possible. You can break down your app into few smaller independent units by `Suspense`. The client will use selective hydration strategy to prioritize the components hydration which lets users interact with the them efficiently. +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 flag `concurrentFeatures` to `true`: @@ -58,7 +58,7 @@ Check out [next/streaming](/docs/api-reference/next/streaming.md) for more detai #### `next/head` and `next/script` -Using resource tags in `next/head` won't work, and `next/script` instances with `beforeInteractive` will need to be in the `_document`. +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. For this reason, we suggest moving resource tags to `next/script` with the `afterInteractive` or `lazyOnload` strategy, or the `_document`. For similar reasons, we suggest migrating `next/script` instances with the `beforeInteractive` strategy to the `_document` as well. #### Data Fetching From 59abdbb74890fca5f3adeb54f04784a428101e7f Mon Sep 17 00:00:00 2001 From: Shu Ding Date: Tue, 8 Feb 2022 18:50:24 +0100 Subject: [PATCH 09/16] update docs for the new runtime experimental option --- docs/advanced-features/react-18/server-components.md | 5 +++-- docs/advanced-features/react-18/streaming.md | 10 ++++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index 5da0e61571305..34c9ce0d4dae7 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -4,18 +4,19 @@ Server Components allow us to render React components on the server. This is fun ### 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`: +To use React Server Components, ensure you have React 18 installed. Then enable the `serverComponents` option and specify the global `runtime` (can be either `'nodejs'` or `'edge'`) in `next.config.js`: ```jsx // next.config.js module.exports = { experimental: { - concurrentFeatures: true, + runtime: 'nodejs', serverComponents: true, }, } ``` +Note that the `runtime` option also enables [Streaming SSR](/docs/advanced-features/react-18/streaming). When setting to `'edge'`, the server will be running entirely in the [Edge Runtime](https://nextjs.org/docs/api-reference/edge-runtime). Once you've made this change, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index 0ba5555bdd6ff..e80ccf631586f 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -5,19 +5,21 @@ It's worth noting that another experimental feature, React Server Components, is ## 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. +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 flag `concurrentFeatures` to `true`: +To enable streaming SSR, set the experimental option `runtime` to either `'nodejs'` or `'edge'`: ```jsx // next.config.js module.exports = { experimental: { - concurrentFeatures: true, + runtime: 'nodejs', }, } ``` +This option determines the environment that 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 @@ -58,7 +60,7 @@ Check out [next/streaming](/docs/api-reference/next/streaming.md) for more detai #### `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. For this reason, we suggest moving resource tags to `next/script` with the `afterInteractive` or `lazyOnload` strategy, or the `_document`. For similar reasons, we suggest migrating `next/script` instances with the `beforeInteractive` strategy to the `_document` as well. +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. For this reason, we suggest moving resource tags to `next/script` with the `afterInteractive` or `lazyOnload` strategy, or the `_document`. For similar reasons, we suggest migrating `next/script` instances with the `beforeInteractive` strategy to the `_document` as well. #### Data Fetching From 0e28d1045368bee8848b3fec548f9ffeabf1593f Mon Sep 17 00:00:00 2001 From: Shu Ding Date: Tue, 8 Feb 2022 18:57:53 +0100 Subject: [PATCH 10/16] Update docs/advanced-features/react-18/streaming.md Co-authored-by: Kara --- docs/advanced-features/react-18/streaming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index e80ccf631586f..42c0ae39daf4e 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -18,7 +18,7 @@ module.exports = { } ``` -This option determines the environment that 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). +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 From b34441f35c8bea40ce4c3c395a05cad81167f033 Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Tue, 8 Feb 2022 20:23:25 +0100 Subject: [PATCH 11/16] Update docs/advanced-features/react-18/server-components.md --- docs/advanced-features/react-18/server-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index 34c9ce0d4dae7..f86a3452b662f 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -51,7 +51,7 @@ export default function Home() { The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However, `` will still be hydrated on the client-side, like normal React components. -> Make sure you're using default imports for server and client components. The support of named exports are a work in progress! +> 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 [vercel/next-rsc-demo demo](https://github.com/vercel/next-rsc-demo). From d914e36803e407607b5aa6ba6d9076138d273b1d Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Mon, 14 Feb 2022 22:48:18 +0100 Subject: [PATCH 12/16] Apply suggestions from code review Co-authored-by: Lee Robinson --- docs/advanced-features/react-18/basic.md | 4 ++-- docs/advanced-features/react-18/server-components.md | 11 +++++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/advanced-features/react-18/basic.md b/docs/advanced-features/react-18/basic.md index 02b405acdffc9..5e60ad6d37ad8 100644 --- a/docs/advanced-features/react-18/basic.md +++ b/docs/advanced-features/react-18/basic.md @@ -2,11 +2,11 @@ [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://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). +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 Release Candidate version of React 18: +Install the RC version of React 18: ```jsx npm install next@latest react@rc react-dom@rc diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index f86a3452b662f..50892287fbacd 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -4,7 +4,10 @@ Server Components allow us to render React components on the server. This is fun ### Enable React Server Components -To use React Server Components, ensure you have React 18 installed. Then enable the `serverComponents` option and specify the global `runtime` (can be either `'nodejs'` or `'edge'`) in `next.config.js`: +To use React Server Components, ensure you have React 18 installed. + +```jsx +npm install next@latest react@rc react-dom@rc ```jsx // next.config.js @@ -16,9 +19,9 @@ module.exports = { } ``` -Note that the `runtime` option also enables [Streaming SSR](/docs/advanced-features/react-18/streaming). When setting to `'edge'`, the server will be running entirely in the [Edge Runtime](https://nextjs.org/docs/api-reference/edge-runtime). +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). -Once you've made this change, you can start using React Server Components. [See our example](https://github.com/vercel/next-rsc-demo) for more information. +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 @@ -49,7 +52,7 @@ export default function Home() { } ``` -The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client runtime. However, `` will still be hydrated on the client-side, like normal React components. +The `` and `` components will always be server-side rendered and streamed to the client, and will not be included by the client-side JavaScript. However, `` 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! From b7997f872185de63597f4a0d375e9e17abf47b8c Mon Sep 17 00:00:00 2001 From: Jiachi Liu Date: Mon, 14 Feb 2022 22:51:12 +0100 Subject: [PATCH 13/16] update manifest, link streaming api along with react 18 api --- .../react-18/{basic.md => overview.md} | 1 + docs/manifest.json | 10 ++++++++-- 2 files changed, 9 insertions(+), 2 deletions(-) rename docs/advanced-features/react-18/{basic.md => overview.md} (92%) diff --git a/docs/advanced-features/react-18/basic.md b/docs/advanced-features/react-18/overview.md similarity index 92% rename from docs/advanced-features/react-18/basic.md rename to docs/advanced-features/react-18/overview.md index 5e60ad6d37ad8..2df4aa92b3b0b 100644 --- a/docs/advanced-features/react-18/basic.md +++ b/docs/advanced-features/react-18/overview.md @@ -1,6 +1,7 @@ # 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). diff --git a/docs/manifest.json b/docs/manifest.json index c635c73c565d8..ef7d33ce98496 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -285,8 +285,14 @@ "title": "React 18", "routes": [ { - "title": "Basic", - "path": "/docs/advanced-features/react-18/basic.md" + "path": "/docs/advanced-features/react-18", + "redirect": { + "destination": "/docs/advanced-features/react-18/overview" + } + }, + { + "title": "Overview", + "path": "/docs/advanced-features/react-18/overview.md" }, { "title": "Streaming SSR", From a3be20dabcc5d70450ece8cac81830f85310d4f9 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Tue, 15 Feb 2022 20:13:01 -0700 Subject: [PATCH 14/16] Apply suggestions from code review --- docs/advanced-features/react-18/server-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index 50892287fbacd..c24495040a29b 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -4,7 +4,7 @@ Server Components allow us to render React components on the server. This is fun ### Enable React Server Components -To use React Server Components, ensure you have React 18 installed. +To use React Server Components, ensure you have React 18 installed: ```jsx npm install next@latest react@rc react-dom@rc From 24f2e2b3eb5f50bc3fe78d28b149da28332e8701 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Tue, 15 Feb 2022 20:26:46 -0700 Subject: [PATCH 15/16] Apply suggestions from code review --- .../react-18/server-components.md | 10 +++++----- docs/advanced-features/react-18/streaming.md | 6 +++--- docs/api-reference/next/streaming.md | 16 ++++++++-------- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index c24495040a29b..b30a7fb47c7a1 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -56,7 +56,7 @@ The `` and `` components will always be server-side rendered and > 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 [vercel/next-rsc-demo demo](https://github.com/vercel/next-rsc-demo). +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 @@ -66,7 +66,7 @@ You can use `next/link` and `next/image` like before and they will be treated as ### `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 provide a functional fallback `_document` component for you. +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 @@ -88,7 +88,7 @@ export default function Document() { ### `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, the signature is changed as below where it only receives the `children` prop as elements. You can wrap any other client or server components around `children` to customize the layout of your 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 @@ -112,7 +112,7 @@ export default function Index({ router }) { ### 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. Note that React 18 use without SSR streaming isn't affected. +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 @@ -126,4 +126,4 @@ Page level exported methods like `getInitialProps`, `getStaticProps` and `getSta #### `next/head` and I18n -We're still working on them! +We are still working on support for these features. diff --git a/docs/advanced-features/react-18/streaming.md b/docs/advanced-features/react-18/streaming.md index 42c0ae39daf4e..544759b3daa66 100644 --- a/docs/advanced-features/react-18/streaming.md +++ b/docs/advanced-features/react-18/streaming.md @@ -54,13 +54,13 @@ export default function Home() { } ``` -Check out [next/streaming](/docs/api-reference/next/streaming.md) for more details for building Next.js apps in streaming SSR mode. +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. For this reason, we suggest moving resource tags to `next/script` with the `afterInteractive` or `lazyOnload` strategy, or the `_document`. For similar reasons, we suggest migrating `next/script` instances with the `beforeInteractive` strategy to the `_document` as well. +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 @@ -68,4 +68,4 @@ Currently, data fetching within `Suspense` boundaries on the server side is not #### Styling -The Next.js team is still working on support for styled-jsx and CSS modules in streaming SSR. Please stay tuned for updates! +The Next.js team is working on support for `styled-jsx` and CSS modules in streaming SSR. Stay tuned for updates. diff --git a/docs/api-reference/next/streaming.md b/docs/api-reference/next/streaming.md index 8b484cfc3bd68..210b18c48df36 100644 --- a/docs/api-reference/next/streaming.md +++ b/docs/api-reference/next/streaming.md @@ -8,9 +8,9 @@ The experimental `next/streaming` module provides streaming related APIs to port ## unstable_useWebVitalsReport -Next.js provides an `_app` component level function, [`reportWebVitals`](docs/advanced-features/measuring-performance), for tracking performance metrics. With server components, you may have a pure server-side custom `_app` component which doesn't run client effects, so this existing API won't work. +Next.js provides an `_app` component-level function, [`reportWebVitals`](docs/advanced-features/measuring-performance), for tracking performance metrics. With Server Components, you may have a pure server-side custom `_app` component (which doesn't run client effects) so the existing API won't work. -With the new `unstable_useWebVitalsReport` API, you're able to track web vitals metrics in client components. +With the new `unstable_useWebVitalsReport` API, you're able to track [Core Web Vitals](https://nextjs.org/learn/seo/web-performance) in client components: ```jsx // pages/_app.js @@ -25,7 +25,7 @@ export default function Home() { } ``` -This method could also be used to replace static exported `reportWebVitals` functions in your existing `_app`. +This method could also be used to replace statically exported `reportWebVitals` functions in your existing `_app`: ```jsx // pages/_app.server.js @@ -38,10 +38,10 @@ export default function App({ children }) { ```jsx // components/layout.client.js -import { unstable_useWebVitalsReport as useWebVitalsReport } from 'next/streaming' +import { unstable_useWebVitalsReport } from 'next/streaming' export default function Layout() { - useWebVitalsReport((data) => { + unstable_useWebVitalsReport((data) => { console.log(data) }) @@ -56,11 +56,11 @@ export default function Layout() { ## unstable_useRefreshRoot -Since server components are rendered on the server side when requesting to server, in some cases you might need to partially refresh server rendered content. +Since Server Components are rendered on the server-side, in some cases you might need to partially refresh content from the server. -For instance, let's say you build a search bar in a client component and display search results through server components. You'd want to update the search results while typing and re-render the results list with a certain frequency (e.g. with each keystroke or on a debounce). +For example, a search bar (client component) which displays search results as server components. You'd want to update the search results while typing and rerender the results list with a certain frequency (e.g. with each keystroke or on a debounce). -The `unstable_useRefreshRoot` hook returns a `refresh` API to let you re-render the React tree smoothly without flickering. This is only allowed to be used on the client side and will only affect server components at the moment. +The `unstable_useRefreshRoot` hook returns a `refresh` API to let you re-render the React tree smoothly without flickering. This is only allowed for use on the client-side and will only affect Server Components at the moment. ```jsx // pages/index.server.js From f5c87e7fc940a26ffa5b9422aeadb3ec7ea8b138 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Tue, 15 Feb 2022 21:58:00 -0600 Subject: [PATCH 16/16] Update server-components.md --- docs/advanced-features/react-18/server-components.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/advanced-features/react-18/server-components.md b/docs/advanced-features/react-18/server-components.md index b30a7fb47c7a1..940c0c4755fb3 100644 --- a/docs/advanced-features/react-18/server-components.md +++ b/docs/advanced-features/react-18/server-components.md @@ -8,6 +8,9 @@ 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 @@ -29,7 +32,7 @@ To run a component on the server, append `.server.js` to the end of the filename 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 "universal components" and can be used and rendered by both sides, depending on where it is imported. For example: +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