Next.js middleware offers powerful customization for request handling within your application. It allows interception of requests to perform actions like session validation, logging, and caching. However, inefficient middleware implementation can severely impact performance. This guide clarifies middleware functionality and best practices, helping you understand when and how to leverage it effectively.

What is Next.js Middleware?

Next.js middleware comprises functions automatically executed for each incoming request. These functions inspect and modify request data before it reaches your application's routing system. Applications include authentication, logging, and error management. For example, middleware can validate user sessions by checking tokens, preventing unauthorized access.

Next.js middleware is highly flexible and customizable. You can create tailored functions to meet specific application needs, setting application-wide settings or policies. This simplifies routing configuration, avoiding complex multi-layered setups. Using middleware results in more robust, scalable, and maintainable applications.

Next.js Middleware Processing Order

Understanding the order of operations when a request is received is crucial:

1. Headers: next.config.js headers are applied first, setting initial request headers. This is ideal for security headers like Content Security Policy (CSP) or CORS.

2. Redirects: next.config.js redirects are processed next, mapping requests to different URLs. This handles URL rewriting and redirects, managing routing rules across pages or the entire application.

3. Middleware Evaluation: After headers and redirects, middleware is evaluated and its logic executed.

4. beforeFiles: next.config.js beforeFiles (rewrites) are applied, enabling further rewriting or file-specific logic before routing.

5. File System Routes: The application's file system routes are processed (e.g., public/, _next/static/, pages, and apps). Static files are served here.

6. afterFiles: next.config.js afterFiles (rewrites) are applied, offering a final modification point before dynamic routing.

7. Dynamic Routes: Dynamic routes (e.g., /blog/[slug]) are handled. These require specific handling and rewriting for variables or parameters.

8. Fallback: next.config.js fallback is applied, managing requests that cannot be routed otherwise. This allows for error handlers or fallback routes.

Common Next.js Middleware Use Cases

• Authentication: Validate user credentials before accessing protected resources. Middleware can check session tokens, redirecting unauthenticated users to login. Clerk uses this approach effectively.

• Logging: Track application events (user actions, errors) by logging each request to a central server for analysis and debugging.

• Data Fetching: (With limitations) Load data from APIs or databases for up-to-date information. Note the performance considerations discussed later.

• Request Routing: Customize routing, redirecting requests to specific paths or implementing catch-all error handlers.

• Caching: Improve performance by storing frequently accessed resources in memory, reducing requests. (Example code provided in original text)

• Rate Limiting: Monitor requests from users or IP addresses, blocking excessive requests to protect backend resources.

• Page Transforms: Rewrite HTML or transform data in real time. This is useful for image URL rewriting or serving assets from different domains.

• Analytics/Reporting: Track user behavior and application performance for optimization. Middleware can modify cookies for third-party analytics integration.

• Internationalization: Deliver content in multiple languages based on user locale (e.g., using IP address or HTTP headers).

Using Middleware in a Next.js Project

Middleware is implemented by creating a middleware.ts file at the project root. This file defines a middleware function and (optionally) a matcher.

The Middleware Function

The middleware function contains the middleware logic. It takes a request as input and returns a response.

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

export function middleware(request: NextRequest) {
  // Middleware logic here
  return NextResponse.next()
}

Example redirecting requests to /dashboard unless they start with /api:

export function middleware(request: NextRequest) {
  if (!request.nextUrl.pathname.startsWith('/api')) {
    return NextResponse.redirect(new URL('/dashboard', request.url))
  }
  return NextResponse.next()
}

The function must return: NextResponse.next(), NextResponse.redirect(), NextResponse.rewrite(), NextResponse.json(), or a custom Response/NextResponse.

The Matcher

The matcher determines which requests are processed by the middleware. It's defined in the config object:

export const config = {
  matcher: '/hello', // Matches only /hello
}

You can use arrays for multiple routes or regular expressions for more complex matching:

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

export function middleware(request: NextRequest) {
  // Middleware logic here
  return NextResponse.next()
}

Without a matcher, middleware applies to all routes, potentially impacting performance.

Combining Multiple Middleware Functions

Next.js supports only one middleware file. To use multiple functions, create separate functions and call them sequentially, returning a response if one is generated:

export function middleware(request: NextRequest) {
  if (!request.nextUrl.pathname.startsWith('/api')) {
    return NextResponse.redirect(new URL('/dashboard', request.url))
  }
  return NextResponse.next()
}

Clerk and Next.js Middleware

Clerk simplifies authentication by providing clerkMiddleware:

export const config = {
  matcher: '/hello', // Matches only /hello
}

This handles cookie parsing and user verification. You can extend it with custom logic:

export const config = {
  matcher: ['/hello', '/world', '/[a-zA-Z]+/'], // Matches multiple routes and regex
}

Limitations of Next.js Middleware

• Edge Runtime Constraints: Middleware runs on the Edge Runtime, limiting available APIs and libraries. File system access is not allowed.

• Size Restriction: Middleware functions are limited to 1MB.

• ES Modules Only: Only ES modules are supported.

• No String Evaluation: eval and new Function(evalString) are disallowed.

• Performance Considerations: Complex middleware can negatively impact performance. Database access within middleware is generally discouraged.

• Limited Access to Request/Response: Middleware doesn't have full access to request and response objects.

Conclusion

This guide provides a comprehensive understanding of Next.js middleware, its capabilities, limitations, and best practices. Remember to prioritize efficient code to avoid performance bottlenecks.

The above is the detailed content of What is middleware in Next.js. For more information, please follow other related articles on the PHP Chinese website!