Redis caching in Node.js: the patterns I use in production (with code)

I added Redis caching to a Node.js dashboard API at the wrong layer once and made it slower. Cache hit ratio was 92%, latency on cache hits was 4ms. Latency on cache misses went from 180ms to 340ms because the cache lookup was now blocking the database call instead of running in parallel with a circuit breaker. Three days of staring at clinic.js output to figure out why caching had backfired. The answer was the cache pattern, not Redis. This is the version that actually works — the patterns I drop into every Node.js + Redis project on Node 24 LTS with ioredis 5.x against Redis 8.x, with the bugs they prevent.

Step 0: when caching is actually the answer

Before installing anything, name the bottleneck. Caching helps when:

• The same data is requested by many clients within a short window (read amplification).
• The cost of recomputing or refetching is high relative to a Redis round-trip (~1ms on the same network, ~3ms across an Availability Zone).
• The data is allowed to be slightly stale.

If the data changes faster than your TTL, or every request is unique, caching adds overhead and complexity for nothing. Don’t cache user-specific data with a 1-second TTL — you’re paying for the round-trip and getting almost no hits. If the bottleneck is the database itself, fix the schema and indexes first — the Postgres + Prisma setup guide covers the patterns. The break-even calculus is in the Node.js performance optimization guide: a Redis hit at ~1ms only beats a Postgres query if the query is >3ms and your hit ratio clears 80%.

ioredis vs node-redis: the actual call

Two serious clients in 2026: redis (the official client, v5) and ioredis (v5.6.x). They are functionally close. The differences that matter at production scale:

I run ioredis on every project. The deciding factor is BullMQ — same connection pool for cache + queues — see the BullMQ background jobs guide. If you do not run BullMQ and you want the official client, node-redis is fine.

npm i ioredis

// src/redis.ts
import Redis from "ioredis";
import { env } from "./env.js";

export const redis = new Redis(env.REDIS_URL, {
  maxRetriesPerRequest: 3,
  enableReadyCheck: true,
  lazyConnect: false,
  retryStrategy: (times) => Math.min(times * 200, 2000),
  reconnectOnError: (err) => {
    // Reconnect on READONLY errors (failover from primary to replica)
    return err.message.includes("READONLY");
  },
});

redis.on("error", (err) => {
  // Don't crash the process on Redis hiccups — degrade gracefully.
  console.error("redis error", err.message);
});

redis.on("ready", () => console.log("redis ready"));

The retryStrategy is the part most teams skip. The default in ioredis is reasonable, but I tighten the cap to 2 seconds — past that, you should be serving from origin, not waiting on Redis to come back. reconnectOnError handles the moment a managed Redis fails over: replicas reject writes with READONLY, the client reconnects, the new primary accepts the next write.

Cache patterns: the table that decides which one

“Use Redis” is not a strategy. The pattern decides whether caching helps or hurts.

For 90% of Node.js APIs you want cache-aside with single-flight on hot keys. Write-through earns its keep when you have a small set of records that are written and immediately re-read — payment receipts after a successful charge, for example.

Cache-aside with a reusable helper

The shape every cache-aside call collapses to is the same: key, TTL, fallback function. Wrap it once.

// src/cache.ts
import { redis } from "./redis.js";

export async function withCache<T>(
  key: string,
  ttlSeconds: number,
  fetchFn: () => Promise<T>,
): Promise<T> {
  try {
    const cached = await redis.get(key);
    if (cached) return JSON.parse(cached) as T;
  } catch (err) {
    // Redis down? Skip cache, hit origin. Don't fail the request.
    console.error("cache read failed", { key, err: (err as Error).message });
  }

  const data = await fetchFn();
  if (data !== null && data !== undefined) {
    redis
      .set(key, JSON.stringify(data), "EX", ttlSeconds)
      .catch((err) => console.error("cache write failed", { key, err: err.message }));
  }
  return data;
}

Usage in a route handler stays one line:

