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

FRAMEWORK-STRUCTURE.md

254 lines6.2 KB

Framework Authoring Guide

This guide covers creating and customizing frameworks, add-ons, and starters for the TanStack CLI.

Directory Structure

packages/create/src/frameworks/
├── react/
│   ├── src/index.ts          # Framework registration
│   ├── project/
│   │   ├── base/             # Base project template
│   │   └── packages.json     # Conditional dependencies
│   ├── add-ons/              # Feature add-ons
│   ├── toolchains/           # eslint, biome
│   ├── hosts/                # Deployment adapters
│   └── examples/             # Demo projects
└── solid/
    └── (same structure)

Add-on Structure

add-on-name/
├── info.json                 # Metadata (required)
├── package.json              # Dependencies
├── README.md
├── small-logo.svg            # 128x128 for UI
└── assets/                   # Files to inject
    ├── src/
    │   ├── integrations/     # Integration code
    │   └── routes/           # Demo routes
    └── _dot_env.local.append # Env vars

info.json Reference

Required Fields

{
  "name": "My Add-on",
  "description": "What it does",
  "type": "add-on",
  "phase": "add-on",
  "modes": ["file-router", "code-router"]
}
FieldValues
typeadd-on, toolchain, deployment, example
phasesetup (toolchains), add-on, example
modesArray of file-router, code-router

Optional Fields

{
  "priority": 100,
  "link": "https://docs.example.com",
  "dependsOn": ["tanstack-query"],
  "conflicts": ["other-addon"],
  "shadcnComponents": ["button", "card"]
}

Routes

{
  "routes": [{
    "url": "/demo/feature",
    "name": "Feature Demo",
    "icon": "Sparkles",
    "path": "src/routes/demo.feature.tsx",
    "jsName": "FeatureDemo"
  }]
}
PropertyRequiredDescription
urlNoURL path; omit for hidden routes
nameNoHeader link text
iconNoLucide icon name
pathYesFile path
jsNameYesComponent export name

Integrations

{
  "integrations": [{
    "type": "provider",
    "jsName": "MyProvider",
    "path": "src/integrations/my-addon/provider.tsx"
  }]
}
TypeLocationPurpose
providerWraps appBasic context providers
root-providerWraps appProviders with exported context
vite-pluginvite.configBuild plugins
devtoolsAfter appDeveloper tools
header-userHeaderAuth UI, user menus
layoutLayout wrapperDashboard layouts

Vite plugin (inline):

{
  "type": "vite-plugin",
  "import": "import { plugin } from 'my-plugin'",
  "code": "plugin({ option: true })"
}

Options

{
  "options": {
    "database": {
      "type": "select",
      "label": "Database",
      "description": "Choose your database",
      "default": "postgres",
      "options": [
        { "value": "postgres", "label": "PostgreSQL" },
        { "value": "sqlite", "label": "SQLite" }
      ]
    }
  }
}

Access in templates: addOnOption.myAddon.database

EJS Templates

Files ending in .ejs are processed through EJS before output.

Available Variables

VariableTypeDescription
projectNamestringProject name
typescriptbooleanTypeScript enabled
tailwindbooleanTailwind enabled
fileRouterbooleanFile-based routing
codeRouterbooleanCode-based routing
addOnEnabledobject{ [id]: boolean }
addOnOptionobject{ [id]: options }
packageManagerstringnpm/pnpm/yarn/bun/deno
jsstringts or js
jsxstringtsx or jsx

Helper Functions

<%# Skip file if condition not met %>
<% if (!addOnEnabled.prisma) { ignoreFile() } %>

<%# Relative import path %>
import { utils } from '<%= relativePath('./src/lib/utils') %>'

<%# Package manager commands %>
Run: <%= getPackageManagerAddScript('lodash') %>
Run: <%= getPackageManagerRunScript('dev') %>

File Patterns

PatternResult
file.tsCopied as-is
file.ts.ejsEJS processed → file.ts
_dot_gitignore→ .gitignore
_dot_env.local.appendAppended to .env.local
__postgres__schema.tsOnly if option selected

Examples

Conditional TypeScript:

<% if (typescript) { %>
interface Props { name: string }
<% } %>

export default function Component(<% if (typescript) { %>{ name }: Props<% } else { %>{ name }<% } %>) {
  return <div>{name}</div>
}

Conditional imports:

<% if (addOnEnabled.clerk) { %>
import { useAuth } from '@clerk/react'
<% } %>

Router mode handling:

<% if (fileRouter) { %>
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/demo')({ component: Demo })
<% } %>
export default function Demo() { return <div>Demo</div> }

Component Types

TypetypephasePriority
Toolchaintoolchainsetup0-10
Add-onadd-onadd-on26-150
Deploymentdeploymentadd-on170-200
Exampleexampleexample-

Creating an Add-on

  1. Create base project and add your feature
  2. Run tanstack add-on init
  3. Edit .add-on/info.json
  4. Run tanstack add-on compile
  5. Test: npx serve .add-on -l 9080
  6. Use: tanstack create test --add-ons http://localhost:9080/info.json

Creating a Template

  1. Create project with desired add-ons
  2. Run tanstack template init
  3. Edit template-info.json
  4. Run tanstack template compile
  5. Use: tanstack create my-app --template ./template.json

Testing

# Watch mode
pnpm dev

# Create test project
rm -rf test && node packages/cli/dist/index.js create test --add-ons my-addon

# Dev mode for built-in templates/add-ons
node packages/cli/dist/index.js dev test-app --framework React

# Legacy direct watch path mode
node packages/cli/dist/index.js create --dev-watch ./packages/create/src/frameworks/react test-app