Skip to main content

next-story-onboarding

A Claude Code skill for wiring a Next.js repo to install and self-host @next-story/journey-recorder. Full source: skills/next-story-onboarding/SKILL.md.

When to use it​

Triggers on tasks like installing the package, wiring middleware.ts, a collect-route 401 that only fails on a clean browser's first request, InMemoryStore in production, or adding journey-recorder to a new Next.js app.

What it covers​

The package deliberately punts identity, storage, and rate limiting to the host app — this skill walks through wiring each of those seams correctly, and flags the gotchas that only show up in production:

  • The same-request token trick — a middleware Set-Cookie is only visible to the browser on its next request, so the journey token must also be forwarded as a request header on the same request that minted it, or the collect route 401s forever on a clean browser's first hit.
  • Runtime isolation — middleware.ts must never import the module that builds the sink/store/database client, or the Edge bundle breaks.
  • A shared site registry — the same Edge-safe origin resolver must back both the mint step (middleware) and the verify step (collect route).
  • Per-request secret guards — production checks for token secrets and IP salt must be checked per-call, not at module load, or next build breaks on a machine that was never going to serve traffic.
  • Production-safe rate limiting — InMemoryStore is dev-only; multi-instance deployments need a shared store like UpstashStore.
  • Schema ownership — createDrizzleEventSink is structurally typed, so the host app implements its own tables rather than depending on this repo's private packages/db.
  • The client re-init guard — must be a module-level boolean, not a useRef, since App Router's dev mode double-invokes effects on mount.
  • Identity as a separate port — anon_id resolution is composed into the app's own single middleware(), never owned by this package.

Read the full SKILL.md for the complete, verifiable invariant list, red flags, and copy-in reference templates for each piece.