core-principles

# Core Principles for React 19 SPA Development

Production-ready best practices for building modern React applications with TypeScript, Vite, and TanStack ecosystem.

## Stack Overview

- **React 19** with React Compiler (auto-memoization)
- **TypeScript** (strict mode)
- **Vite** (bundler)
- **Biome** (formatting + linting)
- **TanStack Query** (server state)
- **TanStack Router** (file-based routing)
- **Vitest** (testing with jsdom)
- **Apidog MCP** (API spec source of truth)

## Project Structure

```
/src
  /app/               # App shell, providers, global styles
  /routes/            # TanStack Router file-based routes
  /components/        # Reusable, pure UI components (no data-fetch)
  /features/          # Feature folders (UI + hooks local to a feature)
  /api/               # Generated API types & client (from OpenAPI)
  /lib/               # Utilities (zod schemas, date, formatting, etc.)
  /test/              # Test utilities
```

**Key Principles:**
- One responsibility per file
- UI components don't fetch server data
- Put queries/mutations in feature hooks
- Co-locate tests next to files

## Agent Execution Rules

**Always do this when you add or modify code:**

1. **API Spec:** Fetch latest via Apidog MCP and regenerate `/src/api` types if changed

2. **Data Access:** Wire only through feature hooks that wrap TanStack Query. Never fetch inside UI components.

3. **New Routes:**
   - Create file under `/src/routes/**` (file-based routing)
   - If needs data at navigation, add loader that prefetches with Query

4. **Server Mutations:**
   - Use React 19 Actions OR TanStack Query `useMutation` (choose one per feature)
   - Use optimistic UI via `useOptimistic` (Actions) or Query's optimistic updates
   - Invalidate/selectively update cache on success

5. **Compiler-Friendly:**
   - Keep code pure (pure components, minimal effects)
   - If compiler flags something, fix it or add `"use no memo"` temporarily

6. **Tests:**
   - Add Vitest tests for new logic
   - Component tests use RTL
   - Stub network with msw

7. **Before Committing:**
   - Run `biome check --write`
   - Ensure Vite build passes

## "Done" Checklist per PR

- [ ] Route file added/updated; loader prefetch (if needed) present
- [ ] Query keys are stable (`as const`), `staleTime`/`gcTime` tuned
- [ ] Component remains pure; no unnecessary effects; compiler ✨ visible
- [ ] API calls typed from `/src/api`; inputs/outputs validated at boundaries
- [ ] Tests cover new logic; Vitest jsdom setup passes
- [ ] `biome check --write` clean; Vite build ok

## Authoritative Sources

- **React 19 & Compiler:**
  - React v19 overview
  - React Compiler: overview + installation + verification
  - `<form action>` / Actions API; `useOptimistic`; `use`
  - CRA deprecation & guidance

- **Vite:**
  - Getting started; env & modes; TypeScript targets

- **TypeScript:**
  - `moduleResolution: "bundler"` (for bundlers like Vite)

- **Biome:**
  - Formatter/Linter configuration & CLI usage

- **TanStack Query:**
  - Caching & important defaults; v5 migration notes; devtools/persisting cache

- **TanStack Router:**
  - Install with Vite plugin; file-based routing; search params; devtools

- **Vitest:**
  - Getting started & config (jsdom)

- **Apidog + MCP:**
  - Apidog docs (import/export, OpenAPI); MCP server usage

## Final Notes

- Favor compile-friendly React patterns
- Let the compiler and Query/Router handle perf and data orchestration
- Treat Apidog's OpenAPI (via MCP) as the single source of truth for network shapes
- Keep this doc as your "contract"—don't add heavy frameworks or configs beyond what's here unless explicitly requested

## Related Skills

- **tooling-setup** - Vite, TypeScript, Biome configuration
- **react-patterns** - React 19 specific patterns (compiler, actions, forms)
- **tanstack-router** - Routing patterns
- **tanstack-query** - Server state management with Query v5
- **router-query-integration** - Integrating Router with Query
- **api-integration** - Apidog + MCP patterns
- **performance-security** - Performance, accessibility, security