Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
npx -y @leejpsd/[email protected]Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
claude mcp add leejpsd-nextjs-cache-handler-mcp -- npx -y @leejpsd/nextjs-cache-handler-mcp@0.1.3รันในเทอร์มินัล
{ "mcpServers": { "leejpsd-nextjs-cache-handler-mcp": { "command": "npx", "args": [ "-y", "@leejpsd/[email protected]" ] } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
v1.0.0— install with , or wire everything with . Production-validated against AWS ECS Fargate with multi-instance Redis (24h live-traffic soak and a live Redis-reboot drill with zero 5xx — see ), and exercised end-to-end against (both cache interfaces).
MCP server for inspecting and operating @leejpsd/nextjs-cache-handler Redis caches — health, key inspection, tag state, SWR simulation, and dry-run-first invalidation for AI agents.
npm install @leejpsd/nextjs-cache-handlernpx nextjs-cache-handler init --yesv0.4 adds: build-output cache seeding (first request after deploy is a
HIT), pub/sub tag propagation (~3ms cross-instance), Redis Cluster
e2e in CI, a CLI (init / doctor / seed), and agent-native assets
(skill, rules, MCP server).
1.0 freezes the public API under semver — the eight entry points, the
CacheHandlerOptions surface, the Redis key shapes and tag-marker format,
and the metric event names. Upgrading from 0.4.x needs no changes.
Working with Claude Code / Codex / Cursor? Give your agent this URL and it will install and wire everything (version detection, wrapper files, next.config patch, verification):
https://raw.githubusercontent.com/leejpsd/nextjs-cache-handler/main/setup-instructions/setup.md
An agent skill with decision tables, invalidation semantics, and a
troubleshooting playbook ships in the package (AGENTS.md,
skills/nextjs-redis-cache/SKILL.md) and via
npx skills add leejpsd/nextjs-cache-handler.
For cache operations from your agent (health, tag state, safe invalidation),
the companion MCP server is on the official registry as
io.github.leejpsd/nextjs-cache-handler-mcp — or one command:
npx nextjs-cache-handler init --yes wires handlers, rules, and .mcp.json together.
The Redis cache handler for Next.js 15/16 that ships both cacheHandler
(ISR / Pages Router) and cacheHandlers ('use cache' directive,
cacheComponents: true) — the area where
@fortedigital/nextjs-cache-handler
currently lists "Help needed".
// next.config.ts
const nextConfig = {
cacheComponents: true,
cacheHandler: require.resolve("./cache-incremental.cjs"),
cacheHandlers: { default: require.resolve("./cache-components.cjs") },
};
// cache-components.cjs
const { createCacheComponentsHandler } = require("@leejpsd/nextjs-cache-handler/cache-components");
module.exports = createCacheComponentsHandler({
client: { type: "redis", url: process.env.REDIS_URL },
buildNamespace: process.env.DEPLOYMENT_VERSION, // auto-isolates deploys
});
That's it. 'use cache', revalidateTag, updateTag, cacheLife all work.
Next.js 16 split caching into two handler interfaces:
As of 2026-05, the leading OSS Redis handler @fortedigital/[email protected]
declares peerDependencies.next: ">=16.1.5" but the README marks the new
plural interface as ❌ "Not yet supported - Help needed":
📅 Compatibility matrix re-verified 2026-07-31 (from each project's published README/registry metadata). The OSS Next.js cache handler ecosystem moves quickly — please verify
@fortedigitalandnextjs-turbo-redis-cachedirectly before relying on this comparison.
PR #207 on
@fortedigital (their cacheHandlers attempt) was held up in review over
PHASE_PRODUCTION_BUILD handling — which this package has from the start.
npm install @leejpsd/nextjs-cache-handler redis
# or
npm install @leejpsd/nextjs-cache-handler ioredis
redis and ioredis are optional peer dependencies — install whichever
client you use. Both can be present.
Two CommonJS wrapper files in your project root (Next.js's
require.resolve pattern doesn't accept ESM directly):
// cache-components.cjs
const { createCacheComponentsHandler } = require("@leejpsd/nextjs-cache-handler/cache-components");
module.exports = createCacheComponentsHandler({
client: { type: "redis", url: process.env.REDIS_URL },
buildNamespace: process.env.DEPLOYMENT_VERSION,
abortTimeoutMs: 1500,
});
// cache-incremental.cjs
const { createIncrementalCacheHandler } = require("@leejpsd/nextjs-cache-handler/incremental");
module.exports = createIncrementalCacheHandler({
client: { type: "redis", url: process.env.REDIS_URL },
buildNamespace: process.env.DEPLOYMENT_VERSION,
abortTimeoutMs: 1500,
});
// next.config.ts
import path from "path";
import type { NextConfig } from "next";
const enabled = !!process.env.REDIS_URL && process.env.DISABLE_REDIS_CACHE_HANDLER !== "true";
const nextConfig: NextConfig = {
output: "standalone",
outputFileTracingRoot: path.join(__dirname),
cacheComponents: true,
deploymentId: process.env.DEPLOYMENT_VERSION,
generateBuildId: async () => process.env.DEPLOYMENT_VERSION ?? "dev-build",
cacheMaxMemorySize: 0, // delegate everything to the Redis handler
cacheHandler: enabled ? require.resolve("./cache-incremental.cjs") : undefined,
cacheHandlers: enabled ? { default: require.resolve("./cache-components.cjs") } : {},
};
export default nextConfig;
// app/blog/page.tsx
import { cacheLife, cacheTag, revalidateTag } from "next/cache";
async function getPosts() {
"use cache";
cacheLife("hours");
cacheTag("posts");
return await db.post.findMany();
}
// Server Action — invalidate
async function publishPost(formData: FormData) {
"use server";
await db.post.create({ data: Object.fromEntries(formData) });
revalidateTag("posts", "max");
}
export default async function Page() {
const posts = await getPosts();
return <ul>{posts.map((p) => <li key={p.id}>{p.title}</li>)}</ul>;
}
interface CacheHandlerOptions {
client: RedisClientFactory | RedisClientConfig;
keyPrefix?: string; // default: "next-cache:" / "next-incremental:"
buildNamespace?: string | (() => string); // default: env DEPLOYMENT_VERSION || GIT_HASH || "unversioned"
abortTimeoutMs?: number; // default: 1500
fallback?: "auto" | "always" | "never"; // default: "auto"
staleWhileRevalidate?: boolean; // default: true (cache-components only)
singleFlight?: boolean; // default: false — see "Single-flight refresh lock" below
singleFlightLockTtlSec?: number; // default: 10
isBuildPhase?: () => boolean; // override PHASE_PRODUCTION_BUILD detection
hashTag?: boolean; // default: false (set true on Redis Cluster)
memoryMaxEntries?: number; // default: 1000 — LRU cap for the in-memory fallback
compression?: "gzip" | "brotli"; // default: off — transparent value compression (node:zlib)
onMetric?: (event: MetricEvent) => void;
logger?: Logger;
}
type RedisClientConfig =
| { type: "redis"; url: string; password?: string; tls?: boolean; connectTimeout?: number }
| { type: "ioredis"; url: string; password?: string; tls?: boolean; connectTimeout?: number }
| { type: "cluster"; nodes: { host: string; port: number }[]; password?: string; tls?: boolean }
| { type: "sentinel"; sentinels: { host: string; port: number }[]; name: string;
password?: string; sentinelPassword?: string; tls?: boolean; connectTimeout?: number };
Full reference: docs/api.md.
DEPLOYMENT_VERSION env injected at runtime — every entry key is
prefixed with this so old prerender HTML can't bleed across deploys.
For Docker, set ENV DEPLOYMENT_VERSION=... in your runner stage,
not just the builder. (See docs/build-phase.md.)cacheMaxMemorySize: 0 — turn off Next's local LRU so multi-instance
reads always hit Redis (or the explicit memory fallback).outputFileTracingRoot pinned — required for output: "standalone"
to avoid static-chunk-404 issues during a deploy.abortTimeoutMs: 1500 (default) — protects against a stuck Redis
connection from hanging the request thread.hashTag: true — multi-key Lua scripts
(set-with-tags.lua, revalidate-hard.lua) require all KEYS to land
on the same hash slot. Without hashTag, cluster deployments will hit
CROSSSLOT Keys in request don't hash to the same slot. The flag wraps
the namespace in {} so every key for a given deploy hashes together.
Cluster support is validated by a dedicated e2e suite against a real
3-master cluster (npm run test:cluster, also in CI) — covering the
multi-key Lua scripts, per-master SCAN propagation, and both handlers.
Not yet load-tested at production scale.maxmemory-policy: allkeys-lru or noeviction — if you need
bounded memory, choose allkeys-lru. Otherwise noeviction keeps
tag indices intact.rediss:// URLs (e.g. ElastiCache in-transit
encryption). The library auto-detects from the URL scheme./api/health that pings Redis
(separate from the handler) so a Redis outage surfaces in your
monitoring without inducing 5xx in user requests.The cacheHandlers (plural) interface returns stale entries inside the
SWR window so users get an instant response while the background
refresh completes. With many instances, the moment an entry crosses the
revalidate boundary, every instance independently triggers its own
refresh — N parallel re-renders for the same key, each hitting your
origin once.
singleFlight: true adds an opt-in Redis lock (refresh-tag-lock.lua,
default TTL 10s) at the SWR boundary. The first instance to acquire it
becomes the leader and runs the refresh; the rest become
followers, keep serving the same stale entry, and wait for the
leader's write to land. The lock is observability-only at the handler
layer — Next.js still drives the actual refresh; we just suppress the
stampede.
createCacheComponentsHandler({
client: { type: "redis", url: process.env.REDIS_URL },
singleFlight: true, // default false
singleFlightLockTtlSec: 10, // default 10
});
Two new MetricEvent types appear on onMetric:
If lock acquisition fails (Redis hiccup, TTL race), the handler defaults to the follower path — the stale entry is always served, never dropped. This is intentional: the lock is an optimization, not a correctness-critical primitive.
When not to enable single-flight: small fleets (1–2 instances) where Next's per-process serialization already covers the stampede risk. Adding a Redis round-trip per stale read isn't free.
See docs/architecture.md
for the full state machine and a reference to the Lua script body.
The handler doesn't bundle @opentelemetry/api (zero runtime
dependencies stays a goal). Instead, the onMetric(event) hook gives
strictly-typed events you can pipe into whatever observability stack
you already run.
examples/opentelemetry/ is a copy-paste
reference wrapper that:
nextjs_cache.events_total counter dimensioned on
type / freshness / backend / reason / opnextjs_cache.op_latency_ms histogram for events that
carry an ms fieldSee examples/opentelemetry/README.md
for setup and three suggested dashboards (hit rate, single-flight
leadership distribution, op latency tails).
@fortedigital/nextjs-cache-handlerThree deliberate departures, all rooted in lessons from production
incidents (see docs/):
shouldUseRedis() gate that short-circuits when
process.env.NEXT_PHASE === "phase-production-build". PR #207 on
@fortedigital was rejected for missing exactly this.BUILD_NAMESPACE (=process.env.DEPLOYMENT_VERSION) by default. New
deploys can never read entries written by old ones — fixes the
"static chunk 404 after deploy" failure mode without manual cache
flushes.set writes the entry and updates tag
indices in a single Lua transaction. updateTags(..., {expire: 0})
removes matching entries with one EVALSHA. No window for half-applied
sets to leak dangling tag members.When @fortedigital ships its cacheHandlers support (PR #207 / feature
branch feature/cache-components), this package will continue to differ
on (2) and (3). For (1), we consider it table-stakes; the upstream's
eventual implementation should converge on the same behavior.
Coming from @neshca/cache-handler (or its forks like
@jadkins89/next-cache-handler)? There's a dedicated guide with a full
API/concept mapping, config diff, and a seeding replacement:
docs/migrating-from-neshca.md.
Upgrading to Next.js 16.3? Two behavioral notes: (1) 16.3 changed the internal fetch-cache key format (
v3→v4), so 16.2-era fetch entries become unreadable orphans — deploy with a newDEPLOYMENT_VERSIONand let the old namespace age out via TTL. (2) An ISR entry found past itscacheLifeexpire now triggers a blocking revalidation instead of serving stale (matching'use cache'semantics); withinrevalidate..expirestale-while-revalidate is unchanged.
>=15.0.0 <17
cacheHandler (singular, ISR): Next 15 and 16 — the handler accepts
both ctx shapes (Next 15's ctx.revalidate / kindHint, Next 16's
ctx.cacheControl / kind)cacheHandlers (plural, 'use cache'): Next >=16.1.5 only — the
interface does not exist before 16>=20>=5.0.0 (peer, optional)>=5.0.0 (peer, optional) — also powers type: "cluster" and
type: "sentinel" (Sentinel master discovery with automatic failover)ESM and CJS dual-published, full TypeScript types, validated via
arethetypeswrong and
publint.
redis@5 + ioredis adapters, AbortSignal, in-memory fallback
with TTL, soft-tag freshness check ✅redis@5 + ioredis), GitHub Actions
OIDC publish path with provenance attestation ✅/otel), LRU-bounded memory fallback, ESM peer-loading fixes ✅seed CLI, NX-safe),
pub/sub tag propagation, Redis Cluster e2e in CI, init/doctor CLI,
agent assets (skill, rules, MCP server) ✅
updateTags is hard (updateTag() read-your-own-writes), profile
durations are soft with a real hard deadline; tag-stale entries are
served with revalidate: -1 instead of a backdated timestamp ✅docs/api.md ✅'use cache: remote' multi-tier
setup, neshClassicCache equivalent. All additive; no 2.0 needed.MIT © 2026 Eddy Lee
MCP server for inspecting and operating @leejpsd/nextjs-cache-handler Redis caches — health, key inspection, tag state, SWR simulation, and dry-run-first invalidation for AI agents.
{ "mcpServers": { "leejpsd-nextjs-cache-handler-mcp": { "command": "npx", "args": [ "-y", "@leejpsd/[email protected]" ] } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
@leejpsd/nextjs Cache Handler ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-14 MCP server for inspecting and operating @leejpsd/nextjs-cache-handler Redis caches — health, key inspection, tag state, SWR simulation, and dry-run-first invalidation for AI agents.