Redirects and Rewrites for URL Management | Pages and Routing: Navigating Your Application | Next.js: A Practical Introduction for Developers

In any web application, managing URLs effectively is crucial for user experience and SEO. Next.js provides powerful tools, namely redirects and rewrites, to control how incoming requests are handled and what content is served. Understanding the difference between these two mechanisms will allow you to build more robust and user-friendly applications.

Redirects: Telling the Browser to Go Elsewhere

Redirects are primarily for informing the browser that a resource has moved to a new location. When a redirect occurs, the browser receives a status code (like 301 for permanent or 302 for temporary) and is instructed to make a new request to the specified URL. This means the original URL is no longer considered the authoritative source for the content.

Redirects are configured in the next.config.js file within the redirects array. Each redirect object needs a source (the incoming path) and a destination (the new path). You can also specify a statusCode (defaults to 307).

module.exports = {
  async redirects() {
    return [
      {
        source: '/old-page',
        destination: '/new-page',
        statusCode: 301,
      },
      {
        source: '/users/:id',
        destination: '/profile/:id',
        statusCode: 302,
      },
    ];
  },
};

In this example, requests to /old-page will be permanently redirected to /new-page. Requests to /users/123 will be temporarily redirected to /profile/123. The :id is a path parameter that gets passed along.

graph TD;
  A[Browser Request to /old-page] --> B{Next.js Config};
  B --> C[Redirect Rule Found];
  C --> D[Send 301 Status Code];
  D --> E[Browser Requests /new-page];
  E --> F[Next.js Serves /new-page];

Rewrites: Masking One URL with Another

Rewrites, on the other hand, are for internal URL manipulation. When a rewrite occurs, the browser's URL in the address bar remains the same, but Next.js internally handles the request by serving content from a different path. This is useful for creating cleaner URLs, implementing API routes that map to specific pages, or serving content from a different directory without changing the user-facing URL.

Rewrites are also configured in next.config.js using the rewrites function. Similar to redirects, they have a source and a destination.

module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/hello',
        destination: '/pages/api/hello.js',
      },
      {
        source: '/docs/:slug*',
        destination: '/documentation/:slug*',
      },
    ];
  },
};

Here, a request to /api/hello will serve the content of /pages/api/hello.js without changing the URL. A request to /docs/introduction/getting-started will internally serve /documentation/introduction/getting-started, keeping the /docs/ URL visible to the user. The * is a wildcard for matching multiple path segments.

graph TD;
  A[Browser Request to /api/hello] --> B{Next.js Middleware};
  B --> C[Rewrite Rule Found];
  C --> D[Internally Serve /pages/api/hello.js];
  D --> E[Browser URL Remains /api/hello];
  E --> F[Next.js Returns Content of /pages/api/hello.js];

Key Differences Summarized

The fundamental difference lies in how the browser is informed:

Redirects: Tell the browser to navigate to a different URL. The browser makes a new request, and the URL in the address bar changes. Indicated by HTTP status codes like 301 or 302.
Rewrites: Handle URL requests internally within Next.js. The browser's URL remains the same, and the user is unaware that a different file or route is being served. These typically result in a 200 OK status code.

When to Use Which

Use Redirects when:
- A page or resource has permanently or temporarily moved.
- You want to enforce a canonical URL (e.g., redirecting example.com to www.example.com).
- You are migrating from an old URL structure.
- SEO is a concern, and you want search engines to update their index.

Use Rewrites when:
- You want to create user-friendly, semantic URLs that map to internal file paths.
- You are building an API layer using Next.js pages (e.g., /api/*).
- You need to serve content from a different directory structure without affecting the user's URL.
- You want to provide a single, consistent URL for different versions of content or for A/B testing.

By mastering redirects and rewrites in Next.js, you gain fine-grained control over your application's URL management, leading to a better experience for both your users and search engines.

module.exports = { async redirects() { return [ { source: '/old-page', destination: '/new-page', statusCode: 301, }, { source: '/users/:id', destination: '/profile/:id', statusCode: 302, }, ]; }, };

graph TD; A[Browser Request to /old-page] --> B{Next.js Config}; B --> C[Redirect Rule Found]; C --> D[Send 301 Status Code]; D --> E[Browser Requests /new-page]; E --> F[Next.js Serves /new-page];

module.exports = { async rewrites() { return [ { source: '/api/hello', destination: '/pages/api/hello.js', }, { source: '/docs/:slug*', destination: '/documentation/:slug*', }, ]; }, };

graph TD; A[Browser Request to /api/hello] --> B{Next.js Middleware}; B --> C[Rewrite Rule Found]; C --> D[Internally Serve /pages/api/hello.js]; D --> E[Browser URL Remains /api/hello]; E --> F[Next.js Returns Content of /pages/api/hello.js];