Unverified Commit 602a2aba authored by Joseph's avatar Joseph Committed by GitHub

docs: add API reference pages for skipProxyUrlNormalize and skipTrailingSlashRedirect (#97967)

- Generated with the `/write-api-reference` skill
- These two options were only listed in
https://nextjs.org/docs/app/api-reference/file-conventions/proxy#advanced-proxy-flags

Closes: https://github.com/vercel/next.js/issues/56090
parent 1b5400c9
......@@ -256,7 +256,7 @@ Proxy defaults to using the Node.js runtime. The [`runtime`](/docs/app/api-refer
## Advanced Proxy flags
In `v13.1` of Next.js two additional flags were introduced for proxy, `skipProxyUrlNormalize` (formerly `skipMiddlewareUrlNormalize`) and `skipTrailingSlashRedirect` to handle advanced use cases.
In `v13.1` of Next.js two additional flags were introduced for proxy, [`skipProxyUrlNormalize`](/docs/app/api-reference/config/next-config-js/skipProxyUrlNormalize) (formerly `skipMiddlewareUrlNormalize`) and [`skipTrailingSlashRedirect`](/docs/app/api-reference/config/next-config-js/skipTrailingSlashRedirect) to handle advanced use cases.
`skipTrailingSlashRedirect` disables Next.js redirects for adding or removing trailing slashes. This allows custom handling inside proxy to maintain the trailing slash for some paths but not others, which can make incremental migrations easier.
......@@ -477,7 +477,7 @@ When you use `NextResponse.rewrite()`, Next.js automatically propagates the requ
If you implement custom rewrite logic with `fetch()` instead of `NextResponse.rewrite()`, you can run into missing RSC headers unless you forward them manually.
For custom `fetch` rewrite setups, you can also enable `skipProxyUrlNormalize` in `next.config.js` so your rewrite logic can receive the necessary URL shape and RSC headers from the provided request object:
For custom `fetch` rewrite setups, you can also enable [`skipProxyUrlNormalize`](/docs/app/api-reference/config/next-config-js/skipProxyUrlNormalize) in `next.config.js` so your rewrite logic can receive the necessary URL shape and RSC headers from the provided request object:
```js filename="next.config.js"
module.exports = {
......
---
title: skipProxyUrlNormalize
description: Let Proxy see the original request instead of Next.js's normalized version. Formerly skipMiddlewareUrlNormalize.
---
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
Enabling `skipProxyUrlNormalize` lets [Proxy](/docs/app/api-reference/file-conventions/proxy) see the original request instead of Next.js's normalized version. This includes internal URLs, query parameters, and headers used during client-side navigation.
**Most projects don't need this option.** It is one of the [advanced Proxy flags](/docs/app/api-reference/file-conventions/proxy#advanced-proxy-flags), meant for specific routing cases and debugging.
```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
skipProxyUrlNormalize: true,
}
export default nextConfig
```
```js filename="next.config.js" switcher
/** @type {import('next').NextConfig} */
const nextConfig = {
skipProxyUrlNormalize: true,
}
module.exports = nextConfig
```
## Reference
During client-side navigation, Next.js uses an internal request rather than requesting the destination URL as a full document load. By default, Next.js normalizes that request before it reaches Proxy, so Proxy sees the same destination URL for both client-side navigation and a full page load.
Next.js also normalizes what Proxy returns, so any URL you rewrite or redirect to is rewritten to match.
With `skipProxyUrlNormalize: true`, neither normalization runs. Proxy receives the request as sent, and the destinations it rewrites or redirects to are sent as written:
| Default | With `skipProxyUrlNormalize: true` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| `request.nextUrl` resolves the internal data URL back to the route path and extracts the locale | Holds the requested pathname as sent |
| `request.url` is the normalized URL | Is the original request URL |
| The internal `_rsc` query parameter is stripped | Preserved |
| Next.js internal navigation headers (`rsc`, `next-router-state-tree`, `next-router-prefetch`, `next-router-segment-prefetch`, `next-hmr-refresh`) are removed from `request.headers` | Preserved |
| `NextResponse.rewrite()` destinations are re-serialized with the build ID | Sent as written |
| `NextResponse.redirect()` `Location` is rewritten to a relative URL | Sent as written, trailing slash preserved |
| With [`trailingSlash: true`](/docs/app/api-reference/config/next-config-js/trailingSlash), a trailing slash is appended before Proxy runs | Pathname passed through unchanged |
### Deprecated alias
The former name of this option is `skipMiddlewareUrlNormalize`, from when Proxy was called Middleware. It still works and logs a deprecation warning. Setting both at once throws:
```bash filename="Terminal"
Config options `skipProxyUrlNormalize` and `skipMiddlewareUrlNormalize` cannot be set at the same time. Please use `skipProxyUrlNormalize` instead.
```
The [version 16 codemod](/docs/app/guides/upgrading/codemods#160) renames it for you.
## Good to know
- Avoid using the internal navigation headers to return different content for client-side navigation and full page loads.
- You do not need this option to limit which routes Proxy runs on. The [`matcher`](/docs/app/api-reference/file-conventions/proxy#matcher) config still matches the destination URL either way.
- Only the request and response Proxy sees change. Filesystem routing, `redirects`, and `rewrites` from `next.config.js` behave the same.
## Examples
### Reading the URL as the client sent it
<AppOnly>
During client-side navigation, Next.js adds an `_rsc` query parameter and its internal navigation headers to the request. With the option enabled, Proxy can read both.
```ts filename="proxy.ts" switcher
import type { NextRequest } from 'next/server'
export default function proxy(request: NextRequest) {
console.log(request.nextUrl.searchParams.get('_rsc'))
// Enabled: the value Next.js added to the request
// Disabled: null
console.log(request.headers.get('rsc'))
// Enabled: '1' during client-side navigation
// Disabled: null
}
```
```js filename="proxy.js" switcher
export default function proxy(request) {
console.log(request.nextUrl.searchParams.get('_rsc'))
// Enabled: the value Next.js added to the request
// Disabled: null
console.log(request.headers.get('rsc'))
// Enabled: '1' during client-side navigation
// Disabled: null
}
```
</AppOnly>
<PagesOnly>
During client-side navigation, Next.js requests a `/_next/data` URL instead of the destination URL. With the option enabled, Proxy sees that URL as sent.
```ts filename="proxy.ts" switcher
import type { NextRequest } from 'next/server'
export default function proxy(request: NextRequest) {
const { pathname } = request.nextUrl
// Request: GET /_next/data/build-id/hello.json
console.log(pathname)
// Enabled: /_next/data/build-id/hello.json
// Disabled: /hello
}
```
```js filename="proxy.js" switcher
export default function proxy(request) {
const { pathname } = request.nextUrl
// Request: GET /_next/data/build-id/hello.json
console.log(pathname)
// Enabled: /_next/data/build-id/hello.json
// Disabled: /hello
}
```
</PagesOnly>
## Version History
| Version | Changes |
| --------- | --------------------------------------------------------------------- |
| `v16.0.0` | Renamed from `skipMiddlewareUrlNormalize` to `skipProxyUrlNormalize`. |
| `v13.1.0` | `skipMiddlewareUrlNormalize` added. |
---
title: skipTrailingSlashRedirect
description: Disable the automatic trailing slash redirects so you can handle trailing slashes yourself in Proxy.
---
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
Enabling `skipTrailingSlashRedirect` turns off the automatic redirects that add or remove a trailing slash. You handle any redirecting you still want in [Proxy](/docs/app/api-reference/file-conventions/proxy).
**Most projects don't need this option.** It is one of the [advanced Proxy flags](/docs/app/api-reference/file-conventions/proxy#advanced-proxy-flags), meant for specific routing cases and debugging.
```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
skipTrailingSlashRedirect: true,
}
export default nextConfig
```
```js filename="next.config.js" switcher
/** @type {import('next').NextConfig} */
const nextConfig = {
skipTrailingSlashRedirect: true,
}
module.exports = nextConfig
```
## Reference
By default, Next.js redirects every request so the trailing slash matches your [`trailingSlash`](/docs/app/api-reference/config/next-config-js/trailingSlash) setting.
| `trailingSlash` | Request | Default response |
| --------------- | --------- | --------------------------- |
| `false` | `/about` | `200` |
| `false` | `/about/` | `308` redirect to `/about` |
| `true` | `/about` | `308` redirect to `/about/` |
| `true` | `/about/` | `200` |
Enabling `skipTrailingSlashRedirect` affects both server responses and client-side navigation:
- Both `/about` and `/about/` return `200`. Neither redirects to the other.
- Next.js stops changing trailing slashes during client-side navigation. [`<Link>`](/docs/app/api-reference/components/link) and router URLs keep the path exactly as written.
Your own `redirects` and `rewrites` from `next.config.js` still apply.
### Paths that contain a dot
If the last path segment contains a dot, Next.js treats the path as a file and removes the trailing slash, regardless of the `trailingSlash` setting. A dot in an earlier segment has no effect, except under `.well-known/`, which is exempt from the default redirects when `trailingSlash` is `true`.
| Request | `trailingSlash: true` | `trailingSlash: false` | `skipTrailingSlashRedirect: true` |
| ------------------------- | ---------------------------------- | ------------------------------------------ | --------------------------------- |
| `/about` | `308` redirect to `/about/` | `200` | `200` |
| `/about/` | `200` | `308` redirect to `/about` | `200` |
| `/gcc.git/` | `308` redirect to `/gcc.git` | `308` redirect to `/gcc.git` | `200` |
| `/version/1.2.3/` | `308` redirect to `/version/1.2.3` | `308` redirect to `/version/1.2.3` | `200` |
| `/version/1.2.3/my-page/` | `200` | `308` redirect to `/version/1.2.3/my-page` | `200` |
| `/.well-known/x/` | `200` | `308` redirect to `/.well-known/x` | `200` |
With `skipTrailingSlashRedirect` enabled, none of these redirects are generated and every path is served at whichever form was requested.
## Good to know
- Keep setting [`trailingSlash`](/docs/app/api-reference/config/next-config-js/trailingSlash) as you did before. It still controls the URLs Next.js generates and the output filenames for [`output: 'export'`](/docs/app/guides/static-exports).
- With `output: 'export'`, this preserves the `href` instead of resolving `/me` to `/me/`. See [Static Exports](/docs/app/guides/static-exports).
- Serving one page at both `/about` and `/about/` gives search engines two URLs for it. Set a [canonical URL](/docs/app/api-reference/functions/generate-metadata#alternates) in your metadata, or redirect in [Proxy](/docs/app/api-reference/file-conventions/proxy).
## Examples
### Handling trailing slashes in Proxy
With `skipTrailingSlashRedirect` enabled, Next.js no longer adds trailing slashes, but Proxy can still add them selectively. This example adds a trailing slash to your own routes while leaving a set of legacy prefixes untouched, which makes an incremental migration easier.
```ts filename="proxy.ts" switcher
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
const legacyPrefixes = ['/docs', '/blog']
export default function proxy(request: NextRequest) {
const { pathname } = request.nextUrl
if (legacyPrefixes.some((prefix) => pathname.startsWith(prefix))) {
return NextResponse.next()
}
// Apply trailing slash handling, skipping files and `.well-known` paths
if (
!pathname.endsWith('/') &&
!pathname.match(/((?!\.well-known(?:\/.*)?)(?:[^/]+\/)*[^/]+\.\w+)/)
) {
return NextResponse.redirect(new URL(`${pathname}/`, request.nextUrl))
}
}
```
```js filename="proxy.js" switcher
import { NextResponse } from 'next/server'
const legacyPrefixes = ['/docs', '/blog']
export default function proxy(request) {
const { pathname } = request.nextUrl
if (legacyPrefixes.some((prefix) => pathname.startsWith(prefix))) {
return NextResponse.next()
}
// Apply trailing slash handling, skipping files and `.well-known` paths
if (
!pathname.endsWith('/') &&
!pathname.match(/((?!\.well-known(?:\/.*)?)(?:[^/]+\/)*[^/]+\.\w+)/)
) {
return NextResponse.redirect(new URL(`${pathname}/`, request.nextUrl))
}
}
```
## Version History
| Version | Changes |
| --------- | ---------------------------------- |
| `v13.1.0` | `skipTrailingSlashRedirect` added. |
---
title: skipProxyUrlNormalize
description: Let Proxy see the original request instead of Next.js's normalized version. Formerly skipMiddlewareUrlNormalize.
source: app/api-reference/config/next-config-js/skipProxyUrlNormalize
---
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
---
title: skipTrailingSlashRedirect
description: Disable the automatic trailing slash redirects so you can handle trailing slashes yourself in Proxy.
source: app/api-reference/config/next-config-js/skipTrailingSlashRedirect
---
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
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