Middleware Pattern | Bootspring Docs

Implement request preprocessing, authentication, CORS, logging, and rate limiting using Next.js middleware for API routes.

Overview#

Middleware runs before requests are completed, allowing you to modify the response, redirect, rewrite, or add headers. It's ideal for authentication checks, logging, and request transformation across multiple routes.

When to use:

Authentication and authorization checks
Request logging and monitoring
CORS handling for API routes
Rate limiting implementation
Request/response header modification

Key features:

Runs at the edge for low latency
Executes before cached content
Can modify request and response
Path-based matching with matchers
Access to cookies and headers

Code Example#

Authentication Middleware#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { getToken } from 'next-auth/jwt'

const protectedPaths = ['/api/users', '/api/teams', '/api/billing']
const publicPaths = ['/api/auth', '/api/health', '/api/webhooks']

export async function middleware(request: NextRequest) {
  const path = request.nextUrl.pathname

  // Skip public paths
  if (publicPaths.some(p => path.startsWith(p))) {
    return NextResponse.next()
  }

  // Check auth for protected paths
  if (protectedPaths.some(p => path.startsWith(p))) {
    const token = await getToken({ req: request })

    if (!token) {
      return NextResponse.json(
        { error: { message: 'Unauthorized', code: 'UNAUTHORIZED' } },
        { status: 401 }
      )
    }

    // Add user info to headers for route handlers
    const requestHeaders = new Headers(request.headers)
    requestHeaders.set('x-user-id', token.sub!)
    requestHeaders.set('x-user-role', token.role as string)

    return NextResponse.next({
      request: { headers: requestHeaders }
    })
  }

  return NextResponse.next()
}

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

CORS Middleware#

// middleware.ts
const allowedOrigins = [
  'https://app.example.com',
  'https://admin.example.com'
]

function corsMiddleware(request: NextRequest) {
  const origin = request.headers.get('origin')
  const isAllowed = origin && allowedOrigins.includes(origin)

  // Handle preflight
  if (request.method === 'OPTIONS') {
    return new NextResponse(null, {
      status: 204,
      headers: {
        'Access-Control-Allow-Origin': isAllowed ? origin : '',
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
        'Access-Control-Max-Age': '86400'
      }
    })
  }

  const response = NextResponse.next()

  if (isAllowed) {
    response.headers.set('Access-Control-Allow-Origin', origin)
  }

  return response
}

Request Logging Middleware#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export async function middleware(request: NextRequest) {
  const requestId = crypto.randomUUID()
  const start = Date.now()

  // Add request ID to headers
  const requestHeaders = new Headers(request.headers)
  requestHeaders.set('x-request-id', requestId)

  const response = NextResponse.next({
    request: { headers: requestHeaders }
  })

  // Log request
  const duration = Date.now() - start
  console.log(JSON.stringify({
    requestId,
    method: request.method,
    path: request.nextUrl.pathname,
    duration,
    timestamp: new Date().toISOString()
  }))

  response.headers.set('x-request-id', requestId)
  return response
}

Composed Middleware#

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest, NextMiddleware } from 'next/server'

type MiddlewareFunction = (
  request: NextRequest
) => Promise<NextResponse | null> | NextResponse | null

// Compose multiple middlewares
function composeMiddleware(...middlewares: MiddlewareFunction[]) {
  return async (request: NextRequest) => {
    for (const middleware of middlewares) {
      const result = await middleware(request)
      // If middleware returns a response, stop chain
      if (result) return result
    }
    return NextResponse.next()
  }
}

// Individual middlewares
async function authMiddleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/api/protected')) {
    const token = await getToken({ req: request })
    if (!token) {
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
    }
  }
  return null // Continue to next middleware
}

function loggingMiddleware(request: NextRequest) {
  console.log(`${request.method} ${request.nextUrl.pathname}`)
  return null
}

async function rateLimitMiddleware(request: NextRequest) {
  const ip = request.ip ?? 'unknown'
  const result = await checkRateLimit(ip)
  if (!result.success) {
    return NextResponse.json({ error: 'Rate limited' }, { status: 429 })
  }
  return null
}

// Export composed middleware
export const middleware = composeMiddleware(
  loggingMiddleware,
  rateLimitMiddleware,
  authMiddleware
)

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

API Key Middleware#

// lib/api-key.ts
import { prisma } from '@/lib/db'
import { headers } from 'next/headers'

export async function validateApiKey() {
  const headersList = headers()
  const apiKey = headersList.get('x-api-key')

  if (!apiKey) {
    return null
  }

  const key = await prisma.apiKey.findUnique({
    where: { key: apiKey },
    include: { user: true }
  })

  if (!key || key.revokedAt) {
    return null
  }

  // Update last used
  await prisma.apiKey.update({
    where: { id: key.id },
    data: { lastUsedAt: new Date() }
  })

  return key.user
}

// Usage in route handler
export async function GET(request: Request) {
  const user = await validateApiKey()

  if (!user) {
    return Response.json(
      { error: 'Invalid API key' },
      { status: 401 }
    )
  }

  // Continue with authenticated user...
}

Request Validation Middleware#

// lib/validate-request.ts
import { NextRequest, NextResponse } from 'next/server'
import { z } from 'zod'

export function withValidation<T extends z.ZodSchema>(
  schema: T,
  handler: (
    request: NextRequest,
    data: z.infer<T>
  ) => Promise<NextResponse>
) {
  return async (request: NextRequest) => {
    try {
      const body = await request.json()
      const data = schema.parse(body)
      return handler(request, data)
    } catch (error) {
      if (error instanceof z.ZodError) {
        return NextResponse.json(
          { error: { message: 'Validation failed', details: error.errors } },
          { status: 400 }
        )
      }
      throw error
    }
  }
}

// Usage
const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1)
})

export const POST = withValidation(CreateUserSchema, async (request, data) => {
  const user = await createUser(data)
  return NextResponse.json({ data: user }, { status: 201 })
})

Usage Instructions#

Create middleware.ts: Add file at project root (next to app/ directory)
Export middleware function: Default export or named middleware export
Configure matcher: Use config.matcher to specify which paths to run on
Compose middlewares: Chain multiple middleware functions for complex logic
Handle responses: Return NextResponse.next() to continue or a response to short-circuit

Best Practices#

Keep middleware fast - It runs on every matched request, avoid heavy computations
Use matchers wisely - Only run middleware on necessary paths
Compose for reusability - Break down logic into composable functions
Add request IDs - Helpful for debugging and tracing
Handle errors gracefully - Return proper error responses
Consider edge limitations - Middleware runs at the edge, not all Node.js APIs available
Log strategically - Don't over-log, use structured logging

Route Handler - API route implementation
Rate Limiting - Protect APIs from abuse
Error Handling - Consistent error responses
Authentication - User authentication setup