Guides & Tutorials

How to Use Next.js Middleware

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 give developers more options for achieving middleware use cases such as localization, personalization, authentication, A/B testing, and more.

What is Next.js Middleware?

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.

How does Next.js Middleware work on Netlify?

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 prerendered pages.

Check out this starter demo to see how it works.

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 website 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, latitude and longitude. 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:

Deploy to Netlify

Next.js 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, the response is a Fetch Response object. This means you don’t only have access to the body by calling response.text(), response.blob() or 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 app? 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!

Keep reading

Recent posts

Book cover with the title Deliver web project 10 times faster with Jamstack enterprise

Deliver web projects 10× faster

Get the whitepaper