README.md

Project Overview

This is a TanStack Start React application written in TypeScript, featuring:

• TanStack Start full-stack framework
• TanStack Router with SSR and file-based routing
• TypeScript path aliases via vite-tsconfig-paths (use @/ for src/)
• Tailwind CSS v4 for utility-first styling
• ESLint for linting and Prettier for formatting
• Vitest + React Testing Library for tests

Development Commands

Core Development

pnpm dev           # Start dev server on port 3000 (Vite HMR)
pnpm build         # Production build (SSR + client bundles)
pnpm serve         # Preview the production build locally

Code Quality

pnpm lint          # ESLint
pnpm format        # Prettier format
pnpm check         # ESLint + Prettier

Testing Commands

pnpm test                 # Run Vitest suite
pnpm test -- --watch      # TDD watch mode
pnpm test -- --coverage   # Coverage for PRs touching core flows

Update Dependencies

`pnpm up -L `              # Update dependencies and update pnpm-lock.yaml

Component Management

• Use @/components/... for imports
• Use lucide-react for icons: import { Icon } from 'lucide-react'

Setup

pnpm install       # Install dependencies

Architecture

Routing System

• File-based routes live in src/routes/ using lowercase, dot-delimited filenames (e.g., about.index.tsx).
• Export PascalCase components from route files.
• Root shell: src/routes/__root.tsx defines the HTML document via shellComponent and <HeadContent />.
• The route tree in src/routeTree.gen.ts is generated by the TanStack router plugin; do not edit manually.
• Router configuration is in src/router.tsx.

Data Fetching Modes

1. Route loaders for SSR data (Route.loader / .useLoaderData() in components).
2. API endpoints via Route.server.handlers (GET/POST) that act as REST routes.
3. Server functions via createServerFn() for RPC-style operations with access to Node APIs.
   • You may import Node modules (e.g., node:fs) in server contexts; Start will tree-shake for the client.
   • TanStack Query can be added for client-side caching if needed.

Styling Architecture

• Tailwind CSS v4 via the Vite plugin; global styles in src/styles.css.
• src/lib/utils.ts provides cn() for class merging (clsx + tailwind-merge).
• Prefer class-variance-authority for component variants over manual class concatenation.
• Shadcn components are added to src/components/ui/ via the CLI.

Project Structure

project/
├── public/              # Static assets
│   ├── manifest.json    # PWA manifest
│   └── robots.txt       # Search engine directives
├── src/
│   ├── components/      # Reusable React components
│   ├── lib/             # Shared utilities
│   ├── routes/          # File-based route modules
│   │   ├── __root.tsx   # Root shell component
│   │   ├── index.tsx    # Home page
│   ├── router.tsx       # Router configuration
│   ├── routeTree.gen.ts # Auto-generated; do NOT edit
│   └── styles.css       # Global styles (Tailwind directives)
├── README.md            # Project readme
├── eslint.config.js     # ESLint configuration
├── prettier.config.js   # Prettier configuration

├── package.json         # Dependencies and scripts
├── pnpm-lock.yaml       # Lockfile for pnpm
├── tsconfig.json        # TypeScript configuration
└── vite.config.ts       # Vite bundler configuration

File & Naming Conventions

• Route filenames: lowercase with dots for path segments (e.g marketing.pricing.tsx → /marketing/pricing).
• Optional suffixes clarify modes: .api-request.tsx, .server-funcs.tsx, .full-ssr.tsx.
• Components export functions named after their file, in PascalCase.
• Co-locate component-specific hooks; keep shared utilities in src/lib.
• Use @/ alias for imports from src/.

Testing

• Framework: Vitest + React Testing Library.
• File naming: *.test.tsx or *.test.ts, co-located or under src/__tests__/.
• Mocking: Use vi.mock() for modules; avoid mutating globals.
• Accessibility: Include a11y assertions where relevant.
• Coverage: Run pnpm test -- --coverage for PRs that touch core flows.
• Note: If no tests exist yet, create them following the above conventions.

Linting & Formatting

• ESLint for linting and Prettier for code formatting.
• Configuration in eslint.config.js and prettier.config.js.
• pnpm check runs lint + format together.
• src/routeTree.gen.ts is excluded from linting checks.

Critical Patterns

1. Server-side file I/O and other Node APIs are valid inside server contexts (API handlers, server functions, or loaders that execute on the server).
2. Access loader data with Route.useLoaderData() inside components for type-safe SSR data.
3. Devtools: __root.tsx wires TanStack Devtools and Router DevTools in development.
4. Place static assets in public/ and reference via root-relative URLs.

Adding New Routes

1. Create src/routes/path.to.route.tsx using dot notation.
2. Export Route via createFileRoute('/path/to/route').
3. Provide a component and optionally a loader (SSR), server.handlers (API), or server functions.
4. routeTree.gen.ts is automatically generated on save. Do not edit it manually.
5. Document complex routes or novel patterns in docs/.

Commit & PR Guidelines

• Use Conventional Commits (e.g., feat:, fix:, chore:, build:, docs:) with optional scope.
• Each PR should describe the change, reference issues, and call out config/dependency updates.
• Include screenshots or GIFs for UI-facing work and summarize test runs (e.g., pnpm test).
• Label UX-visible changes and document new routes in docs/ when applicable.

Configuration Notes

• Vite + TanStack Start power the environment; vite.config.ts enables vite-tsconfig-paths and Tailwind via the Vite plugin.
• Tailwind config files can be added/generated if needed; defaults work via the Vite plugin.
• Update eslint.config.js for project-wide lint adjustments as necessary.

Development Helpers

• Tanstack DevTools: Visible in development for inspecting state.
• Router DevTools: Integrated as plugin.

Development Notes

• Prefer pnpm for all scripts and package management.
• The app supports SSR and SPA usage; pick data-fetching modes accordingly.