import { withCache } from "../cache.js";
import { db } from "../db.js";

export async function getUserById(userId: string) {
  return withCache(`user:${userId}:v3`, 300, () =>
    db.user.findUnique({ where: { id: userId } }),
  );
}

Three things worth naming:

1. The key is namespaced and versioned. user:abc:v3, not abc. Without namespacing, your cache becomes a minefield of key collisions the first time you cache a second resource type. The version suffix is your invalidation lever — bump v3 to v4 on a schema change and old keys age out via TTL.
2. Cache writes are fire-and-forget. The .catch on redis.set means a slow Redis write doesn’t block the response.
3. Read failures degrade to origin. A try/catch around redis.get is the difference between “Redis is down for 30 seconds, latency goes up” and “Redis is down for 30 seconds, the API is down.” Always degrade.

Express middleware for whole-response caching

For HTTP endpoints where the response body is identical for every caller (public product pages, sitemap data), cache the full response upstream of the route handler. X-Cache: HIT headers help debugging.

// src/cache-middleware.ts
import type { Request, Response, NextFunction } from "express";
import { redis } from "./redis.js";

export function cacheResponse(ttlSeconds: number) {
  return async (req: Request, res: Response, next: NextFunction) => {
    if (req.method !== "GET") return next();
    const key = `http:${req.originalUrl}`;

    try {
      const cached = await redis.get(key);
      if (cached) {
        res.setHeader("X-Cache", "HIT");
        res.setHeader("Content-Type", "application/json");
        return res.send(cached);
      }
    } catch {
      /* degrade silently */
    }

    res.setHeader("X-Cache", "MISS");
    const originalJson = res.json.bind(res);
    res.json = (body: unknown) => {
      const payload = JSON.stringify(body);
      if (res.statusCode >= 200 && res.statusCode < 300) {
        redis.set(key, payload, "EX", ttlSeconds).catch(() => {});
      }
      res.setHeader("Content-Type", "application/json");
      return res.send(payload);
    };
    next();
  };
}

app.get("/api/products/:id", cacheResponse(600), async (req, res) => {
  const product = await db.product.findUnique({ where: { id: req.params.id } });
  if (!product) return res.status(404).json({ error: "not found" });
  res.json(product);
});

Two notes: the middleware ships the cached JSON as a string straight to res.send, skipping a round-trip through JSON.parse+JSON.stringify. And it only caches 2xx responses — caching a 500 with a 5-minute TTL is a way to extend an outage.

Cache key naming for paginated lists

Paginated endpoints look stateless but turn into a key-explosion problem the first time you cache them. The key has to include every parameter that affects the response.

function listKey(opts: { page: number; limit: number; category?: string; sort?: string }) {
  return [
    "products",
    `p${opts.page}`,
    `l${opts.limit}`,
    `c${opts.category ?? "all"}`,
    `s${opts.sort ?? "default"}`,
  ].join(":");
}
// products:p1:l20:cbooks:sprice

Skip JSON.stringify(opts) as the key. Object key ordering is not stable across all V8 versions for non-string keys, and the resulting key is much larger than it needs to be. Build the key from primitives in a fixed order.

Invalidation: the part nobody wants to think about

The cache is a lie if you don’t invalidate it on writes. Three patterns I lean on, ranked by how often I reach for them:

1. Versioned keys. Cache key includes a version suffix (user:abc:v3). On a global schema change, bump the version. Old keys age out via TTL. No bulk delete. This is what I default to.
2. Direct delete on write. For known-affected keys, delete them after the source write succeeds.
3. Tag-based invalidation. Store a Redis Set tags:user:abc containing every cache key that includes data for user abc. On update, delete every key in the set, then delete the set itself. Heavier but more flexible.

export async function updateUserEmail(userId: string, email: string) {
  await db.user.update({ where: { id: userId }, data: { email } });
  await redis.del(`user:${userId}:v3`);
  await redis.del(`user:${userId}:profile:v3`, `dashboard:user:${userId}:v3`);
}

