Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Server Components documentation. #40452

Merged
merged 2 commits into from Sep 12, 2022
Merged

Update Server Components documentation. #40452

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b61c41
Update server-components.md
leerob Sep 11, 2022
d7b8f5f
Update docs/advanced-features/react-18/server-components.md
leerob Sep 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
115 changes: 13 additions & 102 deletions docs/advanced-features/react-18/server-components.md
View file
Open in desktop
@@ -1,116 +1,27 @@
# React Server Components (RFC)

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.
React Server Components allow developers to build applications that span the server and client, combining the rich interactivity of client-side apps with the improved performance of traditional server rendering.

### Next Router and Layouts RFC
In an upcoming Next.js release, React and Next.js developers will be able to use Server Components inside the `app` directory as part of the changes outlined by the [Layouts RFC](https://nextjs.org/blog/layouts-rfc).

We are currently implementing the [Next.js Router and Layouts RFC](https://nextjs.org/blog/layouts-rfc).
## What are React Server Components?

The new Next.js router will be built on top of React 18 features, including React Server Components.
React Server Components improve the user experience of your application by pairing the best parts of server-rendering with client-side interactivity.

One of the biggest proposed changes is that, by default, files inside a new `app` directory will be rendered on the server as React Server Components.
With traditional React applications that are client-side only, developers often had to make tradeoffs between SEO and performance. Server Components enable developers to better leverage their server infrastructure and achieve great performance by default.

This will allow you to automatically adopt React Server Components when migrating from `pages` to `app`.
For example, large dependencies that previously would impact the JavaScript bundle size on the client can instead stay entirely on the server. By sending less JavaScript to the browser, the time to interactive for the page is decreased, leading to improved [Core Web Vitals](https://vercel.com/blog/core-web-vitals).

You can find more information on the [RFC](https://nextjs.org/blog/layouts-rfc) and we welcome your feedback on [Github Discussions](https://github.com/vercel/next.js/discussions/37136).
## React Server Components vs Server-Side Rendering

### Server Components Conventions
[Server-side Rendering](/docs/basic-features/pages.md#server-side-rendering) (SSR) dynamically builds your application into HTML on the server. This creates faster load times for users by offloading work from the user's device to the server, especially those with slower internet connections or older devices. However, developers still pay the cost to download, parse, and hydrate those components after the initial HTML loads.

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.
React Server Components, combined with Next.js server-side rendering, help eliminate the tradeoff of all-or-nothing data fetching. You can progressively show updates as your data comes in.

For client components, append `.client.js` to the filename. For example, `./components/avatar.client.js`.
## Using React Server Components with Next.js

Server components can import server components and client components.
The Next.js team at Vercel released the [Layouts RFC](https://nextjs.org/blog/layouts-rfc) a few months ago outlining the vision for the future of routing, layouts, and data fetching in the framework. These changes **aren't available yet**, but we can start learning about how they will be used.

Client components **cannot** import server components.
Pages and Layouts in `app` will be rendered as React Server Components by default. This improves performance by reducing the amount of JavaScript sent to the client for components that are not interactive. Client components will be able to be defined through either a file name extension or through a string literal in the file.

Components without a `server` or `client` extension will be treated as shared components and can be imported by server components and client components. 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 [vercel/next-react-server-components demo](https://github.com/vercel/next-react-server-components).

## 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`

The usage of `_app.js` is the same as [Custom App](/docs/advanced-features/custom-app). Using custom app as server component such as `_app.server.js` is not recommended, to keep align with non server components apps for client specific things like global CSS imports.

### 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.
We will be providing more updates about Server Components usage in Next.js soon.