Skip to content

chore: update middleware docs wording #799

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 15, 2021
Merged

chore: update middleware docs wording #799

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1d42a6
chore: update middleware docs wording
ascorbic Nov 15, 2021
a53c88e
Merge branch 'main' into mk/middleware-docs-update
kodiakhq[bot] Nov 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 24 additions & 28 deletions docs/middleware.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Using Next 12 middleware on Netlify

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

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

## How to deploy Next 12 middleware

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

### `geo`

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

```typescript
export async function middleware(req: NextRequest) {
Expand All @@ -42,35 +42,31 @@ export async function middleware(req: NextRequest) {

## Caveats

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
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
`EXPERIMENTAL_MOVE_STATIC_FILES` option, as this causes statically-generated pages to be served by the Netlify CDN
before any middleware can be run.
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 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 `EXPERIMENTAL_MOVE_STATIC_FILES` option, as this causes
statically-generated pages to be served by the Netlify CDN before any middleware can be run.

There is currently [a bug in Next.js](https://github.com/vercel/next.js/issues/31179) that causes a proxy loop if you
try to rewrite to a URL with a host other than localhost. If you are using a pattern like this:
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
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
ensuring that when rewriting a request you either use a relative path, or manually set the host to `localhost` if
returning a URL object. For example:

```typescript
export function middleware(req: NextRequest) {
// Change the `nextUrl` property in some way
req.nextUrl = req.nextUrl.replace('something', 'somethingelse')
// ...then rewrite to the changed URL
return NextResponse.rewrite(req.nextUrl)
}
```
const rewrittenUrl = req.nextUrl

...then you need to set the `nextUrl.host` to `localhost`:
// Change the URL in some way
// ...

```typescript
export function middleware(req: NextRequest) {
// Change the `nextUrl` property in some way
req.nextUrl = req.nextUrl.replace('something', 'somethingelse')
req.nextUrl.host = 'localhost'
// Before returning the URL, set the host to localhost
rewrittenUrl.host = 'localhost'

// ...then rewrite to the changed URL
return NextResponse.rewrite(req.nextUrl)
return NextResponse.rewrite(rewrittenUrl)
}
Comment on lines +50 to 67
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are the only content changes

```

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