hanzoai/next.js
2
0
Fork 0
mirror of https://github.com/hanzoai/next.js.git synced 2026-09-24 17:00:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update Route Handlers docs for dynamic (#66010)

Browse Source 
- Remove unnecessary `dynamic` route segment configs
- Add version history
- Remove caching opt-out section, since it's dynamic now

---------

Co-authored-by: JJ Kasper <[email protected]>
This commit is contained in:
Lee Robinson
2024-05-20 22:40:05 -05:00
committed by GitHub
co-authored by JJ Kasper
parent d498f9c173
commit da8fb8ebc8
2 changed files with 6 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-app/01-building-your-application/01-routing/13-route-handlers.mdx
+1 -94
View File
@@ -25,12 +25,10 @@ Route Handlers allow you to create custom request handlers for a given route usi
Route Handlers are defined in a [`route.js|ts` file](/docs/app/api-reference/file-conventions/route) inside the `app` directory:
```ts filename="app/api/route.ts" switcher
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET(request: Request) {}
```
```js filename="app/api/route.js" switcher
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET(request) {}
```
@@ -49,13 +47,11 @@ In addition to supporting native [Request](https://developer.mozilla.org/docs/We
### Caching
Route Handlers are dynamic by default as of Next.js v15. To opt-in to caching for GET requests in route handlers you can specify via the following config:
Route Handlers are dynamic by default as of Next.js v15. To opt-in to caching for `GET` requests, you can use the following config:
```ts filename="app/items/route.ts" switcher
// opt in to caching the route handler
export const dynamic = 'force-static' // or 'error'
// or
export const revalidate = false // or a value > 0
export async function GET() {
const res = await fetch('https://data.mongodb-api.com/...', {
@@ -86,87 +82,6 @@ export async function GET() {
> **TypeScript Warning:** `Response.json()` is only valid from TypeScript 5.2. If you use a lower TypeScript version, you can use [`NextResponse.json()`](/docs/app/api-reference/functions/next-response#json) for typed responses instead.
### Opting out of caching
You can opt out of caching by:
- Using the `Request` object with the `GET` method.
- Using any of the other HTTP methods.
- Using [Dynamic Functions](#dynamic-functions) like `cookies` and `headers`.
- The [Segment Config Options](#segment-config-options) manually specifies dynamic mode.
For example:
```ts filename="app/products/api/route.ts" switcher
export async function GET(request: Request) {
const { searchParams } = new URL(request.url)
const id = searchParams.get('id')
const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY!,
},
})
const product = await res.json()
return Response.json({ product })
}
```
```js filename="app/products/api/route.js" switcher
export async function GET(request) {
const { searchParams } = new URL(request.url)
const id = searchParams.get('id')
const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY,
},
})
const product = await res.json()
return Response.json({ product })
}
```
Similarly, the `POST` method will cause the Route Handler to be evaluated dynamically.
```ts filename="app/items/route.ts" switcher
export async function POST() {
const res = await fetch('https://data.mongodb-api.com/...', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY!,
},
body: JSON.stringify({ time: new Date().toISOString() }),
})
const data = await res.json()
return Response.json(data)
}
```
```js filename="app/items/route.js" switcher
export async function POST() {
const res = await fetch('https://data.mongodb-api.com/...', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY,
},
body: JSON.stringify({ time: new Date().toISOString() }),
})
const data = await res.json()
return Response.json(data)
}
```
> **Good to know**: Like API Routes, Route Handlers can be used for cases like handling form submissions. A new abstraction for [handling forms and mutations](/docs/app/building-your-application/data-fetching/server-actions-and-mutations) that integrates deeply with React is being worked on.
### Route Resolution
You can consider a `route` the lowest level routing primitive.
@@ -562,8 +477,6 @@ Since `formData` data are all strings, you may want to use [`zod-form-data`](htt
You can set CORS headers for a specific Route Handler using the standard Web API methods:
```ts filename="app/api/route.ts" switcher
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET(request: Request) {
return new Response('Hello, Next.js!', {
status: 200,
@@ -577,8 +490,6 @@ export async function GET(request: Request) {
```
```js filename="app/api/route.js" switcher
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET(request) {
return new Response('Hello, Next.js!', {
status: 200,
@@ -641,8 +552,6 @@ Notably, unlike API Routes with the Pages Router, you do not need to use `bodyPa
You can use Route Handlers to return non-UI content. Note that [`sitemap.xml`](/docs/app/api-reference/file-conventions/metadata/sitemap#generating-a-sitemap-using-code-js-ts), [`robots.txt`](/docs/app/api-reference/file-conventions/metadata/robots#generate-a-robots-file), [`app icons`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx), and [open graph images](/docs/app/api-reference/file-conventions/metadata/opengraph-image) all have built-in support.
```ts filename="app/rss.xml/route.ts" switcher
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET() {
return new Response(
`<?xml version="1.0" encoding="UTF-8" ?>
@@ -665,8 +574,6 @@ export async function GET() {
```
```js filename="app/rss.xml/route.js" switcher
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET() {
return new Response(`<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
docs/02-app/02-api-reference/02-file-conventions/route.mdx
+5 -4
View File
@@ -43,7 +43,7 @@ export async function PATCH(request) {}
export async function OPTIONS(request) {}
```
> **Good to know**: Route Handlers are only available inside the `app` directory. You **do not** need to use API Routes (`pages`) and Route Handlers (`app`) together, as Route Handlers should be able to handle all use cases.
> **Good to know**: Route Handlers are only available inside the App Router. You **do not** need to use API Routes (`pages`) and Route Handlers (`app`) together, as Route Handlers should be able to handle all use cases.
## Parameters
@@ -87,6 +87,7 @@ Route Handlers can extend the Web Response API by returning a `NextResponse` obj
## Version History
| Version | Changes |
| --------- | ------------------------------ |
| `v13.2.0` | Route handlers are introduced. |
| Version | Changes |
| --------- | ------------------------------------------------------------------------- |
| `v15.0.0` | The default caching for `GET` handlers was changed from static to dynamic |
| `v13.2.0` | Route Handlers are introduced. |