Step-by-Step Guide to Setting Up Rate Limiting with Redis 7.2 and Next.js 17

version: '3.8'

services:
  redis:
    image: redis:7.2-alpine
    container_name: rate-limit-redis
    ports:
      - "6379:6379"
    volumes:
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf
      - redis-data:/data
    command: redis-server /usr/local/etc/redis/redis.conf
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  redis-data:

# Redis 7.2 configuration for rate limiting workload
bind 0.0.0.0
port 6379
maxmemory 256mb
maxmemory-policy allkeys-lru
appendonly yes
appendfsync everysec
# Disable dangerous commands for production
rename-command FLUSHALL ""
rename-command FLUSHDB ""
rename-command SHUTDOWN ""
# Enable keyspace notifications for rate limit expiry (optional)
notify-keyspace-events Ex
# Logging
loglevel notice
logfile /var/log/redis/redis.log
# Disable protected mode for local development (enable in production with password)
protected-mode no

docker compose up -d
# Verify Redis is running
docker exec -it rate-limit-redis redis-cli ping
# Should return PONG

npx create-next-app@17 my-rate-limited-app
# Select options:
# TypeScript: Yes
# App Router: Yes
# Edge Middleware: Yes
# ESLint: Yes
# Tailwind CSS: Optional (not used in this guide)
# src directory: No
# import alias: Yes (@/*)
cd my-rate-limited-app

npm install ioredis
# or
yarn add ioredis

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# For production, add:
# REDIS_HOST=your-redis-host
# REDIS_PASSWORD=your-secure-password

import { Redis } from 'ioredis';
import { NextRequest, NextResponse } from 'next/server';

// Constants for rate limit configuration
const RATE_LIMIT_WINDOW_MS = 60 * 1000; // 1 minute window
const MAX_REQUESTS_PER_WINDOW = 100; // 100 requests per minute per identifier
const REDIS_KEY_PREFIX = 'rl:'; // Prefix to avoid key collisions with other Redis data

// Initialize Redis client with connection pooling and error handling
// Using ioredis for built-in Sentinel/Cluster support and automatic reconnection
const redisClient = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD || undefined,
  maxRetriesPerRequest: 3,
  retryStrategy: (times) => {
    // Exponential backoff for reconnection: 50ms, 100ms, 200ms, 400ms, 800ms
    const delay = Math.min(times * 50, 2000);
    return delay;
  },
  // Enable lazy connection to avoid blocking startup if Redis is unavailable
  lazyConnect: true,
});

// Handle Redis connection errors without crashing the Next.js process
redisClient.on('error', (err) => {
  console.error(`[Rate Limit Redis Client Error]: ${err.message}`);
  // Log to external monitoring service in production (e.g., Datadog, Sentry)
  if (process.env.NODE_ENV === 'production') {
    // reportToMonitoring(err); // Uncomment and implement in production
  }
});

redisClient.on('connect', () => {
  console.log('[Rate Limit] Connected to Redis 7.2 instance');
});

/**
 * Sliding window rate limiting implementation using Redis atomic operations
 * Uses INCR + EXPIRE for fixed window (simpler) — see Step 4 for sliding window
 * @param identifier - Unique identifier for the rate limit (e.g., IP, API key)
 * @returns Object containing limit status, remaining requests, and reset time
 */
export async function checkRateLimit(identifier: string): Promise<{
  isLimited: boolean;
  remaining: number;
  resetMs: number;
  totalLimit: number;
}> {
  const redisKey = `${REDIS_KEY_PREFIX}${identifier}`;

  try {
    // Atomic INCR and EXPIRE to avoid race conditions
    // Using MULTI/EXEC for transactionality
    const multi = redisClient.multi();
    multi.incr(redisKey);
    multi.expire(redisKey, RATE_LIMIT_WINDOW_MS / 1000); // EXPIRE takes seconds
    const results = await multi.exec();

    if (!results) {
      throw new Error('Redis transaction failed: no results returned');
    }

    const [incrErr, requestCount] = results[0];
    const [expireErr, expireResult] = results[1];

    if (incrErr || expireErr) {
      throw new Error(`Redis operation failed: ${incrErr?.message || expireErr?.message}`);
    }

    const currentCount = requestCount as number;
    const isLimited = currentCount > MAX_REQUESTS_PER_WINDOW;
    const remaining = Math.max(0, MAX_REQUESTS_PER_WINDOW - currentCount);
    // Calculate reset time as window start + window duration
    // For fixed window, reset is when the key expires
    const resetMs = Date.now() + RATE_LIMIT_WINDOW_MS;

    return {
      isLimited,
      remaining,
      resetMs,
      totalLimit: MAX_REQUESTS_PER_WINDOW,
    };
  } catch (err) {
    console.error(`[Rate Limit Check Failed]: ${err.message}`);
    // Fail open: if Redis is down, allow the request to avoid blocking legitimate traffic
    // In strict mode, you'd fail closed — see Developer Tips for tradeoffs
    return {
      isLimited: false,
      remaining: MAX_REQUESTS_PER_WINDOW,
      resetMs: Date.now() + RATE_LIMIT_WINDOW_MS,
      totalLimit: MAX_REQUESTS_PER_WINDOW,
    };
  }
}

