core-principles

name	core-principles
description	Use when planning new projects, onboarding, or reviewing architectural decisions. Core principles and project structure for React 19 SPA development. Covers stack overview, project organization, agent execution rules, and authoritative sources.
updated	"2026-01-20T00:00:00.000Z"
keywords	react-19, spa, project-structure, architecture, vite, typescript, tanstack, biome

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