React Frontend Development

Vite + React 19 + TypeScript + TanStack Query + Zustand + shadcn/ui

Quick Reference

Critical Rules

ALWAYS

• •TypeScript strict mode (no any, no @ts-ignore)
• •Prefer bun package manager, fallback to pnpm (NEVER npm)
• •Use Biome for linting AND formatting
• •TanStack Query for ALL server data
• •Zustand for UI-only state
• •lucide-animated icons when available

NEVER

• •Suppress type errors (as any, @ts-ignore, @ts-expect-error)
• •Use npm as package manager
• •Mix server state in Zustand
• •Custom animations outside shared presets
• •Paste secrets or production data in code

ASK FIRST

• •Auth implementation (WorkOS vs better-auth)
• •Major refactors affecting 3+ files
• •Changing core dependencies (icons, auth, state management)
• •Non-obvious architectural decisions

State Management Decision Tree

Is it from an API/server?
├─ YES → TanStack Query (useQuery, useMutation)
└─ NO → Is it UI-related?
         ├─ YES → Zustand (dialogs, selections, filters)
         └─ NO → Consider if state is needed at all

Commands

# Setup (use bun, fallback pnpm)
bun install        # or: pnpm install

# Development
bun run dev        # or: pnpm dev

# Build
bun run build      # or: pnpm build

# Lint & Format
bun run check      # biome check
bun run format     # biome format --write

Detailed References

Quality Gates (Pre-commit)

Required before any commit:

1. •biome check - Lint + format validation
2. •tsc --noEmit - TypeScript type checking

Husky + lint-staged enforces these automatically.