One trap: do not use KEYS pattern for bulk delete on a busy Redis. KEYS is O(n) over the entire keyspace and blocks the server. Use SCAN + UNLINK instead:

export async function deleteByPattern(pattern: string) {
  const stream = redis.scanStream({ match: pattern, count: 100 });
  for await (const keys of stream) {
    if (keys.length) await redis.unlink(...keys); // UNLINK is non-blocking DEL
  }
}

Thundering herd: the bug that took me three days

The dashboard API was rebuilding a per-customer report on every cache miss. Cache TTL was 60 seconds. When the cache expired, every concurrent request hit the database simultaneously and rebuilt the same report 47 times in parallel. Database fell over.

Fix: lock the rebuild. The first miss takes the lock and rebuilds; everyone else waits.

// src/single-flight.ts
import { redis } from "./redis.js";

const inFlight = new Map<string, Promise<unknown>>();

export async function singleFlight<T>(
  key: string,
  ttlSeconds: number,
  build: () => Promise<T>,
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached) as T;

  // Process-local dedupe — same Node process, same key, one rebuild
  const local = inFlight.get(key);
  if (local) return local as Promise<T>;

  const lockKey = `lock:${key}`;
  const acquired = await redis.set(lockKey, process.pid.toString(), "EX", 10, "NX");

  if (!acquired) {
    // Another process is rebuilding. Brief wait, then re-read.
    await new Promise((r) => setTimeout(r, 75 + Math.random() * 75));
    return singleFlight(key, ttlSeconds, build);
  }

  const work = (async () => {
    try {
      const data = await build();
      await redis.set(key, JSON.stringify(data), "EX", ttlSeconds);
      return data;
    } finally {
      await redis.del(lockKey);
      inFlight.delete(key);
    }
  })();

  inFlight.set(key, work);
  return work;
}

Two layers of dedupe. The inFlight Map kills duplicate rebuilds inside the same Node process. The Redis SET NX EX kills duplicate rebuilds across processes. The 75ms+jitter wait stops every retrier waking up at exactly the same moment and stampeding the lock check.

This is a single-Redis lock. For real distributed locking across many Redis nodes, use node-redlock. For most caching scenarios, SET NX EX plus the in-process Map is enough.

Negative caching: handle “not found” too

If your endpoint takes random IDs from URLs, attackers (or legitimate broken links) can hammer “not found” paths and bypass your cache entirely — every request hits the database to confirm the user does not exist. Cache the absence with a short TTL.

const NOT_FOUND_TTL = 30; // seconds — short on purpose
const NOT_FOUND_SENTINEL = "__nf__";

export async function getUserCached(userId: string) {
  const key = `user:${userId}:v3`;
  const cached = await redis.get(key);
  if (cached === NOT_FOUND_SENTINEL) return null;
  if (cached) return JSON.parse(cached);

  const user = await db.user.findUnique({ where: { id: userId } });
  if (user) {
    await redis.set(key, JSON.stringify(user), "EX", 300);
  } else {
    await redis.set(key, NOT_FOUND_SENTINEL, "EX", NOT_FOUND_TTL);
  }
  return user;
}

Keep the negative TTL much shorter than the positive TTL — you don’t want a user who just signed up to look not-found for 5 minutes. 30 seconds is usually fine; tune it down to 5 for high-write systems.

Batch reads: pipelines and MGET

One GET takes ~1ms. Ten sequential GETs take ~10ms. Ten GETs in one round-trip take ~1.2ms. If you are hydrating a list of 50 items, this is the difference between a 60ms route and a 5ms route.

