A reliable, drop-in cacheHandlers implementation: 'use cache' backed by memcached (including AWS ElastiCache Serverless) instead of a per-pod in-memory LRU. A dead cache costs misses, never stale data, never a broken render.

Memcached as the shared cache behind Next.js cacheHandlers ('use cache' / Cache Components). Built for self-hosted deployments (Kubernetes, ECS, bare VMs) where every pod must share one cache instead of keeping its own in-memory LRU.

Fail-safe by construction: a dead memcached costs you cache misses, never render errors, and never stale data.

Principles

1. Native. A drop-in cacheHandlers implementation. One config entry plus one env var, and the default export is the handler instance Next.js already expects, so there's no custom wiring and no surprising deviation from the documented interface.
2. Reliable. Consistent, correct content over raw speed. Where the two trade off, correctness wins, and a slow or dead cache degrades to "no caching," never to stale or broken output. Roadmap: a built-in circuit breaker that trips this same fallback automatically under sustained failure instead of relying on per-op timeouts alone.
3. Observable. Instrumented so operators can see what the cache is doing, not just guess from application logs. Roadmap: first-class telemetry, metrics and traces, out of the box.

Highlights

• AWS ElastiCache Serverless ready. TLS via memcaches://, text protocol only, TTL clamps that respect serverless LRU eviction. Tested against a real serverless cache.
• O(1) tag invalidation, no key lists. Hard (updateTag) and soft (revalidateTag(tag, 'max'), stale-while-revalidate) both supported; invalidation cost does not grow with the number of entries carrying the tag.
• Every failure degrades to "no caching". 750 ms op budget, versioned envelope (corrupt entries read as misses), eviction-safe tag records, a total exception guard on every method.
• Proven in CI. Integration suite against live memcached (plain and TLS), Node 22/24, and a Next.js compat matrix: 16.3 floor, latest 16.x, canary.

[!WARNING] Pre-1.0, not yet published to npm, and under heavy development. Expect constant breaking changes to the config shape, the envelope format, and the exported API until v1.0.0 ships. Pin a commit, not a range, and re-read this doc before every update.

[!NOTE] TLS support ships in the upstream memcache client since 1.10.0 (SeatGeek's contribution).

Install

npm install @seatgeek/next-memcached   # or pnpm add / yarn add / bun add

Requires Node >= 22.19 and Next.js >= 16.3 with Cache Components (see Next.js compatibility).

Quick start

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheHandlers: {
    default: require.resolve("@seatgeek/next-memcached"),
  },
  // Disable Next's default in-memory LRU so memcached is authoritative.
  cacheMaxMemorySize: 0,
};

export default nextConfig;

Point it at memcached:

# plain
MEMCACHED_URI=localhost:11211
# ElastiCache Serverless (TLS)
MEMCACHED_URI=memcaches://my-cache.serverless.use1.cache.amazonaws.com:11211

Two details are easy to get wrong: the default export is the handler instance (not a factory), and cacheMaxMemorySize: 0 is not optional (without it, an outage silently degrades to divergent per-pod caching). Both are explained in getting started.

Documentation

Everything past the quick start lives alongside this file:

| Doc | Contents | | --- | --- | | Getting started | Config reference, first cached function, the example app, links to Vercel's own docs | | How it works | Keys, envelope, tag versioning, failure modes, TTL clamp, the page-level cache trap | | Roadmap | Compression, circuit breaker, benchmarks, larger items, telemetry, external logger, protocol and pooling evaluations, Next.js 15 | | Next.js compatibility | Supported versions, feature compatibility matrix, the CI compat matrix | | Contributing | Setup, quality gates, example smoke test | | Releasing | Tag-driven publish flow, guards, one-time npm setup | | Security | Reporting, and the memcached no-auth threat model |

Package invariants (fail-safe methods, never-stale eviction semantics, stream draining, TTL clamps) live in AGENTS.md and are enforced by tests and CI.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Vercel or Amazon Web Services. "Next.js" and "Vercel" are trademarks of Vercel, Inc. "Amazon ElastiCache" is a trademark of Amazon.com, Inc. or its affiliates. memcached is a project of the memcached community (see memcached.org).

License

Apache-2.0 © SeatGeek