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

creating-add-ons.md

171 lines3.4 KB

1---
2id: creating-add-ons
3title: Creating Add-ons
4---
5​
6Add-ons add files, dependencies, and code hooks to generated projects.
7​
8## Quick Start
9​
10```bash
11# 1. Create base project
12tanstack create my-addon-dev -y
13​
14# 2. Add your code
15# - src/integrations/my-feature/
16# - src/routes/demo/my-feature.tsx
17# - Update package.json
18​
19# 3. Extract add-on
20tanstack add-on init
21​
22# 4. Edit .add-on/info.json
23​
24# 5. Compile
25tanstack add-on compile
26​
27# 6. Test locally
28npx serve .add-on -l 9080
29tanstack create test --add-ons http://localhost:9080/info.json
30```
31​
32## Structure
33​
34```
35.add-on/
36├── info.json # Metadata (required)
37├── package.json # Dependencies (optional)
38└── assets/ # Files to copy
39 └── src/
40 ├── integrations/my-feature/
41 └── routes/demo/my-feature.tsx
42```
43​
44## info.json
45​
46Required fields:
47​
48```json
50 "name": "My Feature",
51 "description": "What it does",
52 "type": "add-on",
53 "phase": "add-on",
54 "category": "tooling",
55 "modes": ["file-router"]
57```
58​
59| Field | Values |
60|-------|--------|
61| `type` | `add-on`, `toolchain`, `deployment`, `example` |
62| `phase` | `setup`, `add-on`, `example` |
63| `category` | `tanstack`, `auth`, `database`, `orm`, `deploy`, `tooling`, `monitoring`, `api`, `i18n`, `cms`, `other` |
64​
65Optional fields:
66​
67```json
69 "dependsOn": ["tanstack-query"],
70 "conflicts": ["other-feature"],
71 "envVars": [{ "name": "API_KEY", "description": "...", "required": true }],
72 "gitignorePatterns": ["*.cache"]
74```
75​
76## Hooks (Integrations)
77​
78Inject code into generated projects:
79​
80```json
82 "integrations": [
83 {
84 "type": "root-provider",
85 "jsName": "MyProvider",
86 "path": "src/integrations/my-feature/provider.tsx"
87 }
88 ]
90```
91​
92| Type | Location | Use |
93|------|----------|-----|
94| `root-provider` | Wraps app in `__root.tsx` | Context providers |
95| `provider` | Same, but simpler | Basic providers |
96| `vite-plugin` | `vite.config.ts` | Vite plugins |
97| `devtools` | After app in `__root.tsx` | Devtools |
98| `header-user` | Header component | User menu, auth UI |
99| `layout` | Layout wrapper | Dashboard layouts |
100​
101## Demo Routes
102​
103```json
105 "routes": [
106 {
107 "url": "/demo/my-feature",
108 "name": "My Feature Demo",
109 "path": "src/routes/demo/my-feature.tsx",
110 "jsName": "MyFeatureDemo"
111 }
112 ]
114```
115​
116## Add-on Options
117​
118Let users configure the add-on:
119​
120```json
122 "options": {
123 "database": {
124 "type": "select",
125 "label": "Database",
126 "options": [
127 { "value": "postgres", "label": "PostgreSQL" },
128 { "value": "sqlite", "label": "SQLite" }
129 ],
130 "default": "postgres"
131 }
132 }
134```
135​
136Access in EJS templates:
137​
138```ejs
139<% if (addOnOption['my-feature']?.database === 'postgres') { %>
140// PostgreSQL code
141<% } %>
142```
143​
144## EJS Templates
145​
146Files ending in `.ejs` are processed. Available variables:
147​
148| Variable | Type | Description |
149|----------|------|-------------|
150| `projectName` | string | Project name |
151| `typescript` | boolean | TS enabled |
152| `tailwind` | boolean | Tailwind enabled |
153| `addOnEnabled` | object | `{ [id]: boolean }` |
154| `addOnOption` | object | `{ [id]: options }` |
155​
156File patterns:
157​
158| Pattern | Result |
159|---------|--------|
160| `file.ts` | Copied as-is |
161| `file.ts.ejs` | EJS processed |
162| `_dot_gitignore` | Becomes `.gitignore` |
163| `file.ts.append` | Appended to existing |
164​
165## Distribution
166​
167Host on GitHub, npm, or any URL:
168​
169```bash
170tanstack create my-app --add-ons https://example.com/my-addon/info.json
171```