export async function getUsersByIds(ids: string[]) {
  const keys = ids.map((id) => `user:${id}:v3`);
  const cached = await redis.mget(...keys); // single round-trip
  const result: Record<string, unknown> = {};
  const misses: string[] = [];

  ids.forEach((id, i) => {
    const value = cached[i];
    if (value) result[id] = JSON.parse(value);
    else misses.push(id);
  });

  if (misses.length) {
    const fresh = await db.user.findMany({ where: { id: { in: misses } } });
    const pipeline = redis.pipeline();
    for (const u of fresh) {
      result[u.id] = u;
      pipeline.set(`user:${u.id}:v3`, JSON.stringify(u), "EX", 300);
    }
    await pipeline.exec();
  }
  return ids.map((id) => result[id]);
}

One round-trip for the read, one round-trip for the writes. Fifty users hydrated in roughly the latency of one cache lookup.

Don’t serialize JSON for hot reads

Once you’re past 5,000 cache reads per second, JSON.parse on a 4 KB blob becomes the bottleneck. Three options:

• Cache the already-formatted response body, not the parsed object. If the consumer is HTTP, ship the JSON string straight to the wire. The Express middleware above already does this.
• Use Redis Hashes for fielded data. If you’re only reading two fields out of a 12-field user object, HGET user:abc email avoids fetching and parsing the rest.
• Switch to a binary format like MessagePack. Faster to parse and smaller on the wire — Redis stores fewer bytes per key.

For a dashboard endpoint serving 12,000 req/s, switching to “cache the response string” dropped the API’s CPU usage from 71% to 38%. Same throughput, half the work.

Eviction policy and memory sizing

Redis without an eviction policy is a disk space tank that explodes. The default noeviction rejects writes once maxmemory is hit. For a cache, that’s the wrong default.

Set it in redis.conf or via CONFIG SET maxmemory-policy allkeys-lru. On managed Redis (DigitalOcean, AWS ElastiCache, Upstash), the dashboard exposes the policy as a setting. Confirm it before you ship.

Sizing: a rough rule for an API cache is (avg payload bytes × distinct hot keys × 1.4). The 1.4 multiplier covers Redis’s per-key overhead and string headers. 50,000 hot keys × 4 KB × 1.4 ≈ 280 MB. The smallest managed Redis tier (1 GB) is plenty for most APIs until you cross 200,000 hot keys.

Circuit breaker around Redis

“Cache failure should not cause request failure.” Sounds obvious; the failure mode I see most often is the opposite. Long Redis timeouts under load make Redis the bottleneck instead of helping.

// src/cache-breaker.ts
let failures = 0;
let openUntil = 0;

const FAIL_THRESHOLD = 5;
const OPEN_FOR_MS = 5_000;
const CALL_TIMEOUT_MS = 50;

export async function safeRedis<T>(op: () => Promise<T>): Promise<T | null> {
  if (Date.now() < openUntil) return null; // circuit open: skip cache

  try {
    const result = await Promise.race([
      op(),
      new Promise<never>((_, rej) =>
        setTimeout(() => rej(new Error("redis timeout")), CALL_TIMEOUT_MS),
      ),
    ]);
    failures = 0;
    return result;
  } catch (err) {
    failures++;
    if (failures >= FAIL_THRESHOLD) openUntil = Date.now() + OPEN_FOR_MS;
    return null;
  }
}

Wrap your redis.get and redis.set calls in safeRedis. If Redis stops responding within 50ms, the breaker trips for 5 seconds and the API serves directly from origin. Recovery is automatic. The numbers tune to your tolerances — for a checkout API I’d cap timeouts even tighter, at 25ms.

Sentinel, Cluster, TLS — short version

Single-node Redis is fine up to ~100K ops/s on modern hardware. Past that, or for actual high availability, you have two options:

• Sentinel. One primary, multiple replicas, a Sentinel quorum that promotes a replica on primary failure. Same data on every node — no sharding. ioredis has first-class Sentinel support: new Redis({ sentinels: [...], name: "mymaster" }).
• Cluster. Sharded across multiple primaries, each with its own replica set. Picks up at the point Sentinel can’t keep up. new Redis.Cluster([{ host, port }]).

