Custom Cache Handler in Next.js 16 — Redis Setup Caused 200ms Added Latency Per Request

Caching is the backbone of Next.js performance. Every ISR-revalidated page, every cached fetch response, every data request served from cache — they all go through Next.js's cache layer. In Next.js 14 and earlier, this cache was a simple in-memory store on the filesystem, adequate for single-instance deployments but invisible to developers.

Next.js 16 introduced a configurable cache handler API. You can now plug in Redis, Memcached, Cloudflare KV, or any key-value store as the backing cache. This enables shared caching across multiple server instances — critical for auto-scaling deployments where each instance would otherwise rebuild its own cache.

But with great power comes a new failure mode: a poorly configured external cache adds 50-200ms of latency to every cache operation. If your cache handler adds more latency than it saves by avoiding data source fetches, you have built a slower system than running with no cache at all.

This article covers the custom cache handler API, cacheLife profiles for declarative TTL management, cacheTag for granular invalidation, stale-while-revalidate configuration, and the specific scenarios where external caching helps versus hurts. By the end, you will know when to deploy Redis and when the default filesystem cache is the right choice.

The Default Cache — Why Local FS Is Faster Than You Think

Next.js's default cache handler stores data as files on the local filesystem. This sounds primitive compared to a managed Redis instance, but for single-server deployments, it is faster. Local file I/O takes 0.5-2ms per operation. A Redis round trip on the same machine via Unix socket takes 1-3ms. A Redis round trip over a network connection takes 5-50ms depending on distance and bandwidth.

The default handler also has zero operational overhead. There is no Redis to deploy, no connection pool to configure, no eviction policy to tune. The cache is automatically available when your Next.js server starts and disappears when it stops — acceptable for ephemeral server instances.

The limitation: the filesystem cache is not shared across instances. If you run 4 server instances behind a load balancer, each instance has its own cache. A request served by instance 1 that triggers a revalidation does not benefit instance 2 — instance 2 must independently re-fetch and cache the data. For small deployments (1-3 instances), this is acceptable. For larger deployments, a shared external cache eliminates redundant work.

The rule: default to the filesystem cache. Only add an external cache when you can measure that the cache hit rate benefit exceeds the added latency of remote network calls.

cacheLife Profiles — Declarative TTL Management Without Boilerplate

Before cacheLife, managing cache TTLs required either hardcoding values in every fetch call or building a custom TTL function. cacheLife changes this by letting you define reusable profiles that specify how long data can be stale, how long before revalidation triggers, and when data expires completely.

Each profile defines three timestamps: stale — how long the cache serves data without checking the origin; revalidate — how long before Next.js triggers a background revalidation; and expire — the absolute maximum time data remains in cache before being treated as a miss. Together, these mirror the stale-while-revalidate pattern that ISR popularised.

Profiles are registered via cacheLife() in a layout or page file. Once registered, any fetch or data call in that route segment can reference the profile by name. Next.js automatically manages the TTL logic — you don't need to pass revalidation times to every fetch call.

The practical benefit: one source of truth for how long each data type is cached. Product data gets a different profile than user preferences or analytics dashboards. Changing the profile updates all consumers automatically.

import { cacheLife } from 'next/cache'

// Register cache profiles in the root layout
// These apply to all pages in the app
cacheLife({
  // Data that changes hourly:
  products: {
    stale: 60 * 5,      // Serve stale for 5 min
    revalidate: 60 * 15, // Background refresh after 15 min
    expire: 60 * 60,     // Hard expiry at 1 hour
  },
  // Data that changes daily:
  blog: {
    stale: 60 * 60,     // Serve stale for 1 hour
    revalidate: 60 * 60 * 6, // Refresh every 6 hours
    expire: 60 * 60 * 24,   // Expire after 1 day
  },
  // User-specific data — never cache long:
  session: {
    stale: 60,          // Stale for 1 min
    revalidate: 60 * 5,  // Refresh every 5 min
    expire: 60 * 30,     // Hard expiry at 30 min
  },
})

// Usage in any page:
// const data = await fetch(url, {
//   next: { revalidate: false }  // Opt out of per-request revalidate
// })
// The cacheLife profile handles the TTL

cacheTag — Granular Invalidation Without the Pain

