openconcho/.claude/rules/coding-standards.md

description

description
Coding conventions — read when writing or reviewing any code file

Coding Standards

DO

• Use TypeScript strict mode ("strict": true in tsconfig)
• Use Zod only at user-input boundaries (settings form) — not for internal types
• Use named constants — never magic numbers or strings
• Keep components focused; co-locate sub-components in the same file if < 80 lines
• Use type imports for framer-motion's Variants type to avoid widening issues
• Cast TanStack Router params as as never for cross-route navigation

NEVER

• Use any — use unknown and narrow explicitly
• Inline Honcho base URL — always read from loadConfig() in src/lib/config.ts
• Use Tailwind color classes for theme-sensitive values — use CSS var(--*) instead
• Use React.FormEvent (deprecated in TS6) — use React.SyntheticEvent<HTMLFormElement>
• Add as const to framer-motion variant objects — annotate with const x: Variants = {}

Test Standards

• One assertion per test case
• Test behavior, not implementation
• Run targeted: pnpm vitest run src/path/to/file.test.ts
• Never mock internal modules — mock only external API boundaries (openapi-fetch client)

API Query Patterns

• All data fetching via TanStack Query hooks in src/api/queries.ts
• POST body shapes are fixed per the openapi schema — do not guess field names
• Use client.current (getter) to always get fresh config at call time