Guides & Tutorials
How to Use Next.js Middleware
Next.js Middleware works out of the box on Netlify, and it's even better with the addition of Netlify Edge Functions, powered by Deno. Edge Functions also give developers more options for achieving middleware use cases such as localization, personalization, authentication, A/B testing, and more.
What is Next.js Middleware and how does it work on Netlify?
Next.js Middleware is an exciting feature that was released as part of Next.js 12, and it has been supported by Netlify since day one. With Next.js Middleware, you can modify responses based on a user’s incoming request or location. This means you could rewrite, redirect, add headers, or stream HTML.
Now, with Netlify Edge Functions, Next.js Middleware can run at the edge instead of from an origin server. This means Next.js developers using Netlify will see performance improvements and reduced latency, as the middleware code will now run closer to users.
Beyond that, Next.js Middleware can now run in front of static pages or pages served with Incremental Static Regeneration (ISR) by the Netlify CDN, letting you sprinkle some dynamic magic onto your pre-rendered pages.
Note: While Next.js Middleware on Netlify Edge Functions is in beta, you will need to enable it by setting the environment variable
NEXT_USE_NETLIFY_EDGE to “true” in your site.
Here’s a starter demo to show how it works: https://github.com/netlify/next-edge-middleware
This example demonstrates how Next.js Middleware can be used to dynamically show content based on a user’s country code.
Here’s how it works: When the site is deployed, Netlify packages the middleware function into an Edge Function and passes the geolocation information to it from the request. This information includes country code, city, region, lat and long. The function takes the country code and rewrites the URL with it added as a query parameter which Next.js makes available to the page template so it can render the country name and flag.
You can deploy this starter demo to Netlify with one-click:
Middleware vs. Edge Functions
While Netlify Edge Functions improve the performance of Next.js Middleware on Netlify, it’s also worth noting that just about anything you’d want to do with Next.js Middleware, you can also achieve with Netlify Edge Functions on their own.
Shared use cases include:
- Serving personalized or localized content
- Custom authentication
- Redirects and rewrites
- A/B tests
Learn more about how to achieve these use cases in the Netlify Docs for Edge Functions.
Benefits of Edge Functions
While Netlify Edge Functions have a lot in common with Next.js Middleware, using Edge Functions directly unlocks several extra features. Netlify Edge Functions give you full access to transform both the Request and the Response objects, whereas with Next.js Middleware there are some limitations. You can add headers to a response, but you cannot access or modify the response body. You can rewrite the target URL or a request but you cannot change the request in any other way.
With Edge Functions, when you call
context.next(), the response is a Fetch Response object. This means you don’t only have access to the body by calling
response.json(), but you can also process the body as a stream. This is extremely powerful, because it allows you to transform the response chunk by chunk without waiting for it to fully load, resulting in less latency and better memory usage.
For example if you’re returning a large HTML file from the origin, you can scan it to replace placeholders with dynamic content and stream the file to the user as you go, so they can start receiving it before the edge function has even finished loading it. This allows you to perform powerful transformations with minimal added latency. Without streams you would need to load the whole file before you can start processing it.
Bottom line: Even when you're building with Next.js, there are some use cases where you might want to choose Netlify Edge Functions instead of the middleware built into the framework.
Let’s talk about your Next.js project
Are you considering Next.js for a commercial project, like a website, e-commerce shop, or application? Contact us to request a guided pilot! The Netlify experts can answer your questions about complex use cases and make recommendations suited to your team’s goals.
We're glad to support the thousands of developers who build with Next.js on Netlify every week!