Unverified Commit fd8b4c59 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

docs: Split "Get Started: Route Handlers and Middleware" to Route Handlers and Proxy (#84708)

This PR splits the route handlers and middleware to allow for separate
onboarding docs, making it easier to migrate the docs from Middleware to
Proxy.

These PR stacks are to publish a full replacement of the docs for the
Middleware to Proxy. Steps are as follows:

- Split "Get Started: Route Handlers and middleware" to Route Handlers /
Proxy
- Clone the Middleware docs for Proxy
- Add "Migration to Proxy" section to Middleware docs
  - Explain the rationale for the renaming to Proxy
  - Provide migration guide
- Add an error doc that the deprecation warning can refer to. The error
doc will:
  - Explain why this error occurred
  - Provide migration guide
  - Explain the rationale for the renaming to Proxy
parent 332aaf39
---
title: Route Handlers and Middleware
nav_title: Route Handlers and Middleware
description: Learn how to use Route Handlers and Middleware
title: Route Handlers
nav_title: Route Handlers
description: Learn how to use Route Handlers
related:
title: API Reference
description: Learn more about Route Handlers and Middleware
description: Learn more about Route Handlers
links:
- app/api-reference/file-conventions/route
- app/api-reference/file-conventions/middleware
- app/guides/backend-for-frontend
---
......@@ -142,61 +141,3 @@ export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
> **Good to know**
>
> - Types are generated during `next dev`, `next build` or `next typegen`.
## Middleware
Middleware allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
### Use cases
Some common scenarios where Middleware is effective include:
- Quick redirects after reading parts of the incoming request
- Rewriting to different pages based on A/B tests or experiments
- Modifying headers for all pages or a subset of pages
Middleware is _not_ a good fit for:
- Slow data fetching
- Session management
Using fetch with `options.cache`, `options.next.revalidate`, or `options.next.tags`, has no effect in Middleware.
### Convention
Create a `middleware.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`.
> **Note**: While only one `middleware.ts` file is supported per project, you can still organize your middleware logic into modules. Break out middleware functionalities into separate `.ts` or `.js` files and import them into your main `middleware.ts` file. This allows for cleaner management of route-specific middleware, aggregated in the `middleware.ts` for centralized control. By enforcing a single middleware file, it simplifies configuration, prevents potential conflicts, and optimizes performance by avoiding multiple middleware layers.
### Example
```ts filename="middleware.ts" switcher
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
// This function can be marked `async` if using `await` inside
export function middleware(request: NextRequest) {
return NextResponse.redirect(new URL('/home', request.url))
}
// See "Matching Paths" below to learn more
export const config = {
matcher: '/about/:path*',
}
```
```js filename="middleware.js" switcher
import { NextResponse } from 'next/server'
// This function can be marked `async` if using `await` inside
export function middleware(request) {
return NextResponse.redirect(new URL('/home', request.url))
}
// See "Matching Paths" below to learn more
export const config = {
matcher: '/about/:path*',
}
```
Read more about [using `middleware`](/docs/app/guides/backend-for-frontend#middleware), or refer to the `middleware` [API reference](/docs/app/api-reference/file-conventions/middleware).
---
title: Proxy
nav_title: Proxy
description: Learn how to use Proxy
related:
title: API Reference
description: Learn more about Proxy
links:
# TODO: Update to proxy docs
- app/api-reference/file-conventions/middleware
- app/guides/backend-for-frontend
---
## Proxy
Proxy allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
### Use cases
Some common scenarios where Proxy is effective include:
- Quick redirects after reading parts of the incoming request
- Rewriting to different pages based on A/B tests or experiments
- Modifying headers for all pages or a subset of pages
Proxy is _not_ a good fit for:
- Slow data fetching
- Session management
Using fetch with `options.cache`, `options.next.revalidate`, or `options.next.tags`, has no effect in Proxy.
### Convention
Create a `proxy.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`.
> **Note**: While only one `proxy.ts` file is supported per project, you can still organize your proxy logic into modules. Break out proxy functionalities into separate `.ts` or `.js` files and import them into your main `proxy.ts` file. This allows for cleaner management of route-specific proxy, aggregated in the `proxy.ts` for centralized control. By enforcing a single proxy file, it simplifies configuration, prevents potential conflicts, and optimizes performance by avoiding multiple proxy layers.
### Example
```ts filename="proxy.ts" switcher
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
// This function can be marked `async` if using `await` inside
export function proxy(request: NextRequest) {
return NextResponse.redirect(new URL('/home', request.url))
}
// See "Matching Paths" below to learn more
export const config = {
matcher: '/about/:path*',
}
```
```js filename="proxy.js" switcher
import { NextResponse } from 'next/server'
// This function can be marked `async` if using `await` inside
export function proxy(request) {
return NextResponse.redirect(new URL('/home', request.url))
}
// See "Matching Paths" below to learn more
export const config = {
matcher: '/about/:path*',
}
```
{/* TODO: Update to proxy docs */}
Read more about [using `proxy`](/docs/app/guides/backend-for-frontend#middleware), or refer to the `proxy` [API reference](/docs/app/api-reference/file-conventions/middleware).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment