Next.js & Middleware: A Beginner’s Guide to Request Handling

Written by

learnmodernwebdevelopment

in

In the ever-evolving world of web development, creating efficient, scalable, and secure applications is paramount. Next.js, a powerful React framework, provides developers with a robust toolkit to achieve these goals. One of its most versatile features is middleware, a mechanism that intercepts and processes requests before they reach your application’s routes. This tutorial will delve into Next.js middleware, exploring its functionalities, use cases, and how to implement it effectively. We’ll cover everything from the basics to more advanced techniques, equipping you with the knowledge to handle requests like a pro.

What is Middleware?

Middleware, in the context of web development, is a piece of code that sits between the client (e.g., a web browser) and the server (your Next.js application). It intercepts incoming requests, allowing you to perform actions before the request is handled by your application’s routes. Think of it as a gatekeeper, inspecting and modifying requests before they reach their destination. This allows you to implement a wide range of functionalities, such as authentication, authorization, request logging, and more.

Why Use Middleware?

Middleware offers several advantages that make it a valuable tool in your development arsenal:

  • Centralized Logic: It allows you to apply logic globally to all or a subset of requests, avoiding code duplication.
  • Request Modification: You can modify incoming requests, such as adding headers, changing the URL, or rewriting the request path.
  • Response Handling: You can modify or even completely replace the response before it’s sent back to the client.
  • Security: Implement security measures like authentication, authorization, and rate limiting.
  • Performance: Optimize performance by caching responses or redirecting requests.

Setting Up Your Next.js Project

Before diving into middleware, let’s set up a basic Next.js project. If you already have one, feel free to skip this step.

  1. Create a new Next.js project: Open your terminal and run the following command:
npx create-next-app my-middleware-app
  1. Navigate to your project directory:
cd my-middleware-app
  1. Start the development server:
npm run dev

This will start your Next.js development server, typically on http://localhost:3000. You should see the default Next.js welcome page.

Creating Your First Middleware

In Next.js, middleware resides in the `middleware.ts` or `middleware.js` file, located in the `src` directory (if you’re using the app router). If you’re using the pages router, middleware goes in the root directory. Let’s create a simple middleware that logs the request method and URL.

  1. Create the middleware file: Create a file named `middleware.ts` or `middleware.js` in your `src` directory (app router) or your project’s root directory (pages router).
  2. Add the following code to the file:
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

// This function can be marked `async` if using `await` inside
export function middleware(request: NextRequest) {
  console.log('Middleware running: ', request.method, request.url);

  return NextResponse.next();
}

// See "Matching Paths" below to learn more
export const config = {
  matcher: '/:path*',
};

Let’s break down this code:

  • Import statements: We import `NextResponse` and `NextRequest` from `next/server`. These are essential for interacting with the request and response objects.
  • `middleware` function: This is the core of your middleware. It receives a `NextRequest` object, which contains information about the incoming request.
  • `console.log()`: This line logs the request method (e.g., GET, POST) and URL to the server console. This is a simple example of how you can inspect the request.
  • `NextResponse.next()`: This is crucial. It tells Next.js to continue processing the request and pass it to the next handler (either another middleware or your route handler). Without this, the request would be blocked.
  • `config` object: This object configures the middleware’s behavior. The `matcher` property specifies which paths the middleware should apply to. In this example, `/:path*` means the middleware will run for all paths.

Now, when you visit any page in your application, you should see the request method and URL logged in your terminal.

Common Use Cases for Middleware

Middleware is incredibly versatile. Here are some common use cases:

1. Authentication and Authorization

One of the most frequent uses of middleware is to handle authentication and authorization. You can check for a valid authentication token in the request headers, redirect unauthorized users to a login page, and protect specific routes.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token');
  const isAuthRoute = request.nextUrl.pathname.startsWith('/auth');

  if (isAuthRoute && token) {
    return NextResponse.redirect(new URL('/', request.url)); // Redirect authenticated users from /auth
  }

  if (!isAuthRoute && !token) {
    return NextResponse.redirect(new URL('/auth/login', request.url)); // Redirect unauthenticated users
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/profile', '/auth/:path*'],
};

In this example:

  • We retrieve an authentication token from the request cookies.
  • We check if the user is trying to access an authentication route (e.g., login, register) and if they are already authenticated. If so, we redirect them to the home page.
  • We check if the user is trying to access a protected route (e.g., dashboard, profile) and if they are not authenticated. If not, we redirect them to the login page.
  • The `matcher` configures the middleware to run on specific paths (dashboard, profile, and auth routes).

2. URL Rewrites and Redirects

