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 (0)