Skip to content

Commit fd0af9c

Browse files
tannerlinsleytannerlinsley
committed
docs: audit and reorganize for correctness and maintainability
- Fix terminology: 'add-ons' (not 'integrations'), 'starters' (not 'templates') - Fix CLI commands: 'tanstack add-on' (not 'tanstack integration'), 'tanstack starter' (not 'tanstack template') - Add missing flags: --router-only, --interactive, --list-add-ons, --addon-details, --force - Remove hardcoded add-on lists to reduce maintenance burden (use --list-add-ons instead) - Rename docs/integrations.md -> docs/add-ons.md - Rename docs/templates.md -> docs/starters.md - Rename docs/creating-integrations.md -> docs/creating-add-ons.md - Consolidate FRAMEWORK-STRUCTURE.md from 1269 to 251 lines - Streamline CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md - Update docs/config.json navigation
1 parent 067da73 commit fd0af9c

19 files changed

+756
-1905
lines changed

‎ARCHITECTURE.md‎

Lines changed: 128 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,133 @@
1-
## Nomenclature
1+
# Architecture
22

3-
- TanStack CLI - The command line interface for creating and managing TanStack applications
4-
- Framework - A framework that supports the creation of a TanStack Application using a specific technology (e.g. React, Solid)
5-
- `code-router` - One of two _modes_ of TanStack Application. The other is `file-router`. The code router is when the applications routes are defined in code.
6-
- `file-router` - One of two _modes_ of TanStack Application. The other is `code-router`. The file router is when the applications routes are defined in files (usually in the `src/routes` directory).
7-
- `add-on` - A plugin that extends the capabilities of a TanStack Application (e.g. the `tanstack-query` add-on integrates TanStack Query into the application).
8-
- custom `add-on` - An externalized `add-on` contained in a single JSON file that can integate technologies that aren't covered with the built-in add-ons.
9-
- `starter` - An application template that is constructed from an existing application that has been modified to the customers needs. The advantage of a starter over a cloneable git repo is that when a starter is used the add-ons and project will be created using the latest version of the framework and the add-ons. This reduces the versioning burden on the customer. This does come with a risk of potential breaking changes.
3+
## Terminology
104

11-
## CLI Applications
12-
13-
- `tanstack` - The main CLI application (`@tanstack/cli`)
14-
- `create-tanstack` - Deprecated alias for `tanstack create`
15-
- `create-start-app` - Deprecated alias for `tanstack create`
16-
- `create-tsrouter-app` - Deprecated alias for `tanstack create`
5+
| Term | Definition |
6+
|------|------------|
7+
| **Add-on** | Plugin that extends apps (e.g., `clerk`, `drizzle`). Contains code, dependencies, and hooks. |
8+
| **Starter** | Reusable preset of add-ons. Contains only configuration, no code. |
9+
| **Framework** | React or Solid implementation in `packages/create/src/frameworks/` |
10+
| **Mode** | `file-router` (file-based routes) or `code-router` (routes defined in code) |
1711

1812
## Packages
1913