Time-based revalidation is a blunt instrument. With cacheLife's revalidate window, you accept that data may be up to N minutes stale. For many apps, this is fine. For apps where data changes unpredictably — a CMS publish, a price update, a user action — time-based invalidation is either too slow (users see stale data) or too aggressive (server constantly revalidates).

cacheTag solves this by letting you tag cached responses with arbitrary strings and invalidate them on demand. You tag a fetch call with tags: ['products', 'category-electronics']. Then, anywhere in your app — in an API route, a server action, a webhook handler — you call revalidateTag('products') and every cached response tagged with 'products' is immediately invalidated.

The tag system supports arbitrary granularity. You can tag broadly (tags: ['products']) for full category invalidation, or specifically (tags: ['product-42']) to invalidate a single item. You can also combine multiple tags on one fetch — invalidating any of the tags triggers revalidation.

The performance implication: revalidation is lazy. Calling revalidateTag marks the cached response as stale but does not rebuild it. The next request that hits that cache entry triggers the background regeneration. This means invalidating 10,000 product tags is instant — it's just a metadata update. The actual work happens over time as users visit invalidated pages.

import { unstable_cacheTag as cacheTag } from 'next/cache'

// Server Component fetching products
export default async function ProductsPage() {
  const data = await fetch('https://api.example.com/products', {
    next: {
      tags: ['products'], // Tag this response for invalidation
    },
  })
  const products = await data.json()

  return (
    <div>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

// --- app/api/revalidate/route.ts ---
// Webhook or admin action to invalidate cache
import { revalidateTag } from 'next/cache'

export async function POST(request: Request) {
  const body = await request.json()

  // Invalidate all product caches
  revalidateTag('products')

  // Or invalidate a specific product
  // revalidateTag(`product-${body.productId}`)

  return Response.json({ revalidated: true })
}

Building a Custom Cache Handler — When and How

The custom cache handler API in Next.js 16 lets you replace the default filesystem cache with any key-value store. The handler is a class that implements get, set, has, delete, and revalidateTag methods. Next.js calls these methods for every cache operation during rendering.

When you need a custom handler: (1) multi-instance deployments where shared caching reduces redundant work; (2) persistence requirements where cache must survive server restarts; (3) edge caching with Cloudflare KV or similar; (4) specialised backends like Memcached for very large cached objects.

When you don't: single-instance deployments, serverless functions with short lifetimes, or any scenario where the added latency of external network calls may exceed the cache hit benefit. Default to filesystem, measure, then customise.

The handler configuration is in next.config.ts via the cacheHandler option pointing to a module path. The module must export a default class or function that Next.js can instantiate. The handler receives configuration options from the config file.

import { Redis } from '@upstash/redis'
import type { CacheHandler } from 'next/dist/server/lib/incremental-cache'

interface CacheValue {
  body: string
  tags: string[]
}

export default class RedisCacheHandler implements CacheHandler {
  private redis: Redis
  private ttl: number

  constructor(options: { ttl?: number }) {
    this.redis = Redis.fromEnv()
    this.ttl = options.ttl ?? 300
  }

  async get(key: string) {
    const cached = await this.redis.get<CacheValue>(key)
    if (!cached) return null
    return {
      body: cached.body,
      tags: cached.tags,
      // Next.js needs to know when this was cached
      lastModified: Date.now(),
    }
  }

  async set(key: string, data: {
    body: string
    tags?: string[]
  }) {
    await this.redis.set(key, {
      body: data.body,
      tags: data.tags ?? [],
    }, { ex: this.ttl })
  }

  async has(key: string) {
    const exists = await this.redis.exists(key)
    return exists === 1
  }

  async delete(key: string) {
    await this.redis.del(key)
  }

  async revalidateTag(tag: string) {
    // Find all keys with this tag and delete them
    // In production, maintain a tag-to-key index
    const keys = await this.redis.keys(`*${tag}*`)
    if (keys.length > 0) {
      await this.redis.del(...keys)
    }
  }
}

// next.config.ts
// cacheHandler: './cache/redis-handler.ts'

Stale-While-Revalidate — Never Block on Cache Miss

The stale-while-revalidate pattern is the most important caching concept of the past decade. It works: serve the cached (stale) response immediately to the user, then in the background, re-fetch the fresh data and update the cache. The user never waits for the origin.

Next.js has supported this implicitly via ISR's background regeneration since Next.js 9.5. But cacheLife profiles make it explicit: the stale window is the 'while-revalidate' period — the cache is allowed to return stale data while a background refresh completes. The revalidate window is the trigger point — when elapsed time exceeds revalidate, the next request triggers a background refresh.

The critical detail: during the background refresh, the cache still returns stale data. The user whose request triggered the revalidation receives stale data — not fresh. Only subsequent requests receive the freshly built response. This is correct behaviour: no user should ever be blocked waiting for a cache rebuild.

Where teams go wrong: they treat stale data as a bug and reduce the stale window to near-zero. This defeats the purpose — if stale is 1 second, almost every request triggers a background refresh, turning ISR into a more expensive version of SSR. The stale window exists precisely to absorb traffic spikes without overwhelming the origin.

// cacheLife with explicit stale-while-revalidate semantics
cacheLife({
  // For 'products' cache profile:
  products: {
    // 5 minutes — serve stale data without checking origin
    // Users always get instant responses
    stale: 60 * 5,

    // 15 minutes — after this, trigger background refresh
    // The request that triggers the refresh still gets stale data
    revalidate: 60 * 15,

    // 1 hour — hard expiry. Cache miss, must fetch fresh.
    // This prevents serving truly outdated data if no one visited
    // during the revalidate window
    expire: 60 * 60,
  },
})

// Timeline of requests:
// T=0:    First request — cache miss, fetch from origin, populate cache
// T=3min: Request — cache HIT, serve stale, no revalidation
// T=16min: Request — stale > revalidate, serve STALE, trigger background refresh
// T=16.1s: Background refresh completes, cache updated
// T=17min: Request — cache HIT with FRESH data
// T=75min: No requests in 60min — cache EXPIREs
// T=80min: Request — cache MISS, fetch from origin

Redis vs Memcached vs Cloudflare KV — Choosing the Right Backend

Not all external caches are equal. Each has specific characteristics that make it suitable for different deployment patterns.

Redis: full-featured in-memory store. Supports data structures (sets, hashes, sorted sets), TTL, pub/sub for cache invalidation broadcasts, and Lua scripting for atomic operations. Best for: multi-instance deployments where you need shared cache + pub/sub invalidation + data structure operations. Overhead: 5-15ms per operation for network round trip plus serialization.

Memcached: simpler, faster, more memory-efficient per byte of cached data. No persistence, no data structures, no TTL beyond max-age. Best for: very large cache datasets where memory efficiency matters more than features. Overhead: 3-10ms per operation, lower memory overhead per cached item than Redis.

Cloudflare KV: globally distributed, eventually consistent key-value store at the edge. Reads are served from the nearest edge location (sub-5ms p99). Writes propagate globally within 60 seconds. Best for: multi-region Next.js deployments where cache must be close to users worldwide. Not suitable for: data that requires strong consistency or sub-second write propagation.

The choice rule: Redis for single-region multi-instance, KV for global multi-region, Memcached for large cache datasets on a budget. If you can't decide, start with Redis — it's the most forgiving of the three.

import type { CacheHandler } from 'next/dist/server/lib/incremental-cache'

// Cloudflare KV cache handler example
// Assumes @cloudflare/workers-types for KVNamespace type

export default class KVCacheHandler implements CacheHandler {
  private kv: KVNamespace

  constructor() {
    // In production, bind KV namespace from env
    // This example uses Cloudflare for Workers
    this.kv = (process.env as any).CACHE_KV
  }

  async get(key: string) {
    const value = await this.kv.get(key, 'json')
    if (!value) return null
    return {
      body: JSON.stringify(value),
      lastModified: Date.now(),
    }
  }

  async set(key: string, data: { body: string }) {
    await this.kv.put(key, data.body, {
      expirationTtl: 3600, // 1 hour
    })
  }

  async has(key: string) {
    const value = await this.kv.get(key)
    return value !== null
  }

  async delete(key: string) {
    await this.kv.delete(key)
  }

  async revalidateTag(tag: string) {
    // KV has no tag-based listing
    // Solution: maintain tag indexes or use a different
    // invalidation strategy (e.g., version prefixes)
    console.warn(`KV revalidateTag not implemented for: ${tag}`)
  }
}

Cache and Server Actions — Stale Data and Optimistic Updates

Server Actions in Next.js 16 add a new wrinkle to caching. When a user submits a form that mutates data, the Server Action runs on the server. After the mutation completes, Next.js can revalidate cached data automatically — but only if you tell it to.

The pattern: the Server Action performs the mutation, then calls revalidatePath() or revalidateTag() to mark affected cached data as stale. The next request for the page that displays the mutated data triggers a background refresh, returning the new data.

For a snappier user experience, pair Server Actions with optimistic updates on the client. The UI updates immediately to show the expected result (optimistic), while the Server Action runs in the background. If the action fails, the UI reverts to the previous state. If it succeeds, the revalidation refreshes the display with server-authoritative data.

The caching challenge: Server Actions run on the server, so they can directly call revalidateTag. But if you use a library like React Query or SWR alongside cacheTag, you have two layers of caching — Next.js's server-side cache and the client-side cache. Invalidate both when mutations occur.

'use server'

import { revalidateTag, revalidatePath } from 'next/cache'
import { db } from '@/lib/db'

// Server action: update product price
export async function updatePrice(
  productId: string,
  newPrice: number
) {
  // Perform mutation
  await db.product.update({
    where: { id: productId },
    data: { price: newPrice },
  })

  // Invalidate ALL product caches
  revalidateTag('products')

  // Also revalidate the specific product page
  revalidatePath(`/products/${productId}`)

  return { success: true }
}

// Client component with optimistic update
// 'use client'
// import { useOptimistic, useTransition } from 'react'
//
// export function PriceForm({ product }: { product: any }) {
//   const [pending, startTransition] = useTransition()
//   const [optimisticPrice, setOptimisticPrice] =
//     useOptimistic(product.price)
//
//   async function handleSubmit(formData: FormData) {
//     const newPrice = Number(formData.get('price'))
//
//     startTransition(async () => {
//       setOptimisticPrice(newPrice) // Immediate UI update
//       await updatePrice(product.id, newPrice)
//     })
//   }
//
//   return (
//     <form action={handleSubmit}>
//       <input name="price" defaultValue={optimisticPrice} />
//       <button type="submit" disabled={pending}>
//         {pending ? 'Saving...' : 'Update'}
//       </button>
//     </form>
//   )
// }

Cache Deduplication and Coalescing — How Next.js Prevents Thundering Herds

The thundering herd problem: when a cached page expires or is invalidated, and 10,000 users simultaneously request it, all 10,000 requests could trigger individual revalidation fetches to the origin. This can overwhelm your database, API, or CMS.

Next.js handles this through request deduplication: when a background refresh is triggered for a cache key, Next.js coalesces concurrent requests. Of 10,000 simultaneous requests, only ONE triggers the actual revalidation. The other 9,999 receive the stale cached response while the single revalidation completes. When the fresh response is ready, it replaces the cached entry and all subsequent requests receive fresh data.

This deduplication happens within a single server instance. Across multiple instances (without shared caching), each instance independently deduplicates — but you could still have 4 revalidation requests for the same key hitting your origin simultaneously with 4 instances. This is where shared caching (Redis/KV) with a mutex lock prevents each instance from independently revalidating.

The deduplication timeout is the key: if the background refresh takes 1 second, all requests during that second see stale data. If the refresh takes 10 seconds (slow API), requests see stale data for 10 seconds. The system is resilient to slow data sources — it never blocks requests waiting for fresh data.

// Conceptual model of Next.js cache deduplication
// Not actual Next.js source code — illustrates the logic

const inflightRefreshes = new Map<string, Promise<void>>()

async function getOrRefresh(key: string) {
  // Check if a refresh is already inflight
  if (inflightRefreshes.has(key)) {
    // Don't start another refresh — wait for the existing one
    await inflightRefreshes.get(key)
    return serveStaleFromCache(key)
  }

  // Start refresh and store the promise
  const refreshPromise = fetchAndPopulateCache(key).finally(() => {
    inflightRefreshes.delete(key)
  })

  inflightRefreshes.set(key, refreshPromise)

  // Return stale data immediately — don't await the refresh
  return serveStaleFromCache(key)
}

// Result:
// Request 1: triggers refresh, gets stale data
// Request 2-10,000: see inflight refresh, join it, get stale data
// After refresh completes: all requests get fresh data
// Only 1 origin call for 10,000 requests

Cache Monitoring — What to Measure and What to Alert On

Without monitoring, your cache is a black box. You don't know your hit rate, miss penalty, revalidation latency, or eviction rate. You can't answer the basic question: is caching helping or hurting?

The metrics to track: (1) Cache hit rate — percentage of requests served from cache. Target: >80% for most apps, >95% for content-heavy apps. Below 50% indicates misconfigured TTLs or incorrect cache keys. (2) Cache latency — time per cache operation. Local FS: 0.5-2ms. Remote Redis: 5-15ms. If remote cache latency exceeds your target response time margin, the cache is hurting. (3) Revalidation count — how many background refresh requests hit your origin per cache key. Spikes indicate TTLs are too short or invalidation is too aggressive. (4) Cache size and eviction rate — how much data is in the cache and how often entries are evicted before their TTL. High eviction means the cache is too small for your working set.

Alert on: cache hit rate dropping below 60% for 5 minutes, revalidation count exceeding 100/min for a single key (potential thundering herd despite deduplication), cache latency p99 exceeding 50ms.

'use server'

import { Redis } from '@upstash/redis'

const redis = Redis.fromEnv()
const CACHE_PREFIX = 'next-cache:'

export async function getCacheMetrics() {
  const hits = await redis.get<number>(`${CACHE_PREFIX}stats:hits`) ?? 0
  const misses = await redis.get<number>(`${CACHE_PREFIX}stats:misses`) ?? 0
  const total = hits + misses

  return {
    hitRate: total > 0 ? (hits / total * 100).toFixed(1) : 0,
    totalOperations: total,
    hits,
    misses,
    // Sample latency from last 100 operations
    avgLatency: await redis.get<number>(`${CACHE_PREFIX}stats:avg-latency`),
  }
}

export async function recordCacheOperation(
  operation: 'hit' | 'miss',
  latencyMs: number
) {
  const key = `${CACHE_PREFIX}stats:${operation}s`
  await redis.incr(key)
  await redis.lpush(`${CACHE_PREFIX}stats:latencies`, latencyMs)
  await redis.ltrim(`${CACHE_PREFIX}stats:latencies`, 0, 99)

  // Calculate running average
  const latencies = await redis.lrange<number>(
    `${CACHE_PREFIX}stats:latencies`, 0, -1
  )
  const avg = latencies.reduce((a, b) => a + b, 0) / latencies.length
  await redis.set(`${CACHE_PREFIX}stats:avg-latency`, avg)
}

Production Migration — From Default FS to Redis Without Downtime

Migrating from the default filesystem cache to a custom Redis handler in production requires a careful rollout. A sudden switch can cause a cold cache event — every user request becomes a cache miss, flooding your origin with traffic that the cache previously absorbed.

The safe migration strategy: (1) Deploy the Redis handler alongside the FS handler — run both in parallel with the Redis handler writes-only. All reads continue from FS cache. The Redis handler populates over time without serving traffic. (2) After one TTL cycle (monitor for 2x your longest cacheLife expire value), switch Redis to read-write and FS to writes-only. Cache hits now primarily serve from Redis. (3) After another TTL cycle, remove the FS handler entirely.

Each phase should run for at least one full cache expire cycle of your longest cache profile. For a profile with expire: 86400 (24 hours), each phase takes 24 hours minimum — a 72-hour migration. This is intentionally conservative: a cold cache can take down a production system.

import type { CacheHandler } from 'next/dist/server/lib/incremental-cache'

// Dual-write cache handler for safe migration
// Phase 2: reads from Redis, writes to both

export default class MigrationHandler implements CacheHandler {
  private fs: CacheHandler
  private redis: CacheHandler

  constructor() {
    this.fs = new (require('./fs-handler').default)()
    this.redis = new (require('./redis-handler').default)()
  }

  async get(key: string) {
    // Try Redis first, fall back to FS
    const fromRedis = await this.redis.get(key)
    if (fromRedis) return fromRedis

    // FS fallback — warms Redis for next request
    const fromFs = await this.fs.get(key)
    if (fromFs) {
      await this.redis.set(key, fromFs)
    }
    return fromFs
  }

  async set(key: string, data: any) {
    // Write to both caches in parallel
    await Promise.all([
      this.fs.set(key, data),
      this.redis.set(key, data),
    ])
  }

  async has(key: string) {
    return this.redis.has(key) || this.fs.has(key)
  }

  async delete(key: string) {
    await Promise.all([
      this.fs.delete(key),
      this.redis.delete(key),
    ])
  }

  async revalidateTag(tag: string) {
    await Promise.all([
      this.fs.revalidateTag(tag),
      this.redis.revalidateTag(tag),
    ])
  }
}