@leejpsd/nextjs-cache-handler 0.3.4 → 0.4.1

package/setup-instructions/setup.md

@@ -22,7 +22,9 @@ The workflow includes:
   `redis://127.0.0.1:6379` for local verification and tell the user to set
   `REDIS_URL` in their deployment environment.
 - deployment_version_source (optional): how the app derives
-  `DEPLOYMENT_VERSION` (git SHA, CI build id). Default: `git rev-parse --short HEAD`.
+  `DEPLOYMENT_VERSION` (git SHA, CI build id). Default: `git rev-parse
+  --short HEAD`; if the directory is not a git repo, fall back to a fixed
+  value the user chooses (any stable per-deploy string works).
 
 Constraints:
 
@@ -30,7 +32,8 @@ Constraints:
   user Vercel's managed cache already covers them, and stop.
 - You MUST detect the Next.js version before choosing which handlers to wire.
 - You MUST show the `next.config` diff and get explicit approval before
-  writing it — this file frequently contains user customizations.
+  writing it — this file frequently contains user customizations — unless
+  the user has already given blanket approval for changes in this project.
 - You MUST NOT print or commit secrets (Redis passwords, URLs with auth).
 - You MUST install version >= 0.3.3 (earlier versions have an incomplete
   soft-invalidation path).
@@ -94,15 +97,25 @@ user's infrastructure requires them (Cluster additionally needs
 
 ### Step 4: Patch next.config (approval required)
 
-Merge these keys into the existing config — do not replace the file:
+If no `next.config.(js|ts|mjs)` exists, CREATE `next.config.js` with just
+these keys. If one exists, merge the keys into it — do not replace the
+file. Show the diff and get approval first, unless the user already gave
+blanket approval for this project's files:
 
 ```ts
 cacheHandler: require.resolve("./cache-incremental.cjs"),
 cacheHandlers: { default: require.resolve("./cache-components.cjs") }, // Next 16 only
-cacheComponents: true,   // Next 16 only — skip if the user does not want 'use cache'
+cacheComponents: true,   // Next 16 only — see the warning below before enabling
 cacheMaxMemorySize: 0,   // required for multi-instance correctness
 ```
 
+**`cacheComponents: true` decision rule**: enabling it is a MODE SWITCH, not
+a free feature — it is incompatible with route segment configs like
+`export const revalidate` / `export const dynamic` and will FAIL THE BUILD
+of apps that use them. Enable it only when the app already uses (or is
+migrating to) `'use cache'`. When in doubt, wire `cacheHandlers` but leave
+`cacheComponents` off and tell the user how to enable it later.
+
 Show the diff, get approval, then write.
 
 **Error handling:**
@@ -125,16 +138,25 @@ Append both to `.env.example` if the project has one.
 ### Step 6: Verify
 
 With a local Redis (`docker run -d -p 6379:6379 redis:7-alpine` or a native
-`redis-server`), run:
+`redis-server`), run (pick a free port explicitly — do not assume 3000):
 
 ```bash
 REDIS_URL=redis://127.0.0.1:6379 DEPLOYMENT_VERSION=setup-verify npm run build
-REDIS_URL=redis://127.0.0.1:6379 DEPLOYMENT_VERSION=setup-verify npm run start &
+REDIS_URL=redis://127.0.0.1:6379 DEPLOYMENT_VERSION=setup-verify npm run start -- -p 3777 &
+# wait for readiness before curling:
+for i in $(seq 1 30); do curl -sf http://127.0.0.1:3777/ >/dev/null && break; sleep 1; done
 ```
 
-Then request any ISR/static page twice and check the `x-nextjs-cache`
-header: first `MISS`, second `HIT`. Confirm keys exist:
-`redis-cli KEYS 'next-incremental:*'`. Kill the server afterwards.
+Check the `x-nextjs-cache` header on an ISR/static page. **Two valid
+outcomes**: build-time-prerendered pages are often served as `HIT` from the
+very first request; on-demand pages show `MISS` then `HIT`. Either way,
+confirm keys exist with `redis-cli --scan --pattern 'next-incremental:*'`
+(never use `KEYS` — it blocks Redis).
+
+The strongest proof is a full round-trip: delete the page's entry key with
+the server running, then request twice — expect `MISS` then `HIT` and the
+key to REAPPEAR in Redis (proves both read and write paths). Kill the
+server afterwards and verify the port is free.
 
 **Error handling:**
 

package/skills/nextjs-redis-cache/SKILL.md

@@ -109,12 +109,27 @@ Facts that prevent misdiagnosis:
 | `abortTimeoutMs` | 1500 | Per-op Redis deadline; timeouts degrade to miss |
 | `hashTag: true` | off | REQUIRED on Redis Cluster |
 | `onMetric` | — | Wire `createOtelMetricEmitter()` from `@leejpsd/nextjs-cache-handler/otel` |
+| `tagPubSub: true` | off | 0.4+: push-based cross-instance invalidation (~3ms vs seconds); polling stays as safety net; not on Cluster |
 
 Reliability built in (0.3+): reconnect with exponential backoff (1s→30s cap),
 bounded memory fallback, per-op timeouts. A Redis outage degrades to
 in-memory serving; reconnection is automatic (validated with a live
 ElastiCache reboot drill: 2550 requests, zero 5xx).
 
+### 0.4+ deployment accelerators
+
+- **Seed the cache at deploy time** so a fresh deployment's first requests
+  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).
+- **`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.
+- **MCP server** for cache operations from your agent:
+  `@leejpsd/nextjs-cache-handler-mcp` (cache_health, tag_state,
+  invalidate_tag dry-run, …).
+
 ## 6. Production checklist
 
 - [ ] `DEPLOYMENT_VERSION` injected at runtime (runner stage in Docker)