Skip to content

napkin.md

Latest commit

 

History

History
45 lines (40 loc) · 4.49 KB

napkin.md

File metadata and controls

45 lines (40 loc) · 4.49 KB

Napkin

Corrections

Date Source What Went Wrong What To Do Instead
2026-02-11 self Ran ls before reading napkin (again) Always read .claude/napkin.md before any other command
2026-02-10 self Ran ls before reading napkin Always read .claude/napkin.md before any other command
2026-02-10 self Used backticks in a shell-quoted PR body so the shell tried to execute turbo Use a heredoc or escape backticks when passing PR bodies to shell commands
2026-02-13 self Assumed mobile perf issue was mostly JS parse cost before checking runtime endpoints Verify browser-facing service URLs (NEXT_PUBLIC_*) first; loopback hosts break phone/LAN query paths
2026-02-13 self Broke a TS function signature during a broad apply_patch edit Re-open edited file immediately after structural patches before running full checks
2026-02-13 self Ran sed on a bracketed path without quoting ([id]) and zsh globbed it Quote paths containing [] (e.g., 'apps/web/app/challenges/[id]/dashboard/page.tsx')

User Preferences

  • Hide navbar on full-screen flow pages (invite, dashboard, admin) via ConditionalHeader patterns + remove page-with-header class
  • Avoid LAN-specific runtime rewrites in product code unless explicitly requested

Patterns That Work

  • Convex queries can join related data inline (e.g., activity types + categories in one query)
  • conditional-header.tsx DASHBOARD_LAYOUT_PATTERNS array controls navbar visibility per route
  • Admin console sidebar approach was scrapped — revisit admin nav design in the future
  • Mobile feed performance improves by skipping non-critical per-item work (engagement count scans and media URL generation) on initial query
  • For mobile perceived performance, SSR the first feed page from server auth and then let client usePaginatedQuery take over for realtime/pagination

Patterns That Don't Work

  • Deriving env vars inside convex deploy --cmd shell strings — escaping hell, fragile, hard to debug. Instead, derive them in next.config.ts which runs at build time and can set process.env before Next.js compiles.

Domain Notes

  • Scoring configs have types: distance, duration, count, variant
  • page-with-header CSS class = pt-16 to offset fixed navbar
  • Seed data lives in packages/backend/actions/seed.ts
  • Schema changes auto-deploy locally via pnpm dev
  • Dev-only third-party scripts should be opt-in; avoid beforeInteractive for non-critical tooling (e.g., react-grab) | 2026-02-13 | self | Assumed request.json() in Convex HTTP actions returned typed JSON; TS now treats it as unknown | Add runtime type guards (or explicit schema validation) before accessing webhook payload fields |
  • Convex httpAction webhook handlers are safer with explicit type guards before deriving event keys (object_type, aspect_type) from request.json()
  • apps/web dev script runs @react-grab/cursor before next dev; this can create behavior differences vs production. Prefer validating layout bugs with next build && next start too.
  • Overflow debug scripts that add window.scrollY to fixed-position elements can produce misleading top/bottom values; filter out position: fixed when diagnosing document-flow overflow.
  • When user asks to branch with dirty worktree, preserve unrelated local modifications and scope edits to requested files only. | 2026-02-13 | self | Forgot to quote path containing parentheses ((marketing)) so zsh globbing failed | Quote paths with (), [], and other glob chars in shell commands |
  • If user asks to open a PR, commit only task-relevant files and keep unrelated dirty files unstaged. | 2026-02-13 | self | Used backticks inside a double-quoted gh pr create --body string, triggering shell command substitution and noisy side effects | Use a heredoc/file for PR body or avoid backticks in shell-quoted strings |

User Preferences

  • Always commit .claude/napkin.md with related task commits.
  • Avoid module-scope new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!) in route handlers; lazy-init inside request handlers with env guards to prevent build-time crashes.
  • Root layout auth preloads can execute during static prerender (/_not-found); guard token preload and fail open when auth env vars are absent at build time.
  • Vercel can ignore root vercel.json when project Root Directory is apps/web; keep an apps/web/vercel.json with the Convex deploy build command to avoid accidental pnpm build fallback.