Middleware can rewrite URLs or redirect users to different pages. This is useful for SEO, handling legacy URLs, or creating user-friendly paths.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname === '/old-page') {
    return NextResponse.redirect(new URL('/new-page', request.url));
  }

  if (request.nextUrl.pathname.startsWith('/blog/post/')) {
    const slug = request.nextUrl.pathname.replace('/blog/post/', '');
    return NextResponse.rewrite(new URL(`/blog/${slug}`, request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/old-page', '/blog/post/:path*'],
};

Here’s how it works:

  • If a user tries to access `/old-page`, they are redirected to `/new-page`.
  • If a user accesses a URL like `/blog/post/my-article`, the URL is rewritten to `/blog/my-article`. This is useful for cleaner URLs.

3. Request Logging

Logging requests is essential for debugging and monitoring your application. Middleware provides a convenient place to log information about each request.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const startTime = Date.now();

  const response = NextResponse.next();

  const endTime = Date.now();
  const duration = endTime - startTime;

  console.log(`${request.method} ${request.url} - ${duration}ms`);

  return response;
}

export const config = {
  matcher: '/:path*',
};

In this example:

  • We record the start time before the request is processed.
  • We call `NextResponse.next()` to allow the request to continue.
  • We record the end time after the response is generated.
  • We calculate the duration and log the request method, URL, and the processing time.

4. Header Manipulation

You can add, modify, or remove headers from requests and responses using middleware. This is useful for setting security headers, controlling caching, or providing information to downstream services.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  response.headers.set('X-Custom-Header', 'My Custom Value');
  response.headers.append('Cache-Control', 's-maxage=10, stale-while-revalidate');
  return response;
}

export const config = {
  matcher: '/:path*',
};

This middleware adds a custom header and sets a cache-control header to the response.

5. Rate Limiting

Protect your application from abuse by implementing rate limiting using middleware. This involves tracking the number of requests from a specific IP address within a certain time window and blocking requests that exceed a defined limit.

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

const MAX_REQUESTS = 10;
const WINDOW_MS = 60 * 1000; // 1 minute
const requestCounts: { [ip: string]: { count: number; reset: number } } = {};

