Open History to see the last commit
1---
2id: creating-add-ons
3title: Creating Add-ons
4---
5
6Add-ons add files, dependencies, and code hooks to generated projects.
7
8Use this guide when you want to build and maintain your own add-on outside the built-in catalog.
9
10## Quick Start
11
12```bash
13# 1. Create base project
14tanstack create my-addon-dev -y
15
16# 2. Add your code
17# - src/integrations/my-feature/
18# - src/routes/demo/my-feature.tsx
19# - Update package.json
20
21# 3. Extract add-on
22tanstack add-on init
23
24# 4. Edit .add-on/info.json
25
26# 5. Compile
27tanstack add-on compile
28
29# Optional: continuously rebuild while authoring
30tanstack add-on dev
31
32# 6. Test locally
33npx serve .add-on -l 9080
34tanstack create test --add-ons http://localhost:9080/info.json
35```
36
37## Structure
38
39```
40.add-on/
41├── info.json # Metadata (required)
42├── package.json # Dependencies (optional)
43└── assets/ # Files to copy
44 └── src/
45 ├── integrations/my-feature/
46 └── routes/demo/my-feature.tsx
47```
48
49Generated source of truth files in your project root:
50
51- `.add-on/info.json` - add-on metadata and integration config
52- `.add-on/package.json` - dependency/script additions merged into generated apps
53- `.add-on/assets/**` - template files copied into target apps
54
55## info.json
56
57Required fields:
58
59```json
60{
61 "name": "My Feature",
62 "version": "0.0.1",
63 "description": "What it does",
64 "type": "add-on",
65 "phase": "add-on",
66 "category": "tooling",
67 "modes": ["file-router"]
68}
69```
70
71| Field | Values |
72|-------|--------|
73| `version` | Semantic version for your add-on metadata (e.g. `0.0.1`) |
74| `type` | `add-on`, `toolchain`, `deployment`, `example` |
75| `phase` | `setup`, `add-on`, `example` |
76| `category` | `tanstack`, `auth`, `database`, `orm`, `deploy`, `tooling`, `monitoring`, `api`, `i18n`, `cms`, `other` |
77
78Optional fields:
79
80```json
81{
82 "dependsOn": ["tanstack-query"],
83 "conflicts": ["other-feature"],
84 "envVars": [{ "name": "API_KEY", "description": "...", "required": true }],
85 "gitignorePatterns": ["*.cache"]
86}
87```
88
89## Hooks (Integrations)
90
91Inject code into generated projects:
92
93```json
94{
95 "integrations": [
96 {
97 "type": "root-provider",
98 "jsName": "MyProvider",
99 "path": "src/integrations/my-feature/provider.tsx"
100 }
101 ]
102}
103```
104
105| Type | Location | Use |
106|------|----------|-----|
107| `root-provider` | Wraps app in `__root.tsx` | Context providers |
108| `provider` | Same, but simpler | Basic providers |
109| `vite-plugin` | `vite.config.ts` | Vite plugins |
110| `devtools` | After app in `__root.tsx` | Devtools |
111| `header-user` | Header component | User menu, auth UI |
112| `layout` | Layout wrapper | Dashboard layouts |
113
114## Demo Routes
115
116```json
117{
118 "routes": [
119 {
120 "url": "/demo/my-feature",
121 "name": "My Feature Demo",
122 "path": "src/routes/demo/my-feature.tsx",
123 "jsName": "MyFeatureDemo"
124 }
125 ]
126}
127```
128
129## Add-on Options
130
131Let users configure the add-on:
132
133```json
134{
135 "options": {
136 "database": {
137 "type": "select",
138 "label": "Database",
139 "options": [
140 { "value": "postgres", "label": "PostgreSQL" },
141 { "value": "sqlite", "label": "SQLite" }
142 ],
143 "default": "postgres"
144 }
145 }
146}
147```
148
149Access in EJS templates:
150
151```ejs
152<% if (addOnOption['my-feature']?.database === 'postgres') { %>
153// PostgreSQL code
154<% } %>
155```
156
157## EJS Templates
158
159Files ending in `.ejs` are processed. Available variables:
160
161| Variable | Type | Description |
162|----------|------|-------------|
163| `projectName` | string | Project name |
164| `typescript` | boolean | TS enabled |
165| `tailwind` | boolean | Tailwind enabled |
166| `addOnEnabled` | object | `{ [id]: boolean }` |
167| `addOnOption` | object | `{ [id]: options }` |
168
169File patterns:
170
171| Pattern | Result |
172|---------|--------|
173| `file.ts` | Copied as-is |
174| `file.ts.ejs` | EJS processed |
175| `_dot_gitignore` | Becomes `.gitignore` |
176| `file.ts.append` | Appended to existing |
177
178## Distribution
179
180Host on GitHub, npm, or any URL:
181
182```bash
183tanstack create my-app --add-ons https://example.com/my-addon/info.json
184```
185
186### Local Iteration Loop
187
188Fastest way to iterate on a custom add-on:
189
190```bash
191# in your add-on project
192tanstack add-on compile
193npx serve .add-on -l 9080
194
195# in another terminal
196tanstack create test-app --add-ons http://localhost:9080/info.json
197```
198
199If you are actively editing templates, run `tanstack add-on dev` to auto-refresh `.add-on` and `add-on.json` on file changes.
200
201### Publishing Tips
202
203- Keep add-on source in git (not just compiled output).
204- Re-run `tanstack add-on compile` after each metadata/template change.
205- Publish `.add-on` contents to a stable URL.
206- Prefer immutable/versioned URLs for production use.
207
208## Maintenance Checklist
209
210When you update a custom add-on:
211
2121. Update templates or metadata in your source project.
2132. Re-run `tanstack add-on compile`.
2143. Test with a clean scaffold (`tanstack create ... --add-ons <url>`).
2154. Verify install/build/lint in the generated app.
2165. Publish updated `.add-on` assets.
217
218## Troubleshooting
219
220- **Add-on not found**: Verify URL points directly to `info.json`.
221- **Template not applied**: Ensure file is in `.add-on/assets` and ends with `.ejs` if templated.
222- **Option not taking effect**: Confirm option key matches `addOnOption['<id>']` usage in template.
223- **Integration code not injected**: Check `integrations[].type`, `jsName`, and `path` in `.add-on/info.json`.