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

ARCHITECTURE.md

133 lines4.3 KB

1# Architecture
2​
3## Terminology
4​
5| Term | Definition |
6|------|------------|
7| **Add-on** | Plugin that extends apps (e.g., `clerk`, `drizzle`). Contains code, dependencies, and hooks. |
8| **Starter** | Reusable preset of add-ons. Contains only configuration, no code. |
9| **Framework** | React or Solid implementation in `packages/create/src/frameworks/` |
10| **Mode** | `file-router` (file-based routes) or `code-router` (routes defined in code) |
11​
12## Packages
13​
14| Package | Purpose |
15|---------|---------|
16| `@tanstack/cli` | Main CLI with commands: `create`, `add`, `add-on`, `starter`, `mcp` |
17| `@tanstack/create` | Core engine, frameworks, and add-ons |
18| `@tanstack/create-ui` | Visual project builder web interface |
19​
20## Framework Structure
21​
22```
23packages/create/src/frameworks/
24├── react/
25│ ├── project/base/ # Base project template
26│ ├── add-ons/ # Add-on implementations
27│ ├── toolchains/ # eslint, biome
28│ ├── hosts/ # vercel, netlify, cloudflare
29│ └── examples/ # Demo projects
30└── solid/
31 └── (same structure)
32```
33​
34## EJS Template Variables
35​
36Templates (`.ejs` files) have access to:
37​
38| Variable | Type | Description |
39|----------|------|-------------|
40| `projectName` | `string` | Project name |
41| `typescript` | `boolean` | TypeScript enabled |
42| `tailwind` | `boolean` | Tailwind enabled |
43| `fileRouter` | `boolean` | File-based routing mode |
44| `codeRouter` | `boolean` | Code-based routing mode |
45| `addOnEnabled` | `Record<string, boolean>` | Map of enabled add-on IDs |
46| `addOnOption` | `Record<string, object>` | Add-on configuration options |
47| `addOns` | `Array<AddOn>` | Full add-on objects |
48| `routes` | `Array<Route>` | All routes from enabled add-ons |
49| `integrations` | `Array<Integration>` | All integrations (providers, plugins) |
50| `packageManager` | `string` | `npm`, `pnpm`, `yarn`, `bun`, `deno` |
51| `js` | `string` | `ts` or `js` |
52| `jsx` | `string` | `tsx` or `jsx` |
53​
54## Helper Functions
55​
56| Function | Description |
57|----------|-------------|
58| `ignoreFile()` | Skip generating this file |
59| `relativePath(target, stripExt?)` | Calculate relative import path |
60| `getPackageManagerAddScript(pkg, isDev?)` | Get install command |
61| `getPackageManagerRunScript(script, args?)` | Get run command |
62​
63## File Naming Conventions
64​
65| Pattern | Result |
66|---------|--------|
67| `file.ts` | Copied as-is |
68| `file.ts.ejs` | EJS processed, outputs `file.ts` |
69| `_dot_gitignore` | Becomes `.gitignore` |
70| `file.ts.append` | Appended to existing file |
71| `__option__file.ts` | Only included if option selected |
72​
73## Add-on info.json
74​
75```json
77 "name": "My Add-on",
78 "description": "What it does",
79 "type": "add-on", // add-on | toolchain | deployment | example
80 "phase": "add-on", // setup | add-on | example
81 "modes": ["file-router"], // Supported modes
82 "priority": 100, // Execution order (lower = earlier)
84 "dependsOn": ["tanstack-query"],
85 "conflicts": ["other-addon"],
87 "routes": [{
88 "url": "/demo/feature",
89 "name": "Feature Demo",
90 "path": "src/routes/demo.feature.tsx",
91 "jsName": "FeatureDemo"
92 }],
94 "integrations": [{
95 "type": "provider", // provider | root-provider | vite-plugin | devtools | header-user | layout
96 "jsName": "MyProvider",
97 "path": "src/integrations/my-addon/provider.tsx"
98 }],
100 "options": {
101 "database": {
102 "type": "select",
103 "label": "Database",
104 "default": "postgres",
105 "options": [
106 { "value": "postgres", "label": "PostgreSQL" },
107 { "value": "sqlite", "label": "SQLite" }
108 ]
109 }
110 }
112```
113​
114## Integration Types
115​
116| Type | Location | Purpose |
117|------|----------|---------|
118| `provider` | Wraps app in `__root.tsx` | Basic context providers |
119| `root-provider` | Wraps app, exports context | Providers with shared state |
120| `vite-plugin` | `vite.config.ts` | Vite plugins |
121| `devtools` | After app in `__root.tsx` | Developer tools |
122| `header-user` | Header component | Auth UI, user menus |
123| `layout` | Layout wrapper | Dashboard layouts |
124​
125## Priority Ranges
126​
127| Range | Use Case |
128|-------|----------|
129| 0-10 | Toolchains (eslint, biome) |
130| 20-30 | Core libraries (start, query) |
131| 30-50 | UI foundations (shadcn, form) |
132| 100-150 | Feature add-ons (clerk, sentry) |
133| 170-200 | Deployment (netlify, cloudflare) |