/**
 * Next.js 17 Middleware handler for rate limiting
 * Applies rate limiting to all API routes matching the pattern
 */
export function rateLimitMiddleware(request: NextRequest) {
  // Only apply to /api/* routes
  if (!request.nextUrl.pathname.startsWith('/api/')) {
    return NextResponse.next();
  }

  // Use IP as identifier — replace with API key/header for authenticated routes
  const identifier = request.ip || request.headers.get('x-forwarded-for') || 'unknown';
  // In production, use a hashed identifier to avoid storing PII in Redis
  // const hashedIdentifier = crypto.createHash('sha256').update(identifier).digest('hex');

  return checkRateLimit(identifier).then((limitStatus) => {
    const response = limitStatus.isLimited 
      ? NextResponse.json(
          { error: 'Too many requests', retryAfter: Math.ceil((limitStatus.resetMs - Date.now()) / 1000) },
          { status: 429 }
        )
      : NextResponse.next();

    // Set standard rate limit headers
    response.headers.set('X-RateLimit-Limit', limitStatus.totalLimit.toString());
    response.headers.set('X-RateLimit-Remaining', limitStatus.remaining.toString());
    response.headers.set('X-RateLimit-Reset', Math.ceil(limitStatus.resetMs / 1000).toString());

    return response;
  }).catch((err) => {
    console.error(`[Middleware Error]: ${err.message}`);
    return NextResponse.next(); // Fail open on error
  });
}

import { Redis } from 'ioredis';
import { NextRequest, NextResponse } from 'next/server';

// Sliding window rate limit configuration
const SLIDING_WINDOW_MS = 60 * 1000; // 1 minute window
const SLIDING_MAX_REQUESTS = 100; // 100 requests per window
const SLIDING_KEY_PREFIX = 'rl:sliding:';

// Reuse Redis client from previous example, or initialize new one
const slidingRedisClient = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379'),
  password: process.env.REDIS_PASSWORD || undefined,
  maxRetriesPerRequest: 3,
});

slidingRedisClient.on('error', (err) => {
  console.error(`[Sliding Window Redis Error]: ${err.message}`);
});

/**
 * Sliding window rate limiting using Redis Sorted Sets (ZADD/ZREMRANGEBYSCORE/ZCARD)
 * More accurate than fixed window, reduces false positives
 * @param identifier - Unique identifier (IP, API key, etc.)
 * @returns Rate limit status with precise remaining count
 */
export async function checkSlidingRateLimit(identifier: string): Promise<{
  isLimited: boolean;
  remaining: number;
  resetMs: number;
  totalLimit: number;
}> {
  const redisKey = `${SLIDING_KEY_PREFIX}${identifier}`;
  const now = Date.now();
  const windowStart = now - SLIDING_WINDOW_MS;
  const requestId = `${now}:${Math.random().toString(36).substring(2, 9)}`; // Unique ID for this request

  try {
    const multi = slidingRedisClient.multi();
    // 1. Remove all requests older than the window start
    multi.zremrangebyscore(redisKey, 0, windowStart);
    // 2. Add current request to the sorted set with timestamp as score
    multi.zadd(redisKey, now, requestId);
    // 3. Get total count of requests in the window
    multi.zcard(redisKey);
    // 4. Set expiry on the key to clean up if no requests are made
    multi.expire(redisKey, SLIDING_WINDOW_MS / 1000);

    const results = await multi.exec();
    if (!results) {
      throw new Error('Sliding window Redis transaction failed');
    }

    const [zremErr, removedCount] = results[0];
    const [zaddErr, addedCount] = results[1];
    const [zcardErr, totalRequests] = results[2];
    const [expireErr, expireResult] = results[3];

    if (zremErr || zaddErr || zcardErr || expireErr) {
      throw new Error(`Sliding window operation failed: ${zremErr?.message || zaddErr?.message}`);
    }

    const currentCount = totalRequests as number;
    const isLimited = currentCount > SLIDING_MAX_REQUESTS;
    const remaining = Math.max(0, SLIDING_MAX_REQUESTS - currentCount);
    // Reset time is when the oldest request in the window expires
    const oldestRequest = await slidingRedisClient.zrange(redisKey, 0, 0, 'WITHSCORES');
    const resetMs = oldestRequest.length > 1 
      ? parseInt(oldestRequest[1]) + SLIDING_WINDOW_MS 
      : now + SLIDING_WINDOW_MS;

    return {
      isLimited,
      remaining,
      resetMs,
      totalLimit: SLIDING_MAX_REQUESTS,
    };
  } catch (err) {
    console.error(`[Sliding Window Check Failed]: ${err.message}`);
    // Fail open
    return {
      isLimited: false,
      remaining: SLIDING_MAX_REQUESTS,
      resetMs: now + SLIDING_WINDOW_MS,
      totalLimit: SLIDING_MAX_REQUESTS,
    };
  }
}

