If you’ve ever worked with Next.js Middleware, you might have noticed something confusing: it doesn’t behave like Express middleware, and the docs throw a lot of warnings mid-way. No wonder it’s having an identity crisis! Let’s break it down.
What is Next.js Middleware?
Next.js Middleware is a special piece of code that runs before a request is fully processed. It’s meant to:
- Inspect incoming requests
- Modify requests or responses
- Redirect users
- Rewrite URLs
- Add or modify headers
It runs on the Edge Runtime, which is a lightweight JavaScript environment distributed globally, closer to users, so things happen fast and near the user.
So What Exactly is Edge Runtime? Let’s Visualized it..
Imagine your app has a central server. Every user request from anywhere in the world — has to travel all the way there.
Chaos ensues: slow responses, traffic jams, and frustrated users.
Now imagine lightweight servers at the edge, closer to users, handling simple tasks instantly:
✅ Checking authentication
✅ Redirecting requests
✅ Adding headers or rewrites
But they cannot:
❌ Query the database
❌ Run heavy computations
❌ Handle complex business logic
Those still go to the central server the heavy-lifter.
💡 Tech translation:
Central server = Main Server Runtime (Node.js)
Edge servers = Edge Runtime
Quick auth/redirects = Middleware / Proxy
Heavy lifting = Database / API calls
What Middleware Can and Cannot Do
✅ What it’s good at:
- Checking authentication tokens or cookies
- Redirecting users to the correct page
- Adding headers or lightweight modifications
- Handling A/B testing, feature flags, or geolocation-based routing
❌ What it’s not for:
- Fetching data from your database
- Performing heavy computations
- Running complex business logic
Why? Because Edge Runtime is not a full Node.js server. It doesn’t support filesystem access, TCP connections, or heavy processing it’s lightweight and fast, like a bouncer at the club door, not the bartender serving drinks.
How It’s Different from Express Middleware
Express middleware is flexible and full-powered: you can access databases, run computations, and call APIs directly.
Next.js Middleware (soon to be renamed Proxy) is specialized for routing and request manipulation.
So if you tried writing await db.query() inside Next.js Middleware, you’d get an error. That’s the main point of confusion.
Why the Name Change to Proxy Makes Sense
Calling it “Middleware” led many developers to assume it behaves like Express middleware which it doesn’t.
Next.js is now renaming it to Proxy, which is much clearer:
It proxies requests, checks headers, rewrites URLs, and redirects users.
It’s not a general-purpose server function.
This resolves the naming confusion and gives developers a better mental model of what this piece of code actually does.
Takeaways
- Next.js Middleware is lightweight, fast, and runs at the edge.
- It’s not a full server like Express middleware.
- The renaming to Proxy solves the mental model issue.
- Use it for routing, headers, redirects, and auth checks, but not heavy computations or DB queries.
Top comments (0)