20-
- `@tanstack/cli` - The command line interface for TanStack
21-
- `@tanstack/create` - The core engine that powers app creation
22-
- `@tanstack/create-ui` - The UI components for the visual app creator
23-
24-
## Frameworks
25-
26-
Frameworks are now bundled within `@tanstack/create`:
27-
- React framework (`packages/create/src/frameworks/react`)
28-
- Solid framework (`packages/create/src/frameworks/solid`)
29-
30-
## File Templates
31-
32-
The system uses EJS to render the files into the final application.
33-
34-
Below are all of the variables that are available to the file templates.
35-
36-
| Variable | Description |
37-
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
38-
| `packageManager` | The package manager that is being used (e.g. `npm`, `yarn`, `pnpm`) |
39-
| `projectName` | The name of the project |
40-
| `typescript` | Boolean value that is `true` if TypeScript is being used, otherwise it is `false` |
41-
| `tailwind` | Boolean value that is `true` if Tailwind CSS is being used, otherwise it is `false` |
42-
| `js` | The file extension for files that do not include JSX. When in TypeScript mode it is `ts`. When in JavaScript mode it is `js`. |
43-
| `jsx` | The file extension for files that include JSX. When in TypeScript mode it is `tsx`. When in JavaScript mode it is `jsx`. |
44-
| `fileRouter` | Boolean value that is `true` if the file router is being used, otherwise it is `false` |
45-
| `codeRouter` | Boolean value that is `true` if the code router is being used, otherwise it is `false` |
46-
| `addOnEnabled` | An object that contains the enabled add-ons. The keys are the `id` values of the add-ons. For example, if the tanstack-query add-on is enabled the `addOnEnabled]['tanstack-query']` will be `true`. |
47-
| `addOns` | An array of the enabled add-on objects |
48-
| `integrations` | An array of the enabled integrations |
49-
| `routes` | An array containing all of the routes from all of the add-ons. (Used by the header and the `code-router` setup.) |
50-
| `getPackageManagerAddScript` | A function that returns the script to add a dependency to the project. |
51-
| `getPackageManagerRunScript` | A function that returns the script to run a command in the project. |
52-
| `relativePath` | A function that returns the relative path from the current file to the specified target file. |
53-
| `ignoreFile` | A function that if called will tell the engine to not include this file in the application. |
14+
| Package | Purpose |
15+
|---------|---------|
16+
| `@tanstack/cli` | Main CLI with commands: `create`, `add`, `add-on`, `starter`, `mcp` |
17+
| `@tanstack/create` | Core engine, frameworks, and add-ons |
18+
| `@tanstack/create-ui` | Visual project builder web interface |
19+
20+
## Framework Structure
21+
22+
```
23+
packages/create/src/frameworks/
24+
├── react/
25+
│ ├── project/base/ # Base project template
26+
│ ├── add-ons/ # Add-on implementations
27+
│ ├── toolchains/ # eslint, biome
28+
│ ├── hosts/ # vercel, netlify, cloudflare
29+
│ └── examples/ # Demo projects
30+
└── solid/
31+
└── (same structure)
32+
```
33+
34+
## EJS Template Variables
35+
36+
Templates (`.ejs` files) have access to:
37+
38+
| Variable | Type | Description |
39+
|----------|------|-------------|
40+
| `projectName` | `string` | Project name |
41+
| `typescript` | `boolean` | TypeScript enabled |
42+
| `tailwind` | `boolean` | Tailwind enabled |
43+
| `fileRouter` | `boolean` | File-based routing mode |
44+
| `codeRouter` | `boolean` | Code-based routing mode |
45+
| `addOnEnabled` | `Record<string, boolean>` | Map of enabled add-on IDs |
46+
| `addOnOption` | `Record<string, object>` | Add-on configuration options |
47+
| `addOns` | `Array<AddOn>` | Full add-on objects |
48+
| `routes` | `Array<Route>` | All routes from enabled add-ons |
49+
| `integrations` | `Array<Integration>` | All integrations (providers, plugins) |
50+
| `packageManager` | `string` | `npm`, `pnpm`, `yarn`, `bun`, `deno` |
51+
| `js` | `string` | `ts` or `js` |
52+
| `jsx` | `string` | `tsx` or `jsx` |
53+
54+
## Helper Functions
55+
56+
| Function | Description |
57+
|----------|-------------|
58+
| `ignoreFile()` | Skip generating this file |
59+
| `relativePath(target, stripExt?)` | Calculate relative import path |
60+
| `getPackageManagerAddScript(pkg, isDev?)` | Get install command |
61+
| `getPackageManagerRunScript(script, args?)` | Get run command |
62+
63+
## File Naming Conventions
64+
65+
| Pattern | Result |
66+
|---------|--------|
67+
| `file.ts` | Copied as-is |
68+
| `file.ts.ejs` | EJS processed, outputs `file.ts` |
69+
| `_dot_gitignore` | Becomes `.gitignore` |
70+
| `file.ts.append` | Appended to existing file |
71+
| `__option__file.ts` | Only included if option selected |
72+
73+
## Add-on info.json
74+
75+
```json
76+
{
77+
"name": "My Add-on",
78+
"description": "What it does",
79+
"type": "add-on", // add-on | toolchain | deployment | example
80+
"phase": "add-on", // setup | add-on | example
81+
"modes": ["file-router"], // Supported modes
82+
"priority": 100, // Execution order (lower = earlier)
83+
84+
"dependsOn": ["tanstack-query"],
85+
"conflicts": ["other-addon"],
86+
87+
"routes": [{
88+
"url": "/demo/feature",
89+
"name": "Feature Demo",
90+
"path": "src/routes/demo.feature.tsx",
91+
"jsName": "FeatureDemo"
92+
}],
93+
94+
"integrations": [{
95+
"type": "provider", // provider | root-provider | vite-plugin | devtools | header-user | layout
96+
"jsName": "MyProvider",
97+
"path": "src/integrations/my-addon/provider.tsx"
98+
}],
99+
100+
"options": {
101+
"database": {
102+
"type": "select",
103+
"label": "Database",
104+
"default": "postgres",
105+
"options": [
106+
{ "value": "postgres", "label": "PostgreSQL" },
107+
{ "value": "sqlite", "label": "SQLite" }
108+
]
109+
}
110+
}
111+
}
112+
```
113+
114+
## Integration Types
115+
116+
| Type | Location | Purpose |
117+
|------|----------|---------|
118+
| `provider` | Wraps app in `__root.tsx` | Basic context providers |
119+
| `root-provider` | Wraps app, exports context | Providers with shared state |
120+
| `vite-plugin` | `vite.config.ts` | Vite plugins |
121+
| `devtools` | After app in `__root.tsx` | Developer tools |
122+
| `header-user` | Header component | Auth UI, user menus |
123+
| `layout` | Layout wrapper | Dashboard layouts |
124+
125+
## Priority Ranges
126+
127+
| Range | Use Case |
128+
|-------|----------|
129+
| 0-10 | Toolchains (eslint, biome) |
130+
| 20-30 | Core libraries (start, query) |
131+
| 30-50 | UI foundations (shadcn, form) |
132+
| 100-150 | Feature add-ons (clerk, sentry) |
133+
| 170-200 | Deployment (netlify, cloudflare) |

0 commit comments

Comments
 (0)