For TLS to managed Redis (most cloud providers default to TLS now), pass tls: {} to the connection options. The empty object enables TLS with default certificate validation; for self-signed certs in dev, set tls: { rejectUnauthorized: false } — never in production.

Client-side caching with Redis 8 RESP3

RESP3 and the tracking protocol were introduced in Redis 6 and stabilised through 7. Redis 8 dropped the per-connection tracking buffer overhead further. The client subscribes to invalidation messages from the server and keeps a local LRU; the server tells the client when a key changed and the local entry is dropped. Lookup latency for hot keys drops to memory-access speed instead of a Redis round-trip.

// ioredis 5.4+ supports RESP3 client tracking
import Redis from "ioredis";

export const redis = new Redis(env.REDIS_URL, {
  enableAutoPipelining: true,
  // RESP3 needs to be explicitly opted into for tracking
  // Use the "redis" official client for the cleanest tracking API today
});

For now, node-redis v5 has the more polished tracking API. If you want client-side caching in 2026, this is the case where I’d run node-redis alongside ioredis. Most teams don’t need this — the round-trip to Redis is already fast enough — but for the top 1% of read paths it matters.

Decision matrix: pick the pattern by use case

When NOT to cache

• Strongly-consistent reads. Banking balances, current inventory in checkout flows. Stale-by-1-second is wrong here.
• Per-request unique data. Search queries with rare filters, user-specific feeds with frequent updates. Hit rate will be near zero — you’re adding latency for no win.
• Workloads where the source is already fast. If the database query is 3ms, adding Redis adds 1ms on hit and 4ms on miss. Net loss unless your hit rate is > 85%.
• Data that’s already in HTTP cache. If your CDN fronts the API and caches at the edge for 60 seconds, adding a Redis cache layer for the same response saves nothing.

Operational notes from production

• Set maxmemory-policy allkeys-lru. Otherwise Redis fills up and starts rejecting writes. allkeys-lru evicts the least-recently-used key when memory hits the cap.
• Monitor hit ratio. Redis INFO stats exposes keyspace_hits and keyspace_misses. Below 80%, your TTL is too short or your access pattern doesn’t match what you’re caching. Below 30%, you should not be caching this data.
• Don’t store large blobs. Redis is fast on small values (< 10 KB). Past 100 KB per value, you’re using Redis as a slow-but-networked memory store. Move large data to S3 or similar and cache the metadata. The break-even math is in the Node.js performance optimization guide.
• Avoid FLUSHALL on a shared Redis. If your cache and your BullMQ queue share a Redis (which they should), FLUSHALL deletes every queue, every job, every scheduled cron. Use UNLINK with a pattern instead.
• Run Redis in a separate AZ from app. Cross-AZ latency is 2–4ms. If your cache hit is 1ms, suddenly a hit is 5ms and the win shrinks. Co-locate. Cloud-specific deploys are covered in the DigitalOcean Node.js deployment guide.
• Pin the Redis client version. ioredis@^5.6.0 is the current line in 2026; minor versions land monthly and occasionally tighten retry behaviour. Pin the lockfile, watch the changelog.

Production checklist

• [ ] retryStrategy capped at 2s
• [ ] reconnectOnError handles READONLY for managed-Redis failover
• [ ] All cache reads wrapped in try/catch — degrade to origin on failure
• [ ] Cache writes are fire-and-forget (no await on the response path)
• [ ] Hot rebuilds protected by single-flight (in-process Map + Redis lock)
• [ ] Cache keys are namespaced and versioned (resource:id:vN)
• [ ] SCAN + UNLINK for bulk invalidation, never KEYS + DEL
• [ ] Negative caching for “not found” with a short TTL
• [ ] maxmemory-policy set to allkeys-lru (or allkeys-lfu for stable hot sets)
• [ ] Hit ratio dashboard from INFO stats
• [ ] Circuit breaker with 50ms timeout in front of Redis calls
• [ ] TLS enabled to managed Redis (tls: {} in client options)

FAQ