Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/docs-post-1-0-3.md
Original file line number Diff line number Diff line change
@@ -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.
19 changes: 18 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,17 @@
[![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
> observation run on `0.1.0-rc.1` with 0 errors, and a Redis-reboot drill
> 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**
Expand Down Expand Up @@ -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/<KIND>/<hash>/$/<path>`) 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
Expand Down Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion mcp/package.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
4 changes: 2 additions & 2 deletions mcp/server.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
Expand Down
2 changes: 1 addition & 1 deletion mcp/src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
});
}
);
Expand Down
16 changes: 13 additions & 3 deletions skills/nextjs-redis-cache/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 —
Expand Down Expand Up @@ -122,7 +131,8 @@ ElastiCache reboot drill: 2550 requests, zero 5xx).
are HITs instead of a regeneration stampede:
`REDIS_URL=... DEPLOYMENT_VERSION=<deploy-id> 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.
Expand Down
Loading