|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +TanStack.com is the official website and documentation hub for all TanStack open-source libraries (React Query, React Table, React Router, React Form, etc.). Built with TanStack Router/Start as a full-stack React application. |
| 8 | + |
| 9 | +## Essential Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Development |
| 13 | +pnpm dev # Run frontend (Vite) + backend (Convex) in parallel |
| 14 | +pnpm dev:frontend # Frontend only (Vite dev server) |
| 15 | +pnpm dev:backend # Backend only (Convex) |
| 16 | + |
| 17 | +# Build & Deploy |
| 18 | +pnpm build # Production build |
| 19 | +pnpm start # Production start |
| 20 | + |
| 21 | +# Code Quality |
| 22 | +pnpm lint # Run Prettier + ESLint checks |
| 23 | +pnpm format # Auto-format with Prettier |
| 24 | + |
| 25 | +# Local Package Development |
| 26 | +pnpm linkAll # Link local TanStack packages (requires sibling repos) |
| 27 | +``` |
| 28 | + |
| 29 | +## Architecture Overview |
| 30 | + |
| 31 | +### Tech Stack |
| 32 | +- **Framework**: TanStack Router + TanStack Start (file-system based routing) |
| 33 | +- **Styling**: Tailwind CSS with custom design tokens |
| 34 | +- **Backend**: Convex (real-time backend service) |
| 35 | +- **Auth**: Clerk |
| 36 | +- **Content**: Content Collections + Markdown for docs/blog |
| 37 | +- **Build**: Vite |
| 38 | + |
| 39 | +### Key Directory Structure |
| 40 | +- `src/routes/` - File-system based routing (TanStack Router) |
| 41 | +- `src/components/` - Shared React components |
| 42 | +- `src/libraries/` - Library configurations and metadata |
| 43 | +- `src/blog/` - Blog posts in Markdown |
| 44 | +- `convex/` - Backend functions (Convex) |
| 45 | +- `scripts/` - Build and development scripts |
| 46 | + |
| 47 | +### Routing System |
| 48 | +Uses TanStack Router's file-system routing. Key patterns: |
| 49 | +- `src/routes/__root.tsx` - Root layout |
| 50 | +- `src/routes/[framework]/[library]/*.tsx` - Dynamic library docs |
| 51 | +- Route files export `createFileRoute()` for route configuration |
| 52 | +- Layouts use `_layout.tsx` convention |
| 53 | + |
| 54 | +### Content System |
| 55 | +Documentation is fetched from GitHub in production or read locally in development: |
| 56 | +- Library docs pulled from respective GitHub repos |
| 57 | +- Blog posts stored locally in `src/blog/` |
| 58 | +- Content processed via Content Collections |
| 59 | +- Supports multiple framework variations (React, Vue, Angular, Solid) |
| 60 | + |
| 61 | +### State Management |
| 62 | +- **TanStack Query**: Server state and data fetching |
| 63 | +- **Zustand**: Client state (`src/stores/`) |
| 64 | +- **React Context**: Theme and auth providers |
| 65 | + |
| 66 | +### Backend (Convex) |
| 67 | +- Functions in `convex/` directory |
| 68 | +- Real-time subscriptions and mutations |
| 69 | +- Handles user data, sponsors, authentication |
| 70 | + |
| 71 | +## Development Setup Requirements |
| 72 | + |
| 73 | +1. **Environment Variables**: Create `.env` file with: |
| 74 | + - Clerk tokens (auth) |
| 75 | + - Convex deployment URL |
| 76 | + - Sentry DSN (optional) |
| 77 | + |
| 78 | +2. **Local Package Development**: |
| 79 | + - Parent directory must be named `tanstack/` |
| 80 | + - Sibling repos required for local docs: `tanstack/query`, `tanstack/router`, etc. |
| 81 | + - Run `pnpm linkAll` to link local packages |
| 82 | + |
| 83 | +3. **Port Configuration**: Dev server runs on port 3000 |
| 84 | + |
| 85 | +## Important Patterns |
| 86 | + |
| 87 | +### Component Creation |
| 88 | +- Use TypeScript with explicit types |
| 89 | +- Follow existing component patterns in `src/components/` |
| 90 | +- Tailwind classes for styling (avoid inline styles) |
| 91 | + |
| 92 | +### Route Creation |
| 93 | +```tsx |
| 94 | +import { createFileRoute } from '@tanstack/react-router' |
| 95 | + |
| 96 | +export const Route = createFileRoute('/path')({ |
| 97 | + component: RouteComponent, |
| 98 | +}) |
| 99 | + |
| 100 | +function RouteComponent() { |
| 101 | + // Component implementation |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +### API/Backend Calls |
| 106 | +Use Convex hooks: |
| 107 | +```tsx |
| 108 | +import { useQuery, useMutation } from 'convex/react' |
| 109 | +import { api } from '~/convex/_generated/api' |
| 110 | + |
| 111 | +const data = useQuery(api.functions.myFunction) |
| 112 | +const mutate = useMutation(api.functions.myMutation) |
| 113 | +``` |
| 114 | + |
| 115 | +### Content/Documentation Updates |
| 116 | +- Blog posts: Add Markdown files to `src/blog/` |
| 117 | +- Library metadata: Update `src/libraries/[library].tsx` |
| 118 | +- Documentation pulled from respective library repos (not edited here) |
0 commit comments