Understanding Middleware in Next.js: Concept and Example

Middleware is an integral part of web development that enables developers to manage requests and responses before they reach the final destination. In the context of Next.js, middleware provides a way to execute code during the request lifecycle, allowing you to manipulate requests and responses, perform logging, authentication checks, and more. This article will explore the concept of middleware in Next.js and provide an example of how to use it to handle requests effectively.

What is Middleware in Next.js?

Middleware in Next.js is a function that runs before the final request handler. It intercepts requests and responses, providing a way to modify or handle them before they reach the actual API route or page. This concept is particularly useful for tasks such as authentication, logging, rate limiting, and data validation.

Key Characteristics of Middleware in Next.js

Middleware in Next.js plays a crucial role in handling requests and responses, providing a layer of control and customization in the request lifecycle. Here are the key characteristics of middleware in Next.js:

• Interception: Middleware functions intercept requests and responses before they reach the final destination, such as API routes or pages. This allows for early manipulation and decision-making.

• Modularity: Middleware enables a modular approach to handling common functionalities. By defining reusable middleware functions, you can apply consistent logic across multiple routes and pages.

• Reusability: Middleware functions can be reused across different parts of the application. For example, an authentication middleware can be applied to multiple protected routes, ensuring consistent access control.

• Chainable: Multiple middleware functions can be chained together to handle different aspects of a request. This allows for a clean separation of concerns and a structured way to manage request processing.

• Conditional Execution: Middleware can conditionally execute based on the request's characteristics, such as URL patterns, headers, or cookies. This makes it flexible for applying specific logic only when certain conditions are met.

• Early Termination: Middleware can terminate the request-response cycle early if certain conditions are not met. For example, an authentication middleware can redirect unauthenticated users to a login page without proceeding further.

• Custom Response Handling: Middleware can modify responses by adding custom headers, changing status codes, or altering response bodies. This allows for a high degree of customization in how responses are delivered to clients.

• Cross-Cutting Concerns: Middleware is ideal for handling cross-cutting concerns, such as logging, error handling, and security checks, which need to be applied across multiple routes and pages.

• Seamless Integration: Middleware in Next.js integrates seamlessly with the framework, leveraging its server-side capabilities and fitting naturally into the routing and request handling mechanisms.

Example Middleware in Next.js

To illustrate these characteristics, here’s an example of middleware in Next.js that handles authentication and logging:

// pages/_middleware.js

import { NextResponse } from "next/server";

export function middleware(req) {
  const { pathname } = req.nextUrl;

  // Authentication check
  if (pathname.startsWith("/protected") && !req.cookies.auth) {
    return NextResponse.redirect("/login");
  }

  // Logging the request URL
  console.log(`Request to: ${pathname}`);

  // Adding a custom header to the response
  const response = NextResponse.next();
  response.headers.set("X-Custom-Header", "my-custom-header");

  return response;
}

How Middleware Works in Next.js

In Next.js, middleware functions are typically defined in the pages/_middleware.js file or within specific API routes. Middleware can be applied globally to all routes or to individual API routes as needed. Middleware in Next.js offers a versatile and powerful way to manage and customize request and response handling. By leveraging middleware, developers can implement a wide range of functionalities such as authentication, logging, rate limiting, custom headers, redirection, content localization, security checks, A/B testing, request transformation, and caching. These use cases demonstrate the flexibility and importance of middleware in building robust and scalable Next.js applications.

Use Cases for Middleware in Next.js

• Authentication and Authorization: Checking if a user is authenticated before accessing certain routes. If not authenticated, redirect them to the login page.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const { pathname } = req.nextUrl;
  
    if (pathname.startsWith("/protected") && !req.cookies.auth) {
      return NextResponse.redirect("/login");
    }
  
    return NextResponse.next();
  }
  

• Logging: Logging incoming requests for monitoring and debugging purposes.

  // pages/_middleware.js
  export function middleware(req) {
    console.log(`Request to: ${req.nextUrl.pathname}`);
    return NextResponse.next();
  }
  

