Understanding Next.js Rewrites

Most people use Next.js very superficially. Routing, SSR, maybe API routes — and that’s it. But...

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.