Understanding Next.js Rewrites

 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.