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

FRAMEWORK-STRUCTURE.md

254 lines6.2 KB

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
43 "name": "My Add-on",
44 "description": "What it does",
45 "type": "add-on",
46 "phase": "add-on",
47 "modes": ["file-router", "code-router"]
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
61 "priority": 100,
62 "link": "https://docs.example.com",
63 "dependsOn": ["tanstack-query"],
64 "conflicts": ["other-addon"],
65 "shadcnComponents": ["button", "card"]
67```
68​
69### Routes
70​
71```json
73 "routes": [{
74 "url": "/demo/feature",
75 "name": "Feature Demo",
76 "icon": "Sparkles",
77 "path": "src/routes/demo.feature.tsx",
78 "jsName": "FeatureDemo"
79 }]
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
95 "integrations": [{
96 "type": "provider",
97 "jsName": "MyProvider",
98 "path": "src/integrations/my-addon/provider.tsx"
99 }]
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
115 "type": "vite-plugin",
116 "import": "import { plugin } from 'my-plugin'",
117 "code": "plugin({ option: true })"
119```
120​
121### Options
122​
123```json
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 }
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>
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```