React/TypeScript Coding Standards

Personal React/TypeScript development standards and AI skills, extracted from a production Next.js dashboard template.

Structure

PHILOSOPHY.md          Core beliefs — every other doc inherits from this

skills/                Claude Code skills (deploy to ~/.claude/skills/)
  writing-react-ts-code/       Core TS/React: typing, errors, components, style, security
  setting-up-nextjs-projects/  New project bootstrap and configuration
  testing-react-ts/            Vitest, Playwright, test infrastructure
  managing-state/              Zustand, Context, URL state, form state
  building-api-clients/        HTTP client, Zod validation, Orval codegen
  building-ui-components/      shadcn/ui, component patterns, variants

How to Use

For AI agents

Deploy skills from skills/ to ~/.claude/skills/. The top-level writing-react-ts-code skill covers core standards; other skills cover specific domains.

Starting a new project

1. Read PHILOSOPHY.md for the mindset
2. Use the setting-up-nextjs-projects skill for project bootstrap
3. Copy PHILOSOPHY.md into docs/ (referenced by AGENTS.md)

Quick reference

• What tools? pnpm, TypeScript strict, ESLint (typescript-eslint strict), Prettier, Vitest, Playwright
• Error handling? Result<T, E> pattern. Exceptions = bugs only.
• Data validation? Zod for all external data (APIs, forms, env vars). Validates at runtime.
• State? Zustand for business logic. React Hook Form + Zod for forms. nuqs for URL state.
• UI? shadcn/ui (Radix + Tailwind + CVA)
• API? Typed fetch client + Zod validation. Orval for Swagger codegen.
• Tests? E2e > component. Real > mocked. Trustworthiness > coverage.