Open History to see the last commit
1# Framework Authoring Guide
2
3This guide covers creating and customizing frameworks, add-ons, and starters for the TanStack CLI.
4
5## Directory Structure
6
7```
8packages/create/src/frameworks/
9├── react/
10│ ├── src/index.ts # Framework registration
11│ ├── project/
12│ │ ├── base/ # Base project template
13│ │ └── packages.json # Conditional dependencies
14│ ├── add-ons/ # Feature add-ons
15│ ├── toolchains/ # eslint, biome
16│ ├── hosts/ # Deployment adapters
17│ └── examples/ # Demo projects
18└── solid/
19 └── (same structure)
20```
21
22## Add-on Structure
23
24```
25add-on-name/
26├── info.json # Metadata (required)
27├── package.json # Dependencies
28├── README.md
29├── small-logo.svg # 128x128 for UI
30└── assets/ # Files to inject
31 ├── src/
32 │ ├── integrations/ # Integration code
33 │ └── routes/ # Demo routes
34 └── _dot_env.local.append # Env vars
35```
36
37## info.json Reference
38
39### Required Fields
40
41```json
42{
43 "name": "My Add-on",
44 "description": "What it does",
45 "type": "add-on",
46 "phase": "add-on",
47 "modes": ["file-router", "code-router"]
48}
49```
50
51| Field | Values |
52|-------|--------|
53| `type` | `add-on`, `toolchain`, `deployment`, `example` |
54| `phase` | `setup` (toolchains), `add-on`, `example` |
55| `modes` | Array of `file-router`, `code-router` |
56
57### Optional Fields
58
59```json
60{
61 "priority": 100,
62 "link": "https://docs.example.com",
63 "dependsOn": ["tanstack-query"],
64 "conflicts": ["other-addon"],
65 "shadcnComponents": ["button", "card"]
66}
67```
68
69### Routes
70
71```json
72{
73 "routes": [{
74 "url": "/demo/feature",
75 "name": "Feature Demo",
76 "icon": "Sparkles",
77 "path": "src/routes/demo.feature.tsx",
78 "jsName": "FeatureDemo"
79 }]
80}
81```
82
83| Property | Required | Description |
84|----------|----------|-------------|
85| `url` | No | URL path; omit for hidden routes |
86| `name` | No | Header link text |
87| `icon` | No | Lucide icon name |
88| `path` | Yes | File path |
89| `jsName` | Yes | Component export name |
90
91### Integrations
92
93```json
94{
95 "integrations": [{
96 "type": "provider",
97 "jsName": "MyProvider",
98 "path": "src/integrations/my-addon/provider.tsx"
99 }]
100}
101```
102
103| Type | Location | Purpose |
104|------|----------|---------|
105| `provider` | Wraps app | Basic context providers |
106| `root-provider` | Wraps app | Providers with exported context |
107| `vite-plugin` | vite.config | Build plugins |
108| `devtools` | After app | Developer tools |
109| `header-user` | Header | Auth UI, user menus |
110| `layout` | Layout wrapper | Dashboard layouts |
111
112**Vite plugin (inline):**
113```json
114{
115 "type": "vite-plugin",
116 "import": "import { plugin } from 'my-plugin'",
117 "code": "plugin({ option: true })"
118}
119```
120
121### Options
122
123```json
124{
125 "options": {
126 "database": {
127 "type": "select",
128 "label": "Database",
129 "description": "Choose your database",
130 "default": "postgres",
131 "options": [
132 { "value": "postgres", "label": "PostgreSQL" },
133 { "value": "sqlite", "label": "SQLite" }
134 ]
135 }
136 }
137}
138```
139
140Access in templates: `addOnOption.myAddon.database`
141
142## EJS Templates
143
144Files ending in `.ejs` are processed through EJS before output.
145
146### Available Variables
147
148| Variable | Type | Description |
149|----------|------|-------------|
150| `projectName` | string | Project name |
151| `typescript` | boolean | TypeScript enabled |
152| `tailwind` | boolean | Tailwind enabled |
153| `fileRouter` | boolean | File-based routing |
154| `codeRouter` | boolean | Code-based routing |
155| `addOnEnabled` | object | `{ [id]: boolean }` |
156| `addOnOption` | object | `{ [id]: options }` |
157| `packageManager` | string | npm/pnpm/yarn/bun/deno |
158| `js` | string | `ts` or `js` |
159| `jsx` | string | `tsx` or `jsx` |
160
161### Helper Functions
162
163```ejs
164<%# Skip file if condition not met %>
165<% if (!addOnEnabled.prisma) { ignoreFile() } %>
166
167<%# Relative import path %>
168import { utils } from '<%= relativePath('./src/lib/utils') %>'
169
170<%# Package manager commands %>
171Run: <%= getPackageManagerAddScript('lodash') %>
172Run: <%= getPackageManagerRunScript('dev') %>
173```
174
175### File Patterns
176
177| Pattern | Result |
178|---------|--------|
179| `file.ts` | Copied as-is |
180| `file.ts.ejs` | EJS processed → `file.ts` |
181| `_dot_gitignore` | → `.gitignore` |
182| `_dot_env.local.append` | Appended to `.env.local` |
183| `__postgres__schema.ts` | Only if option selected |
184
185### Examples
186
187**Conditional TypeScript:**
188```ejs
189<% if (typescript) { %>
190interface Props { name: string }
191<% } %>
192
193export default function Component(<% if (typescript) { %>{ name }: Props<% } else { %>{ name }<% } %>) {
194 return <div>{name}</div>
195}
196```
197
198**Conditional imports:**
199```ejs
200<% if (addOnEnabled.clerk) { %>
201import { useAuth } from '@clerk/react'
202<% } %>
203```
204
205**Router mode handling:**
206```ejs
207<% if (fileRouter) { %>
208import { createFileRoute } from '@tanstack/react-router'
209export const Route = createFileRoute('/demo')({ component: Demo })
210<% } %>
211export default function Demo() { return <div>Demo</div> }
212```
213
214## Component Types
215
216| Type | `type` | `phase` | Priority |
217|------|--------|---------|----------|
218| Toolchain | `toolchain` | `setup` | 0-10 |
219| Add-on | `add-on` | `add-on` | 26-150 |
220| Deployment | `deployment` | `add-on` | 170-200 |
221| Example | `example` | `example` | - |
222
223## Creating an Add-on
224
2251. Create base project and add your feature
2262. Run `tanstack add-on init`
2273. Edit `.add-on/info.json`
2284. Run `tanstack add-on compile`
2295. Test: `npx serve .add-on -l 9080`
2306. Use: `tanstack create test --add-ons http://localhost:9080/info.json`
231
232## Creating a Template
233
2341. Create project with desired add-ons
2352. Run `tanstack template init`
2363. Edit `template-info.json`
2374. Run `tanstack template compile`
2385. Use: `tanstack create my-app --template ./template.json`
239
240## Testing
241
242```bash
243# Watch mode
244pnpm dev
245
246# Create test project
247rm -rf test && node packages/cli/dist/index.js create test --add-ons my-addon
248
249# Dev mode for built-in templates/add-ons
250node packages/cli/dist/index.js dev test-app --framework React
251
252# Legacy direct watch path mode
253node packages/cli/dist/index.js create --dev-watch ./packages/create/src/frameworks/react test-app
254```