Skip to content

Commit 93008d1

Browse files
chore: update middleware docs wording (#799)
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
1 parent b0f666e commit 93008d1

File tree

1 file changed

+24
-28
lines changed

1 file changed

+24
-28
lines changed

docs/middleware.md

+24-28
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Using Next 12 middleware on Netlify
22

3-
Next 12 introduces a new feature called [Middleware](https://nextjs.org/docs/middleware), in which functions
4-
run before a request has finished processing. Middleware can be used to modify the request or replace the response. For
5-
example, it can change headers, rewrite the request path, or return a different response entirely.
3+
Next 12 introduces a new feature called [Middleware](https://nextjs.org/docs/middleware), in which functions run before
4+
a request has finished processing. Middleware can be used to modify the request or replace the response. For example, it
5+
can change headers, rewrite the request path, or return a different response entirely.
66

7-
Next.js Middleware can run either in an edge function or at the origin. On Netlify, middleware runs at the origin as part
8-
of the normal Next.js server.
7+
Next.js Middleware can run either in an edge function or at the origin. On Netlify, middleware runs at the origin as
8+
part of the normal Next.js server.
99

1010
## How to deploy Next 12 middleware
1111

@@ -15,8 +15,8 @@ workarounds that are currently required for some features during the beta period
1515

1616
### `geo`
1717

18-
When running at the origin, Next.js does not populate the `request.geo` object. Fortunately there is a one line fix to get
19-
the visitor's country:
18+
When running at the origin, Next.js does not populate the `request.geo` object. Fortunately there is a one line fix to
19+
get the visitor's country:
2020

2121
```typescript
2222
export async function middleware(req: NextRequest) {
@@ -42,35 +42,31 @@ export async function middleware(req: NextRequest) {
4242

4343
## Caveats
4444

45-
Because the middleware runs at the origin, it is run _after_ Netlify rewrites and redirects. If a static file is served by the Netlify CDN
46-
then the middleware is never run, as middleware only runs when a page is served by Next.js. This means that middleware should not be used with the
47-
`EXPERIMENTAL_MOVE_STATIC_FILES` option, as this causes statically-generated pages to be served by the Netlify CDN
48-
before any middleware can be run.
45+
Because the middleware runs at the origin, it is run _after_ Netlify rewrites and redirects. If a static file is served
46+
by the Netlify CDN then the middleware is never run, as middleware only runs when a page is served by Next.js. This
47+
means that middleware should not be used with the `EXPERIMENTAL_MOVE_STATIC_FILES` option, as this causes
48+
statically-generated pages to be served by the Netlify CDN before any middleware can be run.
4949

50-
There is currently [a bug in Next.js](https://github.com/vercel/next.js/issues/31179) that causes a proxy loop if you
51-
try to rewrite to a URL with a host other than localhost. If you are using a pattern like this:
50+
There is a bug in Next.js `<=12.0.3` that causes a proxy loop if you try to rewrite to a URL with a host other than
51+
localhost. This bug is fixed in version `12.0.4`. If you are using Next.js `<=12.0.3`, you can work around the bug by
52+
ensuring that when rewriting a request you either use a relative path, or manually set the host to `localhost` if
53+
returning a URL object. For example:
5254

5355
```typescript
5456
export function middleware(req: NextRequest) {
55-
// Change the `nextUrl` property in some way
56-
req.nextUrl = req.nextUrl.replace('something', 'somethingelse')
57-
// ...then rewrite to the changed URL
58-
return NextResponse.rewrite(req.nextUrl)
59-
}
60-
```
57+
const rewrittenUrl = req.nextUrl
6158

62-
...then you need to set the `nextUrl.host` to `localhost`:
59+
// Change the URL in some way
60+
// ...
6361

64-
```typescript
65-
export function middleware(req: NextRequest) {
66-
// Change the `nextUrl` property in some way
67-
req.nextUrl = req.nextUrl.replace('something', 'somethingelse')
68-
req.nextUrl.host = 'localhost'
62+
// Before returning the URL, set the host to localhost
63+
rewrittenUrl.host = 'localhost'
6964

7065
// ...then rewrite to the changed URL
71-
return NextResponse.rewrite(req.nextUrl)
66+
return NextResponse.rewrite(rewrittenUrl)
7267
}
7368
```
7469

75-
If you have an issue with Next.js middleware on Netlify while it is beta, particularly if the issue cannot be reproduced when
76-
running locally, then please add a comment to [the Next plugin beta discussion](https://ntl.fyi/next-beta-feedback).
70+
If you have an issue with Next.js middleware on Netlify while it is beta, particularly if the issue cannot be reproduced
71+
when running locally, then please add a comment to
72+
[the Next plugin beta discussion](https://ntl.fyi/next-beta-feedback).

0 commit comments

Comments
 (0)