## What?
- Updated the heading structure in the documentation to maintain a consistent hierarchy.
- All primary points now use `###` for better readability and understanding of content structure.
## Why?
While reviewing the documentation, I noticed that the heading levels were inconsistent between sections 1, 2, and 3-5.
This PR is a larger change to documentation to make the following
updates:
- Deconstructs [Server
Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions)
into "Forms and Mutations" and an API reference
- Removes content in place of future React API documentation pages
- Removes outdated [Building
Forms](https://nextjs.org/docs/pages/building-your-application/data-fetching/building-forms)
docs from the Pages Router and adds conditional content for both routes
in "Forms and Mutations"
- Adds TypeScript code blocks to API Routes page, recommends Route
Handlers for isomorphic signatures.
- Updates `revalidatePath` and `revalidateTag` docs to have a Server
Actions example.
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
We initially wrote the [React
page](https://nextjs.org/docs/getting-started/react-essentials) to
introduce Server Components in the App Router, but over time, some
implementation details have changed, and the information has become
stale. The React team is working on adding new docs, so I'd like to
change the narrative on the Next.js docs from "client vs. server
components" to "writing code for the server and for the client" - and
link back to the React documentation when it becomes available.
As React developers, we're very familiar with writing code for the
client, it's nice and simple. But doing so comes at the expense of not
being familiar with the server. The aim of these docs is to help
developers become proficient in both the client and server environments.
I'd like to take it back to the foundations, and not use abstractions
like SSG and CSR, MPAs or SPAs, as those terms come with their own set
of assumptions that make it harder to understand how RSC works. Instead,
we'll focus on the request lifecycle, show how application code flows
from the server to the client, and discuss the trade-offs of doing
operations in each environment.
- [x] Page: Rendering Fundamentals
- [x] Environments: Client and Server
- [x] Request-response lifecycle
- [x] Network Boundary
- [x] Page: Server Components
- [x] Benefits and use cases of server rendering
- [x] How to use Server Components in Next.js
- [x] How Server Components are rendered
- [x] Static Rendering
- [x] Dynamic Rendering
- [x] Streaming
- [x] Page: Client Components
- [x] Benefits and use cases of client rendering
- [x] How to use Client Components in Next.js
- [x] How Client Components are rendered
- [x] Initial vs. Subsquent navigation
- [x] Page: Composition Patterns
- [x] When to use client and server components
- [x] Server Component Patterns
- [x] Client Component Patterns
- [x] Interleaving Client and Server Components
- [ ] ~Diagrams~ will follow up with new PR.
- [x] Set up redirects: https://github.com/vercel/front/pull/24917
---------
Co-authored-by: Térence Hollander <hollanderterence@gmail.com>
Co-authored-by: shawnthwei <32075290+shawnthwei@users.noreply.github.com>
Co-authored-by: Michael Novotny <manovotny@gmail.com>
### Why?
Many developers are asking how to add internationalized routing in the App Router as it works in the Pages Router. [next-i18n-router](https://www.npmjs.com/package/next-i18n-router) is a very helpful package that fully solves this challenge.
### How?
Unlike the example provided in these Next.js i18n docs, [next-i18n-router](https://www.npmjs.com/package/next-i18n-router) does not require nesting all pages in a `[lang]` dynamic segment. It also allows for the default language to be accessible without a locale prefix in the path (just like in the Pages Router).
It includes locale detection based on the `accept-language` header as recommended in the Next.js docs, as well as support for the `NEXT_LOCALE` cookie to set a user's preferred language (just like in the Pages Router).
Clarify what status code is returned when streaming, and in relation to `redirect` and `not-found`.
Relates to: https://github.com/vercel/next.js/pull/54361
Co-authored-by: Lee Robinson <9113740+leerob@users.noreply.github.com>
Fixes: https://vercel.slack.com/archives/C03S9JCH2Q5/p1692619927373449
- Updates wording on nesting, to say it's not the actual output, but rather how `template.js` nests between `layout.js` and its children.
- Remove mention of animations, needs further clarification.
Added a switcher on a code snippet under heading -> `Using Cookies`, just like the other code snippets on this page got one..
(For those who don't know what a switcher is -> It's just a simple functionality for changing `typescript` code to `javascript` and vice-versa, kind of a UI feature for better experience`
Co-authored-by: Balázs Orbán <18369201+balazsorban44@users.noreply.github.com>
This PR document the caching semantics in Next.js, how they interact, and what APIs affect them. We're also taking the opportunity to consolidate terminology, remove duplicate content, and update sections of the docs that relate to caching.
### Documentation
- [x] Create a new section for caching
- [x] Explain how the different caching mechanisms work
- [x] Request Memoization (React Cache)
- [x] Persistent Data Cache
- [x] Persistent Full Route Cache
- [x] In-memory, client-side Router Cache
- [x] Document how different APIs affect caching
- [x] Document cache interactions
- [x] Clean up stale information in the other docs sections
- [x] Routing Section
- [x] Move advanced navigation topics from fundamentals to **How Navigation Works** section
- [x] Rewrite the **How Navigation Works** section
- [x] Rendering Section
- [x] Simplify fundamentals page
- [x] Rewrite the **Static and Dynamic Rendering** pages
- [ ] ~Create a page to explain how **Client and Server Components** are rendered~. Moved to this PR: https://github.com/vercel/next.js/pull/51579
- [x] Data fetching section
- [x] Consolidate data fetching story for fetching, caching, and revalidating
- [x] Clarify data fetching story with 3rd party libraries and React `cache`
- [x] Create **Data Fetching Patterns** page
- [x] Document other related behaviors:
- [x] Update information on scroll position for back/forward navigation
- [x] Remove the concepts of **soft and hard navigation**
- [x] Remove the concepts of **static and dynamic data fetching**
- [x] Use consistent terminology **runtime** 👉🏼 **request time**. Runtime for Edge and Node.js, request time to describe when dynamic stuff happens
- [x] `generateStaticParams` being able to seed the Full Route Cache
- [x] Polish 💅🏼
---
### Related PRs:
- Diagrams: https://github.com/vercel/front/pull/24142
- Redirects: https://github.com/vercel/front/pull/24179
changing AI example model from `text-davinci-003` to `gpt-3.5-turbo`
which is in a `chat/route.ts` format.
The alternative but with "completition" style would be a bit longer code
like:
```
// app/api/completion/route.ts
import { Configuration, OpenAIApi } from 'openai-edge'
import { OpenAIStream, StreamingTextResponse } from 'ai'
export const runtime = 'edge'
const apiConfig = new Configuration({
apiKey: process.env.OPENAI_API_KEY!,
})
const openai = new OpenAIApi(apiConfig)
function buildPrompt(prompt: string) {
return prompt.split('\n').map((message) => ({
role: 'user',
content: message,
}));
}
export async function POST(req: Request) {
// Extract the `prompt` from the body of the request
const { prompt } = await req.json();
// Request the OpenAI API for the response based on the prompt
const response = await openai.createChatCompletion({
model: 'gpt-3.5-turbo',
stream: true,
messages: buildPrompt(prompt),
max_tokens: 500,
temperature: 0.7,
top_p: 1,
frequency_penalty: 1,
presence_penalty: 1,
})
// Convert the response into a friendly text-stream
const stream = OpenAIStream(response)
// Respond with the stream
return new StreamingTextResponse(stream)
}
```
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Adding or Updating Examples
- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
---------
Co-authored-by: Lee Robinson <me@leerob.io>
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
### Why?
The code snippet in the Route handler `formData` documentation
```ts
import { NextResponse } from 'next/server'
export async function POST(request: Request) {
const formData = await request.formData()
return NextResponse.json({ formData })
}
```
is slightly wrong, because `formData` is not a plain object and hence `return NextResponse.json({ formData })` doesn't actually work.
Since we are already in the topic of parsing `formData`, I also added a mention on `zod-form-data` which can be used to validate the form and parse it to non-string formats such as `number`.
This link is failing CI as seen here:
https://github.com/vercel/next.js/actions/runs/5623454975/job/15238167610
```
Error: The action could not create a Github comment because it is initiated from a forked repo. View the action logs for a list of broken links.
This PR introduces broken links to the docs:
┌─────────┬───────────────────────────────────────────────────────────────────────────────┬──────┬─────────────────────────────────────────────────────────────────────────────────────┐
│ (index) │ link │ type │ docPath │
├─────────┼───────────────────────────────────────────────────────────────────────────────┼──────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ 0 │ 'app/building-your-application/configuring/typescript#statically-typed-links' │ │ 'docs/02-app/01-building-your-application/01-routing/03-linking-and-navigating.mdx' │
└─────────┴───────────────────────────────────────────────────────────────────────────────┴──────┴─────────────────────────────────────────────────────────────────────────────────────┘
Error: This PR introduces broken links to the docs. The action could not create a Github check because it is initiated from a forked repo.
Error: Process completed with exit code 1.
```
### What and why?
The word "publicly" should be spelled consistently across the documentation. It is spelled currently as "publically" in a few places.
### How?
Fixed the spelling!
Route handlers are not specifically different from API Routes in terms of forms or other usage, the only difference is how you write them (Request) => Response. Initially this mention was supposed to be removed when server actions are marked stable, but it's leading to some confusion so I've updated the mention to clarify that there will be a more integrated solution for React.
This PR adds more info about `error.message`, `error.digest`, and
omission of sensitive error details from Server Components.
---------
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
Co-authored-by: Lee Robinson <me@leerob.io>
### What?
- Added separate links for the app and pages router in the shared documentation.
- Added comment at the top of all shared documentation.
- Fixed typos in pages documentation comment.
### Why?
- To limit the switching between the different routers in shared documentation when clicking the links.
Apparently the object deconstruction in the example doesn't work. This PR proposes a working version:
```diff
- export default function Page({ params: { slug: string } }) {
- return <div>My Post: {slug}</div>
- }
+ export default function Page({ params }: { params: { slug: string } }) {
+ return <div>My Post: {params.slug}</div>
+ }
```
According to the [page reference](https://nextjs.org/docs/app/api-reference/file-conventions/page), the page function parameter slugs needs to be retrieved by calling `params.slug`.
The TypeScript section below shows the correct function type signature, although not referencing to the parameter.
* Changes all `Note` → `Good to know`
* Consistently puts the colon on the outside of bold text
* Documents singe and multi-line styles in contribution guide
---------
Co-authored-by: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Added a TS and JS switcher. Previously the code snippet did not have a
switcher. The file extension was .js when the code was TypeScript which
made it confusing to try to read.
---------
Co-authored-by: Lee Robinson <me@leerob.io>
## Why?
- When i click `red box` in following image, page returns 404 page.
<img width="1728" alt="스크린샷 2023-06-08 오후 7 31 37" src="https://github.com/vercel/next.js/assets/63336958/903b11e3-17af-426e-8787-b6e033c14a24">
## How?
- I found that `/` is missed at `docs/02-app/01-building-your-application/01-routing/02-pages-and-layouts.mdx`.
- So I added `/`.