• Rate Limiting: Limiting the number of requests a user can make to an API endpoint within a given timeframe to prevent abuse.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  const rateLimit = (req, res) => {
    // Rate limiting logic here
    // For example, using an in-memory store or a database
  };
  
  export function middleware(req) {
    if (rateLimit(req)) {
      return NextResponse.next();
    } else {
      return new NextResponse("Too many requests", { status: 429 });
    }
  }
  

• Custom Headers: Adding custom headers to responses for security, caching, or other purposes.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const response = NextResponse.next();
    response.headers.set("X-Custom-Header", "my-custom-header");
    return response;
  }
  

• Redirection: Redirecting users based on certain conditions, such as outdated URLs or geographical location.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const { pathname } = req.nextUrl;
  
    if (pathname === "/old-path") {
      return NextResponse.redirect("/new-path");
    }
  
    return NextResponse.next();
  }
  

• Content Localization: Serving different content based on the user's locale or language preference.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const locale = req.cookies.locale || "en";
    req.nextUrl.locale = locale;
    return NextResponse.next();
  }
  

• Security Checks: Performing security checks such as validating API keys or tokens before processing the request.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const apiKey = req.headers.get("x-api-key");
  
    if (!apiKey || apiKey !== "your-expected-api-key") {
      return new NextResponse("Unauthorized", { status: 401 });
    }
  
    return NextResponse.next();
  }
  

• A/B Testing: Implementing A/B testing by randomly assigning users to different versions of a page and tracking their behavior.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const experimentGroup = Math.random() > 0.5 ? "A" : "B";
    const response = NextResponse.next();
    response.headers.set("X-Experiment-Group", experimentGroup);
    return response;
  }
  

• Request Transformation: Modifying request data before it reaches the final handler, such as transforming request bodies or headers.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    if (req.nextUrl.pathname === "/api/transform") {
      req.headers.set("x-transformed-header", "transformed-value");
    }
    return NextResponse.next();
  }
  

• Caching: Implementing custom caching logic to improve performance by serving cached responses for certain requests.

  // pages/_middleware.js
  import { NextResponse } from "next/server";
  
  export function middleware(req) {
    const cache = getFromCache(req.nextUrl.pathname);
  
    if (cache) {
      return new NextResponse(cache);
    }
  
    const response = NextResponse.next();
    response.then((res) => saveToCache(req.nextUrl.pathname, res));
    return response;
  }
  
  function getFromCache(pathname) {
    // Custom cache retrieval logic
  }
  
  function saveToCache(pathname, response) {
    // Custom cache save logic
  }
  

Creating Middleware in Next.js Project

Setting Up a Next.js Project

First, create a new Next.js project if you don't already have one:

npx create-next-app@latest nextjs-middleware-example
cd nextjs-middleware-example

Defining Middleware

Create a _middleware.js file in the pages directory. This middleware will run for all routes under the pages directory.

// pages/_middleware.js

import { NextResponse } from "next/server";

export function middleware(req) {
  const { pathname } = req.nextUrl;

  // Example: Redirect to login if user is not authenticated
  if (pathname.startsWith("/protected") && !req.cookies.auth) {
    return NextResponse.redirect("/login");
  }

  // Example: Logging the request
  console.log(`Request to: ${pathname}`);

  // Example: Adding a custom header to the response
  const response = NextResponse.next();
  response.headers.set("X-Custom-Header", "my-custom-header");

  return response;
}

Applying Middleware to Specific Routes

If you only want to apply middleware to specific API routes, you can define it within the individual API route files.

// pages/api/protected-route.js

import { NextResponse } from "next/server";

export async function middleware(req, res) {
  if (!req.cookies.auth) {
    return NextResponse.redirect("/login");
  }
  return NextResponse.next();
}

export default function handler(req, res) {
  res.status(200).json({ message: "You have access to this protected route!" });
}

Testing the Middleware

To test the middleware, create a protected page and a login page.

// pages/protected.js

import { useEffect, useState } from 'react';

export default function Protected() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch('/api/protected-route')
      .then((res) => res.json())
      .then((data) => setData(data))
      .catch((err) => console.error('Error:', err));
  }, []);

  if (!data) return <p>Loading...</p>;

  return <p>{data.message}</p>;
}

