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.

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

docs: Rewrite Rendering Section and React Essentials Page #51579

Merged
merged 74 commits into from
Aug 24, 2023
Merged
Show file tree
Hide file tree
Changes from 71 commits
Commits
Show all changes
74 commits
Select commit Hold shift + click to select a range
8df9c9d
Recommend foundations course for beginners
delbaoliveira Jun 20, 2023
a21c723
Tentative outline
delbaoliveira Jun 20, 2023
85e4be8
Add RSC page intro
delbaoliveira Jun 20, 2023
3d02944
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Jun 20, 2023
cefc3a9
No code in page titles
delbaoliveira Jun 20, 2023
a2b145d
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Jul 6, 2023
b0c0d66
Brain dump: foundational concepts
delbaoliveira Jul 7, 2023
c060938
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 1, 2023
e180bd0
Change of plans - remove react essentials pages
delbaoliveira Aug 1, 2023
58b9f39
Swap static/dynamic and components page
delbaoliveira Aug 1, 2023
acb9351
Write fundamentals introduction
delbaoliveira Aug 1, 2023
6aba8b8
Write about react rendering environments
delbaoliveira Aug 1, 2023
5e9ad99
Write about Next.js runtimes
delbaoliveira Aug 1, 2023
779a081
Write about rendering strategies
delbaoliveira Aug 1, 2023
1e153d6
Write about the request-response lifecycle
delbaoliveira Aug 1, 2023
4a2b148
Write about the network boundary
delbaoliveira Aug 1, 2023
bb23c01
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 1, 2023
7d541ad
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 2, 2023
d6de31d
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 4, 2023
bfe05da
Move patterns to their own page
delbaoliveira Aug 4, 2023
48f5706
Clean and reshuffle
delbaoliveira Aug 4, 2023
60ded00
Review fundamentals
delbaoliveira Aug 4, 2023
f4da64a
Review fundamentals page
delbaoliveira Aug 7, 2023
d3b6073
hm, not quite there yet
delbaoliveira Aug 7, 2023
e371156
Write about the benefits / use cases for server rendering
delbaoliveira Aug 7, 2023
fa30c9d
Misc
delbaoliveira Aug 7, 2023
db453f1
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 7, 2023
1f8ccc6
Write about using server components in Next.js
delbaoliveira Aug 8, 2023
f55e733
Update docs/02-app/01-building-your-application/03-rendering/index.mdx
delbaoliveira Aug 8, 2023
e857950
Move sections and delete React essentials page
delbaoliveira Aug 8, 2023
f8b2107
Write about building hybrid applications
delbaoliveira Aug 8, 2023
de081b6
Misc
delbaoliveira Aug 8, 2023
d39ce58
Write about how Server Components are rendered
delbaoliveira Aug 8, 2023
505e42a
Add note about data cache being separate from static rendering
delbaoliveira Aug 8, 2023
bccee54
Write client-side rendering outline
delbaoliveira Aug 8, 2023
a894cd6
Merge branch 'docs-react-essentials-revamp' of https://github.com/ver…
delbaoliveira Aug 8, 2023
225477c
Review
delbaoliveira Aug 9, 2023
7ca1f57
Write about streaming
delbaoliveira Aug 9, 2023
962a88c
Client rendering outline + use cases
delbaoliveira Aug 9, 2023
0f2d3a2
Write about "use client"
delbaoliveira Aug 11, 2023
51345c6
Discuss how client components are rendered for initial visit
delbaoliveira Aug 11, 2023
f58cf84
Write about switching back to the server environment
delbaoliveira Aug 11, 2023
5772dec
Update docs/02-app/01-building-your-application/03-rendering/02-clien…
delbaoliveira Aug 11, 2023
edd62b5
Rewrite composition patterns
delbaoliveira Aug 11, 2023
c35d708
Merge branch 'docs-react-essentials-revamp' of https://github.com/ver…
delbaoliveira Aug 11, 2023
013c765
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 11, 2023
64c5ccf
Rename SSR and CSR pages
delbaoliveira Aug 17, 2023
b8c9e85
Rewrite Server Components page
delbaoliveira Aug 17, 2023
cbd9341
Rewrite Client Components page
delbaoliveira Aug 17, 2023
a3df58c
Review composition patterns page
delbaoliveira Aug 17, 2023
12acb6c
Fix some broken links
delbaoliveira Aug 17, 2023
bb0b589
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 17, 2023
fd93a81
💅🏼
delbaoliveira Aug 17, 2023
842e1ec
Remove inaccurate information
delbaoliveira Aug 17, 2023
c2739f5
Fix some broken links
delbaoliveira Aug 17, 2023
6cbf13c
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 17, 2023
d2514d3
Fix more broken links
delbaoliveira Aug 17, 2023
8c99b43
Merge branch 'docs-react-essentials-revamp' of https://github.com/ver…
delbaoliveira Aug 17, 2023
01b9205
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 21, 2023
5362ef5
Update broken links
delbaoliveira Aug 21, 2023
1e9b673
More broken links
delbaoliveira Aug 21, 2023
37d6ce8
Review interleaving client and server components section
delbaoliveira Aug 21, 2023
a94e845
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 21, 2023
bbdbbb9
Remove mention of Date not being serializable
delbaoliveira Aug 21, 2023
de1e03e
Merge branch 'docs-react-essentials-revamp' of https://github.com/ver…
delbaoliveira Aug 21, 2023
2a53544
Update docs/02-app/01-building-your-application/03-rendering/01-serve…
delbaoliveira Aug 21, 2023
a399b52
Apply suggestions from code review
delbaoliveira Aug 22, 2023
1c270ad
Update docs/02-app/01-building-your-application/03-rendering/03-compo…
delbaoliveira Aug 22, 2023
9dd27e0
Apply Michael's feedback
delbaoliveira Aug 23, 2023
8e4836d
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 23, 2023
abff487
Update diagram placeholders
delbaoliveira Aug 24, 2023
92b9a87
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 24, 2023
b768c89
Update broken link from merging into canary
delbaoliveira Aug 24, 2023
866cbcf
Merge branch 'canary' into docs-react-essentials-revamp
delbaoliveira Aug 24, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
863 changes: 0 additions & 863 deletions docs/01-getting-started/03-react-essentials.mdx

