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

ARCHITECTURE.md

133 lines4.3 KB

Architecture

Terminology

TermDefinition
Add-onPlugin that extends apps (e.g., clerk, drizzle). Contains code, dependencies, and hooks.
StarterReusable preset of add-ons. Contains only configuration, no code.
FrameworkReact or Solid implementation in packages/create/src/frameworks/
Modefile-router (file-based routes) or code-router (routes defined in code)

Packages

PackagePurpose
@tanstack/cliMain CLI with commands: create, add, add-on, starter, mcp
@tanstack/createCore engine, frameworks, and add-ons
@tanstack/create-uiVisual project builder web interface

Framework Structure

packages/create/src/frameworks/
├── react/
│   ├── project/base/      # Base project template
│   ├── add-ons/           # Add-on implementations
│   ├── toolchains/        # eslint, biome
│   ├── hosts/             # vercel, netlify, cloudflare
│   └── examples/          # Demo projects
└── solid/
    └── (same structure)

EJS Template Variables

Templates (.ejs files) have access to:

VariableTypeDescription
projectNamestringProject name
typescriptbooleanTypeScript enabled
tailwindbooleanTailwind enabled
fileRouterbooleanFile-based routing mode
codeRouterbooleanCode-based routing mode
addOnEnabledRecord<string, boolean>Map of enabled add-on IDs
addOnOptionRecord<string, object>Add-on configuration options
addOnsArray<AddOn>Full add-on objects
routesArray<Route>All routes from enabled add-ons
integrationsArray<Integration>All integrations (providers, plugins)
packageManagerstringnpm, pnpm, yarn, bun, deno
jsstringts or js
jsxstringtsx or jsx

Helper Functions

FunctionDescription
ignoreFile()Skip generating this file
relativePath(target, stripExt?)Calculate relative import path
getPackageManagerAddScript(pkg, isDev?)Get install command
getPackageManagerRunScript(script, args?)Get run command

File Naming Conventions

PatternResult
file.tsCopied as-is
file.ts.ejsEJS processed, outputs file.ts
_dot_gitignoreBecomes .gitignore
file.ts.appendAppended to existing file
__option__file.tsOnly included if option selected

Add-on info.json

{
  "name": "My Add-on",
  "description": "What it does",
  "type": "add-on",           // add-on | toolchain | deployment | example
  "phase": "add-on",          // setup | add-on | example
  "modes": ["file-router"],   // Supported modes
  "priority": 100,            // Execution order (lower = earlier)
  
  "dependsOn": ["tanstack-query"],
  "conflicts": ["other-addon"],
  
  "routes": [{
    "url": "/demo/feature",
    "name": "Feature Demo",
    "path": "src/routes/demo.feature.tsx",
    "jsName": "FeatureDemo"
  }],
  
  "integrations": [{
    "type": "provider",       // provider | root-provider | vite-plugin | devtools | header-user | layout
    "jsName": "MyProvider",
    "path": "src/integrations/my-addon/provider.tsx"
  }],
  
  "options": {
    "database": {
      "type": "select",
      "label": "Database",
      "default": "postgres",
      "options": [
        { "value": "postgres", "label": "PostgreSQL" },
        { "value": "sqlite", "label": "SQLite" }
      ]
    }
  }
}

Integration Types

TypeLocationPurpose
providerWraps app in __root.tsxBasic context providers
root-providerWraps app, exports contextProviders with shared state
vite-pluginvite.config.tsVite plugins
devtoolsAfter app in __root.tsxDeveloper tools
header-userHeader componentAuth UI, user menus
layoutLayout wrapperDashboard layouts

Priority Ranges

RangeUse Case
0-10Toolchains (eslint, biome)
20-30Core libraries (start, query)
30-50UI foundations (shadcn, form)
100-150Feature add-ons (clerk, sentry)
170-200Deployment (netlify, cloudflare)