TanStack Start Todos

A modern frontend application built with TanStack Start, demonstrating server-side rendering, infinite scroll pagination, and modern React patterns.

Tech Stack

• Framework: TanStack Start (React 19, SSR)
• Routing: TanStack Router (file-based)
• Data Fetching: TanStack Query v5
• Validation: Zod v4
• Styling: Tailwind CSS v4
• Components: Radix UI primitives
• Icons: Lucide React
• Date Handling: Day.js
• Build: Vite 7
• Testing: Vitest + Testing Library

Prerequisites

• Node.js 20+
• Yarn

Getting Started

# Install dependencies
yarn install

# Start development server
yarn dev

The app will be available at http://localhost:3000.

Scripts

Development

Command	Description
yarn dev	Start development server on port 3000
yarn build	Build for production
yarn serve	Preview production build

Testing

Command	Description
yarn test	Run tests once
yarn test:watch	Run tests in watch mode
yarn test:coverage	Run tests with coverage report

Code Quality

Command	Description
yarn lint	Check for linting errors
yarn lint:fix	Fix linting errors
yarn format	Check code formatting
yarn format:fix	Fix code formatting
yarn scan	Run format, lint, and type check

Directory Structure

src/
├── config/               # App-wide configuration (constants, routes, query keys, validation)
├── utils/                # App-wide utility functions (dayjs date utilities, head generation, helpers)
├── hooks/                # App-wide custom React hooks (shared across features)
├── components/
│   ├── atoms/            # Reusable UI primitives (Button, Table, etc.)
│   └── layout/           # Layout components (Header, NotFound)
├── i18n/                 # Internationalization (i18next config, translations)
├── theme/                # Theme provider and utilities
├── screens/              # Feature modules
│   └── [feature]/
│       ├── api/          # Feature-specific server functions
│       ├── components/   # Feature-specific components
│       ├── hooks/        # Feature-specific hooks
│       ├── utils/        # Feature-specific utilities
│       └── types/        # Feature-specific types
└── routes/               # TanStack Router file-based routes

Global vs Feature-Specific Organization

Location	Purpose	Example
src/config/	App-wide configuration, constants	constants.ts, routes.ts
src/utils/	App-wide utility functions	helpers.ts, date.ts
src/hooks/	App-wide custom hooks (shared across features)	useLocalStorage.ts, useMediaQuery.ts
src/screens/[feature]/	Feature-scoped code (api, components, hooks)	todos/hooks/useCreateTodoMutation.ts

Rule: If it's used by multiple features → global folder (config/, utils/, hooks/). If it's feature-specific → feature folder (screens/[feature]/).

Code Quality

Linting & Formatting

# Check and fix all issues
yarn scan

# Or run individually
yarn lint:fix
yarn format:fix

Commit Convention

This project uses Conventional Commits. Commits are validated with commitlint.

# Examples
git commit -m "feat: add user authentication"
git commit -m "fix: resolve routing issue"
git commit -m "refactor: extract validation logic"

Testing

Running Tests

# Run tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage report
yarn test:coverage

Coverage Reports

After running yarn test:coverage, reports are generated in the ./coverage directory:

Report	Location	Description
HTML	coverage/index.html	Interactive browser-based report
Text	Terminal output	Quick summary in console
JSON	coverage/coverage-final.json	Machine-readable coverage data
Cobertura	coverage/cobertura-coverage.xml	CI/CD integration (GitLab, etc.)

Coverage Thresholds

Metric	Threshold
Lines	50%
Functions	50%
Branches	40%
Statements	50%

Tests will fail if coverage drops below these thresholds.

Environment File Hierarchy

Files are loaded in this order (later files override earlier):

.env.local          # Local overrides (add to .gitignore)
.env.production     # Production-specific variables
.env.development    # Development-specific variables
.env                # Default variables (commit to git)

Mental Model

Server Functions (Node.js)          Client Components (Browser)
├── process.env.*                   ├── import.meta.env.VITE_*
├── Full access to all vars         ├── Only VITE_ prefixed vars
├── Secrets are safe here           ├── Everything is public here
└── Database, API keys, etc.        └── URLs, flags, public config

The boundary is enforced by the bundler - server-only code is stripped from client bundles automatically by TanStack Start/Vite.