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

CLAUDE.md

133 lines3.6 KB

1# CLAUDE.md
2​
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4​
5## Commands
6​
7### Build Commands
8```bash
9# Build all packages (runs in parallel)
10pnpm build
11​
12# Run development mode with watch (builds everything in watch mode)
13pnpm dev
14​
15# Clean all node_modules
16pnpm cleanNodeModules
17```
18​
19### Testing
20```bash
21# Run all tests
22pnpm test
23​
24# Run specific framework tests
25cd frameworks/react-cra && pnpm test
26cd frameworks/solid && pnpm test
27​
28# Test coverage in packages
29cd packages/cta-engine && pnpm test:coverage
30```
31​
32### Development Workflow
33```bash
34# 1. Install dependencies
35pnpm install
36​
37# 2. Build everything
38pnpm build
39​
40# 3. Create a test application (from outside the monorepo)
41node [path-to-repo]/cli/create-tsrouter-app/dist/index.js my-app
42​
43# 4. Run in development mode
44pnpm dev
45```
46​
47### Publishing (CI Only)
48```bash
49pnpm cipublish
50```
51​
52## Architecture
53​
54This is a monorepo for TanStack application builders, using pnpm workspaces and Nx for orchestration.
55​
56### Key Concepts
57​
58- **CTA (Create TanStack Application)**: The core system for creating TanStack applications
59- **Frameworks**: Technology-specific implementations (React, Solid, etc.)
60- **Add-ons**: Plugins that extend application capabilities (e.g., tanstack-query, clerk, sentry)
61- **Starters**: Pre-configured application templates with modern defaults
62- **Code Router vs File Router**: Two routing modes - code-based or file-based routing
63​
64### Project Structure
65​
66- **cli/**: CLI applications (create-tsrouter-app, create-tanstack, create-start-app)
67 - Each CLI delegates to @tanstack/cta-cli for core functionality
69- **packages/**: Core packages
70 - **cta-cli**: Command line interface logic
71 - **cta-engine**: Core engine for app generation and modification
72 - **cta-ui**: Web UI for interactive app creation
73 - **cta-ui-base**: Shared UI components
75- **frameworks/**: Framework implementations
76 - **react-cra**: React framework support
77 - **solid**: Solid framework support
78 - Each contains add-ons, toolchains, and project templates
79​
80### Template System
81​
82Uses EJS templating with these key variables:
83- `typescript`, `tailwind`: Boolean flags
84- `js`, `jsx`: File extensions based on TypeScript setting
85- `fileRouter`, `codeRouter`: Routing mode flags
86- `addOnEnabled`: Object of enabled add-ons
87- `packageManager`: npm, yarn, or pnpm
88​
89### Add-on System
90​
91Add-ons modify the generated application by:
921. Adding dependencies via package.json
932. Copying asset files
943. Providing demo routes
954. Integrating with the build system
96​
97Custom add-ons can be created as JSON files and loaded via URL.
98​
99### Testing Add-ons and Starters
100​
101```bash
102# Serve add-on/starter locally
103npx static-server
104​
105# Test add-on
106node [repo]/cli/create-tsrouter-app/dist/index.js app-test --add-ons http://localhost:9080/add-on.json
107​
108# Test starter
109node [repo]/cli/create-tsrouter-app/dist/index.js app-test --starter http://localhost:9080/starter.json
110```
111​
112### UI Development
113​
114The UI runs as both a web server and React app:
115​
116```bash
117# 1. Start API server (from empty directory)
118CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js --ui
119​
120# 2. Start React dev server
121cd packages/cta-ui && pnpm dev:ui
122​
123# 3. Run monorepo in watch mode
124pnpm dev
125```
126​
127## Key Implementation Details
128​
129- All workspace dependencies use `workspace:*` protocol
130- EJS templates use special naming: `_dot_` prefix becomes `.` in output
131- Add-ons can provide demo routes that integrate with the router
132- The engine uses memfs for virtual file system operations during generation
133- Special steps system handles post-generation tasks (e.g., shadcn setup)