// pages/login.js

export default function Login() {
  const handleLogin = () => {
    document.cookie = "auth=true; path=/";
    window.location.href = "/protected";
  };

  return (
    <div>
      <h1>Login Page</h1>
      <button onClick={handleLogin}>Log in</button>
    </div>
  );
}

Running the Application

Start the Next.js application:

npm run dev

Navigate to /protected. If you are not logged in, you should be redirected to the login page. After logging in, you should have access to the protected route.

NextJs FAQ

// pages/_middleware.js
import { NextResponse } from "next/server";

export function middleware(req) {
  const { pathname } = req.nextUrl;

  if (pathname.startsWith("/api")) {
    // Apply middleware logic only to API routes
    // Example: Check API key
    const apiKey = req.headers.get("x-api-key");
    if (!apiKey || apiKey !== "your-expected-api-key") {
      return new NextResponse("Unauthorized", { status: 401 });
    }
  }

  return NextResponse.next();
}

// pages/_middleware.js
import { NextResponse } from "next/server";

export function middleware(req) {
  try {
    // Middleware logic
    const response = NextResponse.next();
    return response;
  } catch (error) {
    console.error("Error:", error);
    return new NextResponse("Internal Server Error", { status: 500 });
  }
}

// pages/_middleware.js
import { NextResponse } from "next/server";
import jwt from "jsonwebtoken";

export function middleware(req) {
  const { pathname } = req.nextUrl;

  // Enforce HTTPS
  if (req.headers.get("x-forwarded-proto") !== "https") {
    return NextResponse.redirect(`https://${req.nextUrl.hostname}${pathname}`);
  }

  // Validate JWT token
  const token = req.cookies.jwt;
  if (
    pathname.startsWith("/protected") &&
    (!token || !jwt.verify(token, "your-secret-key"))
  ) {
    return NextResponse.redirect("/login");
  }

  // Add security headers
  const response = NextResponse.next();
  response.headers.set("Content-Security-Policy", "default-src 'self'");
  response.headers.set("X-Content-Type-Options", "nosniff");
  response.headers.set("X-Frame-Options", "DENY");

  return response;
}

// pages/_middleware.js
import { NextResponse } from "next/server";

export function middleware(req) {
  const { pathname } = req.nextUrl;

  // First middleware: Logging
  console.log(`Request to: ${pathname}`);

  // Second middleware: Authentication
  if (pathname.startsWith("/protected") && !req.cookies.auth) {
    return NextResponse.redirect("/login");
  }

  // Third middleware: Adding custom header
  const response = NextResponse.next();
  response.headers.set("X-Custom-Header", "my-custom-header");

  return response;
}

// __tests__/middleware.test.js
import { middleware } from "../pages/_middleware";
import { NextRequest, NextResponse } from "next/server";

test("redirects to login if not authenticated", () => {
  const req = new NextRequest("http://localhost/protected", {
    cookies: { auth: "" },
  });
  const response = middleware(req);
  expect(response).toEqual(NextResponse.redirect("/login"));
});

test("allows access if authenticated", () => {
  const req = new NextRequest("http://localhost/protected", {
    cookies: { auth: "valid-auth-cookie" },
  });
  const response = middleware(req);
  expect(response).toEqual(NextResponse.next());
});

test("logs requests", () => {
  console.log = jest.fn();
  const req = new NextRequest("http://localhost/");
  middleware(req);
  expect(console.log).toHaveBeenCalledWith("Request to: /");
});

Conclusion

Middleware in Next.js provides a powerful way to manage requests and responses. It allows developers to add functionality such as authentication, logging, and custom headers in a modular and reusable manner. By understanding and utilizing middleware effectively, you can enhance the security, performance, and maintainability of your Next.js applications.

In this article, we covered the concept of middleware, provided examples of common use cases, and demonstrated how to create and apply middleware in a Next.js project. By following these steps, you can implement robust middleware solutions to handle various aspects of request processing in your Next.js applications.

You can cheack out the expanded version of this aricle on my medium https://medium.com/@farihatulmaria/understanding-middleware-in-next-js-concept-and-example-96581e50389b