Repository navigation
docs: sweep the docs and add a start-here for people and agents - #102
Merged
Merged
Conversation
- README: a Start here (pinned install, withCache, pick-your-setup table); depth moved into docs/. Package README regenerated. - Client snippets: one createClient() + globalThis pattern everywhere; the Sentinel/Cluster snippets no longer use an undefined key; the IAM Cluster example no longer attaches auth outside the guard. - IAM: rewritten around a decision table (environment / iam option / own client), with each claim checked against the source. - Deprecated APIs marked as removed in 16.5 where docs still presented them as current; broken anchors fixed; dense prose split. - New docs/agent-setup.md (copy-paste setup prompt for coding agents) and docs/llms.txt (doc index). No runtime code or API changes; two JSDoc examples updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- redis.md: the shared-iam example now shows the page, remote and local factories in their own files (one factory in all three broke the page handler and put plain "use cache" in Redis). - agent-setup: pick the backing store by asking cluster, then IAM, then plain URL, so a rediss:// URL with IAM or a cluster endpoint is not taken as "nothing to add". - agent-setup: run Next through the package manager, and check the debug log instead of a localhost redis-cli scan. - api-reference: document withCache's useCache option (#106). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mrjasonroy
force-pushed
the
docs/sweep
branch
from
November 3, 2026 17:38
5ff1467 to
869860e
Compare
A route handler that reads no request data is prerendered, so a health or metrics route answers from the build output (x-nextjs-cache: HIT, s-maxage=31536000) and never runs. Found in a production rollout review. - operations.md: a Health checks section: the frozen route, the fix (await connection() plus no-store), how to verify it, and why Redis stays out of liveness and readiness. - agent-setup: the agent looks for such routes and reports them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A pass over every user-facing doc against the source, plus a start-here for people and for coding agents. No runtime code or API changes. The only source edits are two JSDoc `@example` blocks.
Start here
Fixes
Client snippets use one pattern everywhere: a named `createClient()` with `export const client = (globalThis.myAppRedis ??= createClient());` (replaces `Symbol.for` plus an immediately invoked function). The Sentinel and Cluster snippets no longer reference an undefined `key`. The IAM Cluster example no longer attaches auth outside the guard, which would have attached it twice.
IAM is rewritten around a decision table: environment only, the `iam` option, or your own client with `attachElastiCacheIamAuth`. Each claim (refresh timing, env vars, fallbacks, what throws) is checked against `shared/env.ts`, `shared/elasticache-iam.ts` and `helpers/elasticache-iam.ts`.
APIs deprecated in 16.4.3 (e.g. the page handler's `redis` option) are now marked as removed in 16.5 instead of being presented as current.
`custom-handlers.md`: "also provide `default`" corrected to "replace all three". A handler you leave out runs without Redis.
`installation.md` verify step: a prerendered page's first read logs `build output`, not `hit`.
Broken anchors fixed (`#quick-start`, the README `withCache` link). Dense paragraphs are split into lists.
Health checks (
operations.md): withcacheComponents, a health or metrics route handler that reads no request data is prerendered and answers from the build output (x-nextjs-cache: HIT,s-maxage=31536000) without running. The section covers the fix (await connection()plusno-store), how to verify it, and why Redis stays out of liveness and readiness. The agent prompt now looks for such routes.Known, not fixed (needs code): a client you build yourself is created and connected when Next loads the handler file during `next build`. The handlers ignore it, but it still connects.
Checks: `pnpm lint` (including the README sync check), `pnpm format`, the package typecheck, and an internal link/anchor check all pass.
🤖 Generated with Claude Code