From ec82b5a8e4e9c1adeb9d31f9024cab976148bac8 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Mon, 20 May 2024 21:45:11 -0400 Subject: [PATCH 1/2] docs: Update Route Handlers docs for dynamic --- .../01-routing/13-route-handlers.mdx | 95 +------------------ .../02-file-conventions/route.mdx | 9 +- 2 files changed, 6 insertions(+), 98 deletions(-) diff --git a/docs/02-app/01-building-your-application/01-routing/13-route-handlers.mdx b/docs/02-app/01-building-your-application/01-routing/13-route-handlers.mdx index 73e33a17a4f9e..cc700e4a48eb3 100644 --- a/docs/02-app/01-building-your-application/01-routing/13-route-handlers.mdx +++ b/docs/02-app/01-building-your-application/01-routing/13-route-handlers.mdx @@ -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( ` @@ -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(` diff --git a/docs/02-app/02-api-reference/02-file-conventions/route.mdx b/docs/02-app/02-api-reference/02-file-conventions/route.mdx index 9924ed5ff245c..ee7192f1733ae 100644 --- a/docs/02-app/02-api-reference/02-file-conventions/route.mdx +++ b/docs/02-app/02-api-reference/02-file-conventions/route.mdx @@ -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 | +| --------- | ------------------------------------------------------------------------- | +| `v13.2.0` | The default caching for `GET` handlers was changed from static to dynamic | +| `v13.2.0` | Route Handlers are introduced. | From 88c43f7ed5ba4d02a7f2cccecc2632be0bfff9f5 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Mon, 20 May 2024 21:47:18 -0500 Subject: [PATCH 2/2] Update docs/02-app/02-api-reference/02-file-conventions/route.mdx Co-authored-by: JJ Kasper --- docs/02-app/02-api-reference/02-file-conventions/route.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/02-app/02-api-reference/02-file-conventions/route.mdx b/docs/02-app/02-api-reference/02-file-conventions/route.mdx index ee7192f1733ae..9ef5f7702286e 100644 --- a/docs/02-app/02-api-reference/02-file-conventions/route.mdx +++ b/docs/02-app/02-api-reference/02-file-conventions/route.mdx @@ -89,5 +89,5 @@ Route Handlers can extend the Web Response API by returning a `NextResponse` obj | Version | Changes | | --------- | ------------------------------------------------------------------------- | -| `v13.2.0` | The default caching for `GET` handlers was changed from static to dynamic | +| `v15.0.0` | The default caching for `GET` handlers was changed from static to dynamic | | `v13.2.0` | Route Handlers are introduced. |