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
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
49{
50 "name": "My Feature",
51 "description": "What it does",
52 "type": "add-on",
53 "phase": "add-on",
54 "category": "tooling",
55 "modes": ["file-router"]
56}
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
68{
69 "dependsOn": ["tanstack-query"],
70 "conflicts": ["other-feature"],
71 "envVars": [{ "name": "API_KEY", "description": "...", "required": true }],
72 "gitignorePatterns": ["*.cache"]
73}
74```
75
76## Hooks (Integrations)
77
78Inject code into generated projects:
79
80```json
81{
82 "integrations": [
83 {
84 "type": "root-provider",
85 "jsName": "MyProvider",
86 "path": "src/integrations/my-feature/provider.tsx"
87 }
88 ]
89}
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
104{
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 ]
113}
114```
115
116## Add-on Options
117
118Let users configure the add-on:
119
120```json
121{
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 }
133}
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```