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