Next.js Rewrites: Everything You Need to Know

In the dynamic world of web development, the ability to control and manipulate incoming requests is crucial for creating efficient, user-friendly applications. Next.js, a leading React framework, offers a powerful feature known as rewrites, which allows developers to intercept and modify requests to their server.

In this blog, you'll gain a comprehensive understanding of Next.js rewrites, how they differ from middleware, and how they can be configured to optimize your web applications.

What Are Next.js Rewrites?

Rewrites in Next.js are a set of server-side rules that define how incoming requests should be handled. They enable you to map an incoming request path to a different destination path, effectively allowing you to create clean, user-friendly URLs, proxy requests to external services, and manage client side routing without changing your file structure.

What Does NextResponse Rewrite Do?

NextResponse is a core component of Next.js that provides a set of methods to control the response sent back to the user. When you use a rewrite, NextResponse intercepts the incoming request and redirects it to the specified destination. This process is transparent to the user, ensuring a seamless experience as they navigate your application.

The Difference Between Next.js Middleware and Rewrites

While both middleware and rewrites can manipulate requests, they serve different purposes. Middleware allows you to execute code before a request is completed, allowing you to modify the request or response, or even introduce additional logic like authentication. On the other hand, rewrites are specifically designed to alter the path of an incoming request, directing it to a different destination without any additional processing.

What Does next.config.js Do?

The next.config.js file is the heart of your Next.js application's configuration. It's where you define settings such as build options, environment variables, and, importantly, your rewrites configuration. By setting up rules in next.config.js, you instruct Next.js on how to handle various incoming requests, ensuring that they are routed to the correct pages or external resources.

How to Configure Rewrites in Next.js

To implement rewrites, you need to modify the next.config.js file in your project. Here's an example of how to define a simple rewrite:

Copy
1
2
3
4
5
6
7
8
9
10
module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-path',
        destination: '/new-path',
      },
    ];
  },
};

In the above example, any request to /old-path will be rewritten to /new-path. This rewrite is automatically prefixed with your application's basepath if you've configured one.

Working with Async Rewrites

Async rewrites provide the flexibility to perform asynchronous operations before defining the rewrite rules. This is particularly useful when you need to fetch data or perform other asynchronous tasks to determine the destination path.

Copy
1
2
3
4
5
6
7
8
9
10
11
module.exports = {
  async rewrites() {
    const dynamicDestination = await fetchDestinationPath();
    return [
      {
        source: '/dynamic-path',
        destination: dynamicDestination,
      },
    ];
  },
};

Handling Wildcard and Regex Paths

Next.js rewrites support both wildcard path and regex path patterns, allowing for more complex matching scenarios. Wildcard paths are useful for matching nested paths, while regex paths offer even greater control over the incoming request path pattern.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
module.exports = {
  async rewrites() {
    return [
      // Wildcard path example
      {
        source: '/blog/:slug*',
        destination: '/news/:slug*',
      },
      // Regex path example
      {
        source: '/product/:id(\d{1,})',
        destination: '/store/:id',
      },
    ];
  },
};

Redirects vs. Rewrites

It's important to distinguish between redirects and rewrites. Redirects inform the client side that the requested URL has changed, resulting in an HTTP redirect status. Rewrites, however, handle the request server-side, and the user's browser URL remains unchanged.

Advanced Rewrite Techniques

As you become more comfortable with rewrites, you can start to leverage their full potential by implementing advanced techniques such as conditional rewrites, handling static files, and incrementally adopting external services.

Conditional Rewrites

You can use conditions within your async function to apply different rewrites based on the incoming request. This is particularly useful for A/B testing or feature flagging.

Static Files and External URLs

Rewrites can also be used to serve static files from a different destination path or to proxy requests to external URLs. This is useful when integrating with third-party services or when you're incrementally adopting a new backend.

Incrementally Adopting Next.js

For teams transitioning to Next.js, rewrites offer a way to incrementally adopt the framework by redirecting certain paths to a Next.js application while keeping other parts of the application on a legacy system, or even on a different domain. This approach minimizes disruption and allows for a smoother transition.

Practical Examples of Next.js Rewrites

To solidify your understanding, let's explore some practical examples of rewrites. These examples will demonstrate how to handle various scenarios, from simple path changes to more complex conditional logic.

Example: Basic Path Rewrite

Here's a basic example of a rewrite that maps an old blog post URL to a new one:

Copy
1
2
3
4
5
6
7
8
9
10
module.exports = {
  async rewrites() {
    return [
      {
        source: '/old-blog/hello-world',
        destination: '/new-blog/hello-world',
      },
    ];
  },
};

In this example, a request to /old-blog/hello-world will be served by the page at /new-blog/hello-world.

Example: Proxying an External API

Next.js rewrites can also proxy requests to an external API, hiding the API's URL from the client:

Copy
1
2
3
4
5
6
7
8
9
10
module.exports = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://external-api.com/:path*',
      },
    ];
  },
};

Requests to /api/some-endpoint will be proxied to https://external-api.com/some-endpoint , but the user's browser will still display the original path.

Example: Rewrites with Query Parameters

You can also use rewrites to include query parameters in the destination URL:

Copy
1
2
3
4
5
6
7
8
9
10
module.exports = {
  async rewrites() {
    return [
      {
        source: '/shop/:product',
        destination: '/store?item=:product',
      },
    ];
  },
};

A request to /shop/shoes will be rewritten to /store?item=shoes, passing the product name as a query parameter.

Best Practices for Using Next.js Rewrites

When implementing rewrites, there are several best practices to keep in mind:

• Keep It Simple: Start with the simplest rewrite rules possible and only add complexity when necessary.

• Test Thoroughly: Ensure that your rewrites work as expected by testing them in both development and production environments.

• Document Your Rules: Maintain clear documentation of your rewrite rules to make it easier for other developers to understand and maintain them.

• Monitor Performance: Keep an eye on the performance impact of your rewrites, especially when proxying external URLs or performing complex path matching.

Conclusion

Next.js rewrites are a powerful tool for managing incoming requests and optimizing the routing of your web application. By understanding how to configure and use rewrites, you can create more efficient, user-friendly experiences without compromising on performance or scalability.

Whether you're handling static files, proxying requests to external services, or simply cleaning up URLs, Next.js rewrites offer the flexibility and control you need to build top-notch web applications. So go ahead, experiment with rewrites, and take your Next.js projects to the next level!