Skip to content

docs: sweep the docs and add a start-here for people and agents - #102

Merged
mrjasonroy merged 3 commits into
mainfrom
docs/sweep
Nov 3, 2026
Merged

mrjasonroy merged 3 commits into
mainfrom
docs/sweep

Conversation

@mrjasonroy

@mrjasonroy mrjasonroy commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

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

  • README opens with: the pinned install (`npm install --save-exact …@16.4`), the two-line `withCache` config, and a pick-your-setup table (memory / Redis or Valkey / ElastiCache by cluster mode / own client / upgrading). Depth moves into `docs/`; the npm README is regenerated.
  • `docs/agent-setup.md`: one copy-paste prompt for Claude Code, Cursor and the like. It checks versions, installs the exact matching release, wraps the config, picks the backing store from the app's env, avoids the deprecated APIs (named), verifies, and reports what changed.
  • `docs/llms.txt`: a short index of the docs.

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): with cacheComponents, 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() plus no-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

mrjasonroy and others added 2 commits November 3, 2026 09:38
- 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>
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>
@mrjasonroy
mrjasonroy merged commit 9a54ae4 into main Nov 3, 2026
32 checks passed
@mrjasonroy
mrjasonroy deleted the docs/sweep branch November 3, 2026 18:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant