Skip to content
Source
Sign inSign up
TanStack/cli
Open History to see the last commit

CLAUDE.md

211 lines5.8 KB

1# TanStack Application Builders (CTA) - Claude Code Assistant
2​
3## Project Overview
4​
5This monorepo contains the TanStack Application Builders (CTA - Create TanStack Application), a comprehensive tool for creating modern React and Solid applications with TanStack Router and TanStack Start.
6​
7## Quick Start
8​
9```bash
10# Create a new TanStack Router app
11npx create-tsrouter-app@latest my-app
12​
13# Create a new TanStack Start app (SSR)
14npx create-start-app@latest my-app
15​
16# Alternative CLI names (all create TanStack Router apps)
17npx create-tanstack@latest my-app
18npx create-tanstack-app@latest my-app
19```
20​
21## Monorepo Structure
22​
23```
24create-tsrouter-app/
25├── cli/ # CLI applications
26│ ├── create-start-app/ # TanStack Start CLI
27│ ├── create-tanstack/ # TanStack Router CLI (alias)
28│ ├── create-tanstack-app/ # TanStack Router CLI (alias)
29│ └── create-tsrouter-app/ # TanStack Router CLI (main)
30├── packages/ # Core packages
31│ ├── cta-cli/ # CLI interface
32│ ├── cta-engine/ # Core engine
33│ ├── cta-ui/ # Web UI components
34│ └── cta-ui-base/ # Base UI components
35├── frameworks/ # Framework implementations
36│ ├── react-cra/ # React CRA framework
37│ └── solid/ # Solid framework
38└── examples/ # Example projects and starters
39```
40​
41## Core Packages
42​
43### @tanstack/cta-cli
44​
45- **Purpose**: Main CLI interface for the application builder
46- **Key Dependencies**: `@clack/prompts`, `commander`, `express`, `chalk`
47- **Scripts**: `build`, `dev`, `test`, `test:watch`, `test:coverage`
48​
49### @tanstack/cta-engine
50​
51- **Purpose**: Core business logic and file generation engine
52- **Key Dependencies**: `ejs`, `execa`, `memfs`, `prettier`, `zod`
53- **Features**: Template processing, project generation, validation
54​
55### @tanstack/cta-ui
56​
57- **Purpose**: Web interface for the application builder
58- **Key Dependencies**: `react`, `tailwindcss`, `next-themes`, `sonner`
59- **Scripts**: `build:ui`, `dev:ui` (React dev server)
60​
61## CLI Applications
62​
63### create-start-app
64​
65- **Purpose**: Creates TanStack Start applications (SSR)
66- **Features**: Server-side rendering, React/Solid support, Vite build system
67- **Usage**: `npx create-start-app@latest my-app`
68​
69### create-tsrouter-app (and aliases)
70​
71- **Purpose**: Creates TanStack Router applications (client-side routing)
72- **Features**: File-based routing, TypeScript/JavaScript, React/Solid support
73- **Usage**: `npx create-tsrouter-app@latest my-app`
74​
75## Framework Support
76​
77### React CRA Framework
78​
79- **Location**: `frameworks/react-cra/`
80- **Add-ons**: Clerk, Shadcn, Neon, TanStack Query, tRPC, Form, Store, etc.
81- **Toolchains**: Biome, ESLint + Prettier
82- **Examples**: Blog starter, E-commerce starter, TanChat
83​
84### Solid Framework
85​
86- **Location**: `frameworks/solid/`
87- **Add-ons**: Solid UI, TanStack Query, Form, Store, etc.
88- **Toolchains**: Biome, ESLint + Prettier
89- **Examples**: TanChat
90​
91## Development Scripts
92​
93```bash
94# Install dependencies
95pnpm install
96​
97# Build all packages
98pnpm build
99​
100# Start development mode (watch all packages)
101pnpm dev
102​
103# Run tests
104pnpm test
105​
106# Clean node_modules
107pnpm cleanNodeModules
108```
109​
110## Key Development Commands
111​
112### Building Example Apps
113​
114```bash
115# Build with CLI (outside monorepo)
116node cli/create-tsrouter-app/dist/index.js my-app
117​
118# Test with local add-ons
119node cli/create-tsrouter-app/dist/index.js my-app --add-ons http://localhost:9080/add-on.json
120​
121# Test with local starters
122node cli/create-tsrouter-app/dist/index.js my-app --starter http://localhost:9080/starter.json
123```
124​
125### Developing CTA UI
126​
127```bash
128# Start API server
129CTA_DISABLE_UI=true node cli/create-tsrouter-app/dist/index.js --ui
130​
131# Start React dev server
132cd packages/cta-ui && pnpm dev:ui
133​
134# Run monorepo in watch mode
135pnpm dev
136```
137​
138## Add-ons and Starters
139​
140### Popular Add-ons
141​
142- **Clerk**: Authentication integration
143- **Shadcn**: UI component library
144- **Neon**: PostgreSQL database integration
145- **TanStack Query**: Data fetching
146- **tRPC**: Type-safe APIs
147- **Form**: Form handling
148- **Store**: State management
149​
150### Example Starters
151​
152- **Blog Starter**: TanStack Router blog with file-based routing
153- **E-commerce Starter**: AI-powered chat application
154- **Resume Starter**: Professional resume template
155- **TanChat**: AI chat application with Claude integration
156​
157## EJS Template Variables
158​
159The system uses EJS templates with these variables:
160​
161- `packageManager`: npm, yarn, pnpm, bun, deno
162- `projectName`: Project name
163- `typescript`: TypeScript enabled
164- `tailwind`: Tailwind CSS enabled
165- `fileRouter`: File-based routing
166- `codeRouter`: Code-based routing
167- `addOnEnabled`: Enabled add-ons object
168- `addOns`: Array of enabled add-ons
169- `routes`: Array of routes from add-ons
170​
171## Testing
172​
173```bash
174# Run all tests
175pnpm test
176​
177# Test specific framework
178cd frameworks/react-cra && pnpm test
179​
180# Test with coverage
181pnpm test:coverage
182```
183​
184## Contributing
185​
1861. Clone: `gh repo clone TanStack/create-tsrouter-app`
1872. Install: `pnpm install`
1883. Build: `pnpm build`
1894. Develop: `pnpm dev`
1905. Test: `pnpm test`
191​
192## Architecture Notes
193​
194- **Monorepo**: Uses pnpm workspaces and Nx for task orchestration
195- **Package Manager**: Requires pnpm@9.15.5
196- **Node Version**: Requires Node.js (see .nvmrc if available)
197- **Build System**: TypeScript compilation, Vite for UI
198- **Testing**: Vitest for unit tests, ESLint for linting
199- **Versioning**: All packages share the same version (currently 0.16.5)
200​
201## Important Files
202​
203- `package.json`: Root package configuration and workspace setup
204- `pnpm-workspace.yaml`: Workspace configuration
205- `nx.json`: Nx configuration for task orchestration
206- `ARCHITECTURE.md`: Detailed architecture documentation
207- `CONTRIBUTING.md`: Contribution guidelines
208​
209## License
210​
211MIT Licensed - see LICENSE file for details