// Middleware for sliding window rate limiting
export function slidingRateLimitMiddleware(request: NextRequest) {
  if (!request.nextUrl.pathname.startsWith('/api/')) {
    return NextResponse.next();
  }

  const identifier = request.ip || request.headers.get('x-forwarded-for') || 'unknown';
  return checkSlidingRateLimit(identifier).then((status) => {
    const response = status.isLimited
      ? NextResponse.json(
          { error: 'Too many requests', retryAfter: Math.ceil((status.resetMs - Date.now()) / 1000) },
          { status: 429 }
        )
      : NextResponse.next();

    response.headers.set('X-RateLimit-Limit', status.totalLimit.toString());
    response.headers.set('X-RateLimit-Remaining', status.remaining.toString());
    response.headers.set('X-RateLimit-Reset', Math.ceil(status.resetMs / 1000).toString());
    return response;
  }).catch((err) => {
    console.error(`[Sliding Middleware Error]: ${err.message}`);
    return NextResponse.next();
  });
}

import { NextRequest, NextResponse } from 'next/server';
import { rateLimitMiddleware } from '@/lib/rate-limit'; // Adjust path based on your project structure
// Uncomment to use sliding window instead:
// import { slidingRateLimitMiddleware } from '@/lib/sliding-window-rate-limit';

/**
 * Next.js 17 Edge Middleware configuration
 * Matches all API routes and applies rate limiting
 * Note: Edge middleware runs before the request hits API routes, reducing latency
 */
export const config = {
  matcher: [
    // Match all API routes except health check
    '/api/:path*',
    // Exclude health check endpoint from rate limiting
    '!/api/health',
  ],
};

/**
 * Main middleware handler for Next.js 17
 * Supports both Node.js and Edge runtime (Edge is default for Next.js 17)
 */
export async function middleware(request: NextRequest) {
  try {
    // Apply rate limiting to all matched routes
    const rateLimitResponse = await rateLimitMiddleware(request);

    // If rate limit response is 429, return it immediately
    if (rateLimitResponse.status === 429) {
      return rateLimitResponse;
    }

    // Add custom headers for debugging (remove in production)
    if (process.env.NODE_ENV === 'development') {
      rateLimitResponse.headers.set('X-Debug-RateLimit', 'applied');
    }

    return rateLimitResponse;
  } catch (err) {
    console.error(`[Main Middleware Error]: ${err.message}`);
    // Fail open: allow request if middleware errors
    return NextResponse.next();
  }
}

// Optional: Configure runtime to edge (default in Next.js 17, but explicit here)
export const runtime = 'edge'; // Use 'nodejs' for Node.js runtime, 'edge' for Edge

// For authenticated routes, use API key from header as identifier instead of IP
// Uncomment below for authenticated rate limiting:
// if (request.nextUrl.pathname.startsWith('/api/protected')) {
//   const apiKey = request.headers.get('x-api-key');
//   if (!apiKey) {
//     return NextResponse.json({ error: 'Missing API key' }, { status: 401 });
//   }
//   const identifier = `api-key:${apiKey}`;
//   const limitStatus = await checkRateLimit(identifier);
//   // Apply rate limit with identifier
// }

npm run dev
# Make 101 requests to http://localhost:3000/api/hello
# The 101st request should return 429 Too Many Requests

// In checkRateLimit catch block:
return {
  isLimited: true, // Fail closed
  remaining: 0,
  resetMs: Date.now() + RATE_LIMIT_WINDOW_MS,
  totalLimit: MAX_REQUESTS_PER_WINDOW,
};

import crypto from 'crypto';

function hashIdentifier(identifier: string): string {
  return crypto.createHash('sha256').update(identifier).digest('hex');
}

// In rateLimitMiddleware:
const rawIdentifier = request.ip || request.headers.get('x-forwarded-for') || 'unknown';
const identifier = hashIdentifier(rawIdentifier);

// In checkRateLimit, after determining isLimited:
if (isLimited) {
  redisClient.incr('metrics:rate-limit-hits');
  redisClient.expire('metrics:rate-limit-hits', 86400); // Keep metrics for 24 hours
}

nextjs17-redis7-rate-limiting/
├── app/
│   ├── api/
│   │   ├── hello/
│   │   │   └── route.ts
│   │   └── health/
│   │       └── route.ts
├── lib/
│   ├── rate-limit.ts
│   └── sliding-window-rate-limit.ts
├── redis/
│   └── redis.conf
├── middleware.ts
├── docker-compose.yml
├── .env.local.example
├── package.json
└── README.md

import { Cluster } from 'ioredis';
const redisClient = new Cluster([
  { host: 'redis-node-1', port: 6379 },
  { host: 'redis-node-2', port: 6379 },
], { maxRedirections: 16 });

// In middleware.ts
const user = await getUserFromRequest(request); // Implement your auth check
const identifier = user ? `user:${user.id}` : `ip:${request.ip}`;