diff --git a/.changeset/docs-post-1-0-3.md b/.changeset/docs-post-1-0-3.md new file mode 100644 index 0000000..b1c463c --- /dev/null +++ b/.changeset/docs-post-1-0-3.md @@ -0,0 +1,5 @@ +--- +"@leejpsd/nextjs-cache-handler": patch +--- + +Docs only. README: note on Next.js 16.3.8+ route-scoped keys and the `seed` version they need, the 1.0.2 and 1.0.3 changes in the version history, and which Next.js versions those releases were run against. Agent skill: single-argument `revalidateTag(tag)` is a hard invalidation (it was listed as soft), plus the version checks for the 1.0.2 and 1.0.3 fixes. diff --git a/README.md b/README.md index 8700f34..241cf0e 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![npm](https://img.shields.io/npm/v/@leejpsd/nextjs-cache-handler.svg)](https://www.npmjs.com/package/@leejpsd/nextjs-cache-handler) [![license](https://img.shields.io/npm/l/@leejpsd/nextjs-cache-handler.svg)](./LICENSE) -> **`v1.0.0`** — install with +> **`v1.0`** — install with > `npm install @leejpsd/nextjs-cache-handler`, or wire everything with > `npx nextjs-cache-handler init --yes`. Validated on a staging demo > deployment (AWS ECS Fargate, two instances, ElastiCache Redis): a 24h @@ -11,6 +11,9 @@ > under ~14 req/s with zero 5xx across 2,550 requests > ([`docs/staging-verification-2026-08-01.md`](./docs/staging-verification-2026-08-01.md)). > Exercised end-to-end against **Next.js 16.3** (both cache interfaces). +> The 1.0.2 fixes (seeding, tag invalidation) were additionally run by hand +> against Next.js 16.2.4, 16.3.8 and 16.4.6 with a real Redis, and the 1.0.3 +> fix (Redis outage) against 16.4.6; `cacheHandler` only. > > v0.4 adds: **build-output cache seeding** (first request after deploy is a > HIT), **pub/sub tag propagation** (~3ms cross-instance), **Redis Cluster** @@ -394,6 +397,13 @@ API/concept mapping, config diff, and a seeding replacement: > `cacheLife` **expire** now triggers a blocking revalidation instead of > serving stale (matching `'use cache'` semantics); within > `revalidate..expire` stale-while-revalidate is unchanged. +> +> **On Next.js 16.3.8 or later?** Route entries are keyed by source route +> (`/route-cache///$/`) instead of the pathname. The +> handlers store whatever key Next passes, so nothing changes at runtime, +> but `seed` needs **1.0.2 or later**: earlier versions wrote pathname keys +> that 16.3.8+ never reads, so the first request after a deploy was a +> `MISS`. - **Next.js**: `>=15.0.0 <17` - `cacheHandler` (singular, ISR): Next **15 and 16** — the handler accepts @@ -435,6 +445,13 @@ ESM and CJS dual-published, full TypeScript types, validated via served with `revalidate: -1` instead of a backdated timestamp ✅ - **v1.0.0** *(2026-08)* — public API frozen under semver; every export documented in [`docs/api.md`](./docs/api.md) ✅ + - *1.0.2* — `cacheHandler`: `revalidateTag(tag, 'max')` no longer turns + every tagged entry into a miss for a year; hard invalidation is immune + to clock skew between instances. `seed`: route-scoped keys for Next + 16.3.8+ (App and Pages Router), and the root route on older versions ✅ + - *1.0.3* — `cacheHandler`: `revalidateTag` rejects when the tag state + could not be written (no Redis connection) instead of reporting + success ✅ - **Next** — Vercel KV / Upstash adapters, `'use cache: remote'` multi-tier setup, `neshClassicCache` equivalent. All additive; no 2.0 needed. diff --git a/mcp/package.json b/mcp/package.json index f95b5b7..ff13ed0 100644 --- a/mcp/package.json +++ b/mcp/package.json @@ -1,6 +1,6 @@ { "name": "@leejpsd/nextjs-cache-handler-mcp", - "version": "0.1.2", + "version": "0.1.3", "description": "MCP server for inspecting and operating @leejpsd/nextjs-cache-handler Redis caches \u2014 health, key inspection, tag state, SWR simulation, and dry-run-first invalidation for AI agents.", "keywords": [ "mcp", diff --git a/mcp/server.json b/mcp/server.json index 74fe0c4..d1799ff 100644 --- a/mcp/server.json +++ b/mcp/server.json @@ -7,13 +7,13 @@ "source": "github", "subfolder": "mcp" }, - "version": "0.1.2", + "version": "0.1.3", "packages": [ { "registryType": "npm", "registryBaseUrl": "https://registry.npmjs.org", "identifier": "@leejpsd/nextjs-cache-handler-mcp", - "version": "0.1.2", + "version": "0.1.3", "transport": { "type": "stdio" }, diff --git a/mcp/src/server.ts b/mcp/src/server.ts index d2c7000..8ffe10a 100644 --- a/mcp/src/server.ts +++ b/mcp/src/server.ts @@ -243,7 +243,7 @@ server.tool( tag, isr: { key: isrKey, state: isrRaw ? (JSON.parse(isrRaw) as unknown) : null }, useCache: plural, - hint: "ISR: 'expired' hits all kinds, 'stale' is SWR. 'use cache': entries older than invalidatedAt serve stale-while-revalidate.", + hint: "ISR: 'expired' without 'stale' is a hard invalidation (all kinds miss). With 'stale', 'expired' is the soft deadline (e.g. a year ahead for revalidateTag(tag, 'max')) and only becomes a hard miss once it has passed; until then 'stale' means SWR for routes and a miss for fetch entries. 'use cache': entries older than invalidatedAt serve stale-while-revalidate.", }); } ); diff --git a/skills/nextjs-redis-cache/SKILL.md b/skills/nextjs-redis-cache/SKILL.md index b286ba6..92aef7d 100644 --- a/skills/nextjs-redis-cache/SKILL.md +++ b/skills/nextjs-redis-cache/SKILL.md @@ -85,13 +85,22 @@ the builder. | Call | Effect | Mechanism | |---|---|---| -| `revalidateTag(tag)` / `revalidateTag(tag, "max")` | **SOFT / SWR**: keep serving stale instantly, re-render in background, all instances converge (~1-2s) | marker write; read path backdates entries | -| `updateTag(tag)` (server action) / hard expire | **HARD**: entries deleted now, next read blocks and regenerates | Lua atomic delete | +| `revalidateTag(tag, "max")` | **SOFT / SWR**: keep serving stale instantly, re-render in background, all instances converge (~1-2s) | marker write; read path backdates entries | +| `updateTag(tag)` (server action) / single-argument `revalidateTag(tag)` (deprecated in Next 16) / hard expire | **HARD**: entries deleted now, next read blocks and regenerates | Lua atomic delete | | `revalidatePath(path)` | implicit route tags (`_N_T_/...`) flow through the soft path; Next additionally hard-discards via `getExpiration` | | Facts that prevent misdiagnosis: - Soft invalidation is NOT lost: it serves STALE content briefly by design. If content "never updates", check version >= 0.3.3 first. +- If pages on `cacheHandler` (ISR) stay `MISS` on every request after a + `revalidateTag(tag, "max")`, upgrade to >= 1.0.2 (earlier versions read + the one-year soft deadline as already expired). +- Invalidation that cannot reach Redis: `cacheHandler` (ISR) rejects it + (>= 1.0.3); `cacheHandlers` rejects hard invalidation and treats soft as + best-effort. Next only awaits `updateTag()` in a Server Action, so only + that request fails (500). `revalidateTag(tag, "max")` runs after the + response, so a rejection shows up in the server log, not in the HTTP + status (measured on Next 16.4.6 with `cacheHandler`). - The instance that fires `revalidateTag` refreshes eagerly (read-your-own-writes). Other instances converge on their next request. - Explicit `cacheTag()` tags are checked by the HANDLER, not by Next — @@ -122,7 +131,8 @@ ElastiCache reboot drill: 2550 requests, zero 5xx). are HITs instead of a regeneration stampede: `REDIS_URL=... DEPLOYMENT_VERSION= npx nextjs-cache-handler seed` (run after `next build`, e.g. a Docker entrypoint step; NX semantics — - never overwrites live entries). + never overwrites live entries). On Next >= 16.3.8 this needs package + version >= 1.0.2; older versions seed keys that Next no longer reads. - **`npx nextjs-cache-handler init --yes`** wires everything above automatically; **`npx nextjs-cache-handler doctor`** is the first command to run when debugging connectivity or key-layout issues.