Most people use Next.js very superficially.
Routing, SSR, maybe API routes — and that’s it. But Next.js is not just a React framework; it’s a routing, request-handling, and application architecture layer. Many of its most powerful features live outside components and never touch JSX.
One of those features is rewrites.
Today, we’re talking about rewrites — what they are, how they work, and why they matter.
What is a Rewrite in Next.js?
A rewrite allows you to map an incoming request path to a different destination without changing the URL in the browser.
The user requests one URL.
Your application serves content from another.
The browser never knows.
This is fundamentally different from redirects.
Redirects tell the browser to make a new request.
Rewrites happen entirely inside Next.js.
Basic Rewrite Example
Rewrites are defined in next.config.js
module.exports = {
async rewrites() {
return [
{
source: '/blog/:slug',
destination: '/content/posts/:slug',
},
]
},
}
What happens here?
A user visits:
/blog/nextjs-rewrites
Next.js internally serves:
/content/posts/nextjs-rewrites
The browser URL remains /blog/nextjs-rewrites
No redirect. No reload. No visible change.
Why Rewrites Matter Architecturally
URLs are a public contract.
Once users, crawlers, or external systems depend on a URL, changing it becomes expensive. Rewrites let you preserve that contract while refactoring everything underneath.
This means:
you can change folder structures freely
you can reorganize routes without breaking links
you can evolve your app incrementally
API Proxying With Rewrites
One of the most practical uses of rewrites is API proxying.
module.exports = {
async rewrites() {
return [
{
source: '/api/:path*',
destination: 'https://external-service.com/:path*',
},
]
},
}
Now the frontend calls /api/users but the request is actually sent to https://external-service.com/users
Why this is powerful:
avoids CORS issues
keeps API keys server-side
creates a single API surface for the frontend
allows backend services to change without frontend changes
From the client’s perspective, everything lives under /api
Rewrites vs Redirects (Critical Difference)
Redirects:
change the browser URL
trigger a second request
are visible to the user
affect SEO
Rewrites:
keep the original URL
resolve internally
are invisible to the user
do not trigger navigation
If redirects are navigation tools, rewrites are infrastructure tools.
Rewrites and the Request Lifecycle
Rewrites run before routing.
This means:
Next.js evaluates rewrites first
then resolves the final route
then executes page or API logic
Because of this:
req.url may not reflect the final destination
middleware logic must be tested carefully
assumptions about paths can break if rewrites are ignored
This is one of the few “gotchas” with rewrites — they are powerful precisely because they’re invisible.
Conditional Rewrites
Rewrites can also be conditional.
Example based on headers:
{
source: '/dashboard',
has: [
{
type: 'header',
key: 'x-admin',
value: 'true',
},
],
destination: '/admin/dashboard',
}
Same URL. Different destination. Different behavior.
This enables:
role-based routing
multi-tenant applications
internal feature flags
environment-based routing
Why Rewrites Are Underrated
Rewrites don’t live in components.
They don’t affect UI.
They don’t announce themselves.
But they:
decouple URLs from implementation
enable safe refactors
turn Next.js into a lightweight gateway
push routing decisions closer to infrastructure
Once you understand rewrites, you stop thinking of URLs as file paths and start treating them as interfaces.
And that’s a shift that changes how you design applications.
Final Thought
Rewrites are not about convenience.
They’re about control.
They allow Next.js apps to grow, migrate, and evolve without breaking users or clients. If you’re building anything beyond a small project, rewrites are not optional — they’re foundational.
Most people never go past the surface of Next.js.
Rewrites are one of the first features that show you how deep it actually goes.
Top comments (2)
The API proxying use case is the one that sold me on rewrites. We had a project where the backend team kept changing API endpoints during development and it was driving the frontend devs crazy. Once we set up rewrites as a proxy layer, the frontend just hit
/api/whateverand we adjusted the destination in next.config.js. Zero frontend changes needed.One gotcha worth mentioning: if you're using rewrites for API proxying to external services, keep in mind that the rewrite happens server-side, so your Next.js server becomes a bottleneck for those requests. For high-traffic endpoints, you might want to handle that at the reverse proxy level (nginx/cloudflare) instead.
Also the conditional rewrites with headers are super interesting for feature flags. Have you tried combining them with middleware for more complex routing logic?
Really nice and insightful comment!
No, beyond trying out in a demo project, I have not really done it in a middleware. Have not had any use case. Can you share a case where you had to do it?