export function middleware(request: NextRequest) {
  const ip = request.ip || '127.0.0.1'; // Fallback for local development
  const now = Date.now();

  if (!requestCounts[ip]) {
    requestCounts[ip] = { count: 1, reset: now + WINDOW_MS };
  } else {
    if (now > requestCounts[ip].reset) {
      requestCounts[ip] = { count: 1, reset: now + WINDOW_MS };
    } else {
      requestCounts[ip].count++;
    }
  }

  if (requestCounts[ip].count > MAX_REQUESTS) {
    return new NextResponse(
      'Too Many Requests', {
        status: 429,
        headers: {
          'Retry-After': Math.ceil((requestCounts[ip].reset - now) / 1000).toString(),
        },
      }
    );
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/api/:path*',
};

In this example:

  • We track the number of requests from each IP address.
  • We reset the request count after a specified time window.
  • If the request count exceeds the limit, we return a 429 Too Many Requests response with a Retry-After header.

Understanding the `matcher` Configuration

The `matcher` configuration is crucial for controlling which paths your middleware applies to. It uses a simplified path-matching syntax.

  • `/`: Matches the root path.
  • `/:path*`: Matches all paths.
  • `/about`: Matches the exact path `/about`.
  • `/blog/:slug`: Matches paths like `/blog/my-article`. The `:slug` is a dynamic segment.
  • `/api/:path*`: Matches all paths under the `/api` directory.

You can use an array of matchers to apply the middleware to multiple paths.

export const config = {
  matcher: ['/about', '/contact', '/api/:path*'],
};

This middleware will run for the `/about` and `/contact` pages and all API routes.

Common Mistakes and How to Fix Them

Here are some common mistakes developers make when working with Next.js middleware and how to avoid them:

1. Forgetting `NextResponse.next()`

The most common mistake is forgetting to call `NextResponse.next()`. If you don’t call this, the request will be blocked, and your application won’t function as expected. Always ensure you include `NextResponse.next()` unless you specifically want to short-circuit the request.

2. Incorrect Path Matching

Carefully review your `matcher` configuration to ensure it matches the paths you intend. Typos or incorrect patterns can lead to the middleware not running on the expected routes or running on too many routes, causing unexpected behavior.

3. Infinite Redirect Loops

Be cautious when using redirects. If your middleware redirects a request to a path that also triggers the middleware, you could create an infinite loop. Always consider the potential for loops and add appropriate checks to prevent them.

4. Performance Issues

Middleware runs on every request that matches its path. Therefore, complex or computationally expensive operations within the middleware can impact performance. Optimize your middleware code and consider caching results where appropriate.

5. Not Considering Edge Cases

Thoroughly test your middleware to cover all possible scenarios, including edge cases. Consider what happens when the user is not authenticated, when an API request fails, or when the server is under heavy load.

Step-by-Step Implementation Guide

Let’s walk through a more complex example: implementing authentication using middleware. This example will demonstrate how to protect routes and redirect unauthenticated users.

1. Project Setup

If you don’t already have one, create a Next.js project as described earlier.

2. Create Auth Pages (Optional)

If you don’t have authentication pages, create basic login and registration pages. These are not strictly necessary for the middleware example, but they’re useful for testing.

3. Implement Authentication Logic (Simplified)

For simplicity, we’ll simulate authentication using a cookie. In a real-world scenario, you would integrate with a proper authentication provider (e.g., Auth0, Firebase Authentication, or your own backend).

Create a file (e.g., `lib/auth.ts`) to manage authentication functions:

// lib/auth.ts

export const setAuthCookie = (token: string) => {
  document.cookie = `auth-token=${token}; path=/`;
};

export const removeAuthCookie = () => {
  document.cookie = 'auth-token=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT';
};

export const getAuthToken = () => {
  const cookies = document.cookie.split(';');
  for (const cookie of cookies) {
    const [name, value] = cookie.trim().split('=');
    if (name === 'auth-token') {
      return value;
    }
  }
  return null;
};

This code provides functions to set, remove, and get the authentication token from a cookie. Note: This is an example for demonstration purposes only. For production, use secure HTTP-only cookies and implement proper CSRF protection.

4. Create Protected Pages

Create a protected page (e.g., `/dashboard`) that requires authentication. In `app/dashboard/page.tsx` (using app router):

// app/dashboard/page.tsx

"use client";

import { useEffect } from 'react';
import { useRouter } from 'next/navigation';
import { getAuthToken } from '../../lib/auth';

export default function DashboardPage() {
  const router = useRouter();

  useEffect(() => {
    const authToken = getAuthToken();
    if (!authToken) {
      router.push('/auth/login'); // Redirect to login if not authenticated
    }
  }, [router]);

  return (
    <div>
      <h2>Dashboard</h2>
      <p>Welcome to your dashboard!</p>
    </div>
  );
}

This dashboard page uses a client-side check to ensure the user is authenticated. This is a fallback in case the middleware fails.

5. Implement the Middleware

Now, create the `middleware.ts` file in your `src` directory (app router) or project root (pages router) and add the following code:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token');
  const isAuthRoute = request.nextUrl.pathname.startsWith('/auth');

  if (isAuthRoute && token) {
    return NextResponse.redirect(new URL('/', request.url)); // Redirect authenticated users from /auth
  }

  if (!isAuthRoute && !token) {
    return NextResponse.redirect(new URL('/auth/login', request.url)); // Redirect unauthenticated users
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/profile', '/auth/:path*'],
};

This middleware:

  • Checks for the `auth-token` cookie.
  • If the user is trying to access an authentication route and is already authenticated, redirect to the home page.
  • If the user is not authenticated and is trying to access a protected route (e.g., dashboard, profile), redirect to the login page.
  • The `matcher` configures the middleware to run on specific paths.

6. Test Your Implementation

Start your Next.js development server and test the following scenarios:

  • Unauthenticated user trying to access `/dashboard`: The user should be redirected to the login page.
  • Unauthenticated user trying to access `/auth/login`: The user should be able to access the login page.
  • Authenticated user trying to access `/dashboard`: The user should be able to access the dashboard.
  • Authenticated user trying to access `/auth/login`: The user should be redirected to the home page.

By testing these scenarios, you can verify that your middleware is working as expected.

Key Takeaways

  • Middleware is a powerful feature in Next.js that allows you to intercept and process requests.
  • Common use cases include authentication, authorization, URL rewriting, and request logging.
  • The `matcher` configuration controls which paths the middleware applies to.
  • Always include `NextResponse.next()` unless you want to short-circuit the request.
  • Test your middleware thoroughly to cover all scenarios and edge cases.

FAQ

  1. What is the difference between middleware and API routes?
    • Middleware runs before your API routes and allows you to intercept and modify requests before they reach your API handlers. API routes handle the actual logic for responding to specific API requests.
  2. Can I use middleware with static site generation (SSG)?
    • Yes, middleware works with SSG. However, middleware runs on the server (or edge functions in Vercel) for every request, even for statically generated pages.
  3. How can I debug middleware?
    • Use `console.log()` statements to log information about the request. You can also use the debugger in your browser or the server console to step through your middleware code.
  4. What is the best practice for storing sensitive information in middleware?
    • Avoid storing sensitive information directly in your middleware code. Instead, use environment variables to store secrets and access them within your middleware.
  5. Can I use third-party libraries in middleware?
    • Yes, you can import and use third-party libraries in your middleware. However, be mindful of the size of your middleware bundle, as it can impact performance.

Middleware in Next.js offers a flexible and efficient way to handle requests, allowing you to build more robust and feature-rich applications. With a solid understanding of its capabilities and best practices, you can leverage middleware to improve the security, performance, and overall user experience of your Next.js projects. Mastering middleware is a significant step towards becoming a more proficient Next.js developer, equipping you with the tools to tackle complex challenges and create exceptional web applications.

More posts