This file was deleted.

8 changes: 0 additions & 8 deletions docs/01-getting-started/index.mdx

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ export default function Page() {
> - A page is always the [leaf](/docs/app/building-your-application/routing#terminology) of the [route subtree](/docs/app/building-your-application/routing#terminology).
> - `.js`, `.jsx`, or `.tsx` file extensions can be used for Pages.
> - A `page.js` file is required to make a route segment publicly accessible.
> - Pages are [Server Components](/docs/getting-started/react-essentials) by default but can be set to a [Client Component](/docs/getting-started/react-essentials#client-components).
> - Pages are [Server Components](/docs/app/building-your-application/rendering/server-components) by default but can be set to a [Client Component](/docs/app/building-your-application/rendering/client-components).
> - Pages can fetch data. View the [Data Fetching](/docs/app/building-your-application/data-fetching) section for more information.

## Layouts
Expand Down Expand Up @@ -109,7 +109,7 @@ export default function DashboardLayout({
> - Any route segment can optionally define its own [Layout](#nesting-layouts). These layouts will be shared across all pages in that segment.
> - Layouts in a route are **nested** by default. Each parent layout wraps child layouts below it using the React `children` prop.
> - You can use [Route Groups](/docs/app/building-your-application/routing/route-groups) to opt specific route segments in and out of shared layouts.
> - Layouts are [Server Components](/docs/getting-started/react-essentials) by default but can be set to a [Client Component](/docs/getting-started/react-essentials#client-components).
> - Layouts are [Server Components](/docs/app/building-your-application/rendering/server-components) by default but can be set to a [Client Component](/docs/app/building-your-application/rendering/client-components).
> - Layouts can fetch data. View the [Data Fetching](/docs/app/building-your-application/data-fetching) section for more information.
> - Passing data between a parent layout and its children is not possible. However, you can fetch the same data in a route more than once, and React will [automatically dedupe the requests](/docs/app/building-your-application/caching#request-memoization) without affecting performance.
> - Layouts do not have access to the current route segment(s). To access route segments, you can use [`useSelectedLayoutSegment`](/docs/app/api-reference/functions/use-selected-layout-segment) or [`useSelectedLayoutSegments`](/docs/app/api-reference/functions/use-selected-layout-segments) in a Client Component.
Expand Down Expand Up @@ -150,7 +150,7 @@ export default function RootLayout({ children }) {
> - The root layout must define `<html>` and `<body>` tags since Next.js does not automatically create them.
> - You can use the [built-in SEO support](/docs/app/building-your-application/optimizing/metadata) to manage `<head>` HTML elements, for example, the `<title>` element.
> - You can use [route groups](/docs/app/building-your-application/routing/route-groups) to create multiple root layouts. See an [example here](/docs/app/building-your-application/routing/route-groups#creating-multiple-root-layouts).
> - The root layout is a [Server Component](/docs/getting-started/react-essentials) by default and **can not** be set to a [Client Component](/docs/getting-started/react-essentials#client-components).
> - The root layout is a [Server Component](/docs/app/building-your-application/rendering/server-components) by default and **can not** be set to a [Client Component](/docs/app/building-your-application/rendering/client-components).

> **Migrating from the `pages` directory:** The root layout replaces the [`_app.js`](/docs/pages/building-your-application/routing/custom-app) and [`_document.js`](/docs/pages/building-your-application/routing/custom-document) files. [View the migration guide](/docs/app/building-your-application/upgrading/app-router-migration#migrating-_documentjs-and-_appjs).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -165,8 +165,8 @@ There are two ways routes are prefetched in Next.js:

The`<Link>`'s prefetching behavior is different for static and dynamic routes:

- [**Static Routes**](/docs/app/building-your-application/rendering/static-and-dynamic#static-rendering-default): `prefetch` defaults to `true`. The entire route is prefetched and cached.
- [**Dynamic Routes**](/docs/app/building-your-application/rendering/static-and-dynamic#dynamic-rendering): `prefetch` default to automatic. Only the shared layout down until the first `loading.js` file is prefetched and cached for `30s`. This reduces the cost of fetching an entire dynamic route, and it means you can show an [instant loading state](/docs/app/building-your-application/routing/loading-ui-and-streaming#instant-loading-states) for better visual feedback to users.
- [**Static Routes**](/docs/app/building-your-application/rendering/server-components#static-rendering-default): `prefetch` defaults to `true`. The entire route is prefetched and cached.
- [**Dynamic Routes**](/docs/app/building-your-application/rendering/server-components#dynamic-rendering): `prefetch` default to automatic. Only the shared layout down until the first `loading.js` file is prefetched and cached for `30s`. This reduces the cost of fetching an entire dynamic route, and it means you can show an [instant loading state](/docs/app/building-your-application/routing/loading-ui-and-streaming#instant-loading-states) for better visual feedback to users.

You can disable prefetching by setting the `prefetch` prop to `false`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ See the [generateStaticParams()](#generating-static-params) page to learn how to

## Generating Static Params

The `generateStaticParams` function can be used in combination with [dynamic route segments](/docs/app/building-your-application/routing/dynamic-routes) to [**statically generate**](/docs/app/building-your-application/rendering/static-and-dynamic#static-rendering-default) routes at build time instead of on-demand at request time.
The `generateStaticParams` function can be used in combination with [dynamic route segments](/docs/app/building-your-application/routing/dynamic-routes) to [**statically generate**](/docs/app/building-your-application/rendering/server-components#static-rendering-default) routes at build time instead of on-demand at request time.

```tsx filename="app/blog/[slug]/page.tsx" switcher
export async function generateStaticParams() {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ export default async function Page({ params: { lang } }) {
}
```

Because all layouts and pages in the `app/` directory default to [Server Components](/docs/getting-started/react-essentials#server-components), we do not need to worry about the size of the translation files affecting our client-side JavaScript bundle size. This code will **only run on the server**, and only the resulting HTML will be sent to the browser.
Because all layouts and pages in the `app/` directory default to [Server Components](/docs/app/building-your-application/rendering/server-components), we do not need to worry about the size of the translation files affecting our client-side JavaScript bundle size. This code will **only run on the server**, and only the resulting HTML will be sent to the browser.

## Static Generation

Expand Down
6 changes: 3 additions & 3 deletions docs/02-app/01-building-your-application/01-routing/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ First, you will see these terms being used throughout the documentation. Here's

## The `app` Router

In version 13, Next.js introduced a new **App Router** built on [React Server Components](/docs/getting-started/react-essentials#server-components), which supports shared layouts, nested routing, loading states, error handling, and more.
In version 13, Next.js introduced a new **App Router** built on [React Server Components](/docs/app/building-your-application/rendering/server-components), which supports shared layouts, nested routing, loading states, error handling, and more.

The App Router works in a new directory named `app`. The `app` directory works alongside the `pages` directory to allow for incremental adoption. This allows you to opt some routes of your application into the new behavior while keeping other routes in the `pages` directory for previous behavior. If your application uses the `pages` directory, please also see the [Pages Router](/docs/pages/building-your-application/routing) documentation.

Expand All @@ -50,9 +50,9 @@ The App Router works in a new directory named `app`. The `app` directory works a
height="444"
/>

By default, components inside `app` are [React Server Components](/docs/getting-started/react-essentials#server-components). This is a performance optimization and allows you to easily adopt them, and you can also use [Client Components](/docs/getting-started/react-essentials#client-components).
By default, components inside `app` are [React Server Components](/docs/app/building-your-application/rendering/server-components). This is a performance optimization and allows you to easily adopt them, and you can also use [Client Components](/docs/app/building-your-application/rendering/client-components).

> **Recommendation:** Check out the [Server and Client Components](/docs/getting-started/react-essentials) page if you're new to Server Components.
> **Recommendation:** Check out the [Server](/docs/app/building-your-application/rendering/server-components) page if you're new to Server Components.

## Roles of Folders and Files

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ There's an extensive list of Segment Config options, giving you fine-grained con

In cases where you're using a third-party library that doesn't support or expose `fetch` (for example, a database, CMS, or ORM client), you can configure the caching and revalidating behavior of those requests using the [Route Segment Config Option](/docs/app/api-reference/file-conventions/route-segment-config) and React's `cache` function.

Whether the data is cached or not will depend on whether the route segment is [statically or dynamically rendered](/docs/app/building-your-application/rendering/static-and-dynamic). If the segment is static (default), the output of the request will be cached and revalidated as part of the route segment. If the segment is dynamic, the output of the request will _not_ be cached and will be re-fetched on every request when the segment is rendered.
Whether the data is cached or not will depend on whether the route segment is [statically or dynamically rendered](/docs/app/building-your-application/rendering/server-components#server-rendering-strategies). If the segment is static (default), the output of the request will be cached and revalidated as part of the route segment. If the segment is dynamic, the output of the request will _not_ be cached and will be re-fetched on every request when the segment is rendered.

> **Good to know:**
>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -304,10 +304,10 @@ export const getItem = cache(async (id) => {
})
```

With this approach, you can eagerly fetch data, cache responses, and guarantee that this data fetching [only happens on the server](/docs/getting-started/react-essentials#keeping-server-only-code-out-of-client-components-poisoning).
With this approach, you can eagerly fetch data, cache responses, and guarantee that this data fetching [only happens on the server](/docs/app/building-your-application/rendering/composition-patterns#keeping-server-only-code-out-of-the-client-environment).

The `utils/get-item` exports can be used by Layouts, Pages, or other components to give them control over when an item's data is fetched.

> **Good to know:**
>
> - We recommend using the [`server-only` package](/docs/getting-started/react-essentials#keeping-server-only-code-out-of-client-components-poisoning) to make sure server data fetching functions are never used on the client.
> - We recommend using the [`server-only` package](/docs/app/building-your-application/rendering/composition-patterns#keeping-server-only-code-out-of-the-client-environment) to make sure server data fetching functions are never used on the client.
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ export default function AddToCart({ productId }) {

Rather than needing to manually create an API endpoint, Server Actions automatically create an endpoint for Next.js to use behind the scenes. When calling a Server Action, Next.js sends a `POST` request to the page you're on with metadata for which action to run.

Server Actions inherit the same runtime (either [Node.js or Edge](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes)) defined by the `page` or `layout` they're used on. Currently, if a route uses a Server Action, it is required to [render dynamically](/docs/app/building-your-application/rendering/static-and-dynamic).
Server Actions inherit the same runtime (either [Node.js or Edge](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes)) defined by the `page` or `layout` they're used on. Currently, if a route uses a Server Action, it is required to [render dynamically](/docs/app/building-your-application/rendering/server-components#server-rendering-strategies).

> **Good to know:**
>
Expand Down
Loading