Creating Add-ons | TanStack CLI Русский

Add-ons add files, dependencies, and code hooks to generated projects.

Use this guide when you want to build and maintain your own add-on outside the built-in catalog.

Quick Start

# 1. Create base project
tanstack create my-addon-dev -y

# 2. Add your code
#    - src/integrations/my-feature/
#    - src/routes/demo/my-feature.tsx
#    - Update package.json

# 3. Extract add-on
tanstack add-on init

# 4. Edit .add-on/info.json

# 5. Compile
tanstack add-on compile

# Optional: continuously rebuild while authoring
tanstack add-on dev

# 6. Test locally
npx serve .add-on -l 9080
tanstack create test --add-ons http://localhost:9080/info.json

Structure

.add-on/
├── info.json        # Metadata (required)
├── package.json     # Dependencies (optional)
└── assets/          # Files to copy
    └── src/
        ├── integrations/my-feature/
        └── routes/demo/my-feature.tsx

Generated source of truth files in your project root:

.add-on/info.json - add-on metadata and integration config
.add-on/package.json - dependency/script additions merged into generated apps
.add-on/assets/** - template files copied into target apps

info.json

Required fields:

{
  "name": "My Feature",
  "version": "0.0.1",
  "description": "What it does",
  "type": "add-on",
  "phase": "add-on",
  "category": "tooling",
  "modes": ["file-router"]
}

Field	Values
`version`	Semantic version for your add-on metadata (e.g. `0.0.1`)
`type`	`add-on`, `toolchain`, `deployment`, `example`
`phase`	`setup`, `add-on`, `example`
`category`	`tanstack`, `auth`, `database`, `orm`, `deploy`, `tooling`, `monitoring`, `api`, `i18n`, `cms`, `other`

Optional fields:

{
  "dependsOn": ["tanstack-query"],
  "conflicts": ["other-feature"],
  "envVars": [{ "name": "API_KEY", "description": "...", "required": true }],
  "gitignorePatterns": ["*.cache"]
}

Hooks (Integrations)

Inject code into generated projects:

{
  "integrations": [
    {
      "type": "root-provider",
      "jsName": "MyProvider",
      "path": "src/integrations/my-feature/provider.tsx"
    }
  ]
}

Type	Location	Use
`root-provider`	Wraps app in `__root.tsx`	Context providers
`provider`	Same, but simpler	Basic providers
`vite-plugin`	`vite.config.ts`	Vite plugins
`devtools`	After app in `__root.tsx`	Devtools
`header-user`	Header component	User menu, auth UI
`layout`	Layout wrapper	Dashboard layouts

Demo Routes

{
  "routes": [
    {
      "url": "/demo/my-feature",
      "name": "My Feature Demo",
      "path": "src/routes/demo/my-feature.tsx",
      "jsName": "MyFeatureDemo"
    }
  ]
}

Add-on Options

Let users configure the add-on:

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

Access in EJS templates:

<% if (addOnOption['my-feature']?.database === 'postgres') { %>
// PostgreSQL code
<% } %>

EJS Templates

Files ending in .ejs are processed. Available variables:

Variable	Type	Description
`projectName`	string	Project name
`typescript`	boolean	TS enabled
`tailwind`	boolean	Tailwind enabled
`addOnEnabled`	object	`{ [id]: boolean }`
`addOnOption`	object	`{ [id]: options }`

File patterns:

Pattern	Result
`file.ts`	Copied as-is
`file.ts.ejs`	EJS processed
`_dot_gitignore`	Becomes `.gitignore`
`file.ts.append`	Appended to existing

Distribution

Host on GitHub, npm, or any URL:

tanstack create my-app --add-ons https://example.com/my-addon/info.json

Local Iteration Loop

Fastest way to iterate on a custom add-on:

# in your add-on project
tanstack add-on compile
npx serve .add-on -l 9080

# in another terminal
tanstack create test-app --add-ons http://localhost:9080/info.json

If you are actively editing templates, run tanstack add-on dev to auto-refresh .add-on and add-on.json on file changes.

Publishing Tips

Keep add-on source in git (not just compiled output).
Re-run tanstack add-on compile after each metadata/template change.
Publish .add-on contents to a stable URL.
Prefer immutable/versioned URLs for production use.

Maintenance Checklist

When you update a custom add-on:

Update templates or metadata in your source project.
Re-run tanstack add-on compile.
Test with a clean scaffold (tanstack create ... --add-ons <url>).
Verify install/build/lint in the generated app.
Publish updated .add-on assets.

Troubleshooting

Add-on not found: Verify URL points directly to info.json.
Template not applied: Ensure file is in .add-on/assets and ends with .ejs if templated.
Option not taking effect: Confirm option key matches addOnOption['<id>'] usage in template.
Integration code not injected: Check integrations[].type, jsName, and path in .add-on/info.json.