better-t-stack（更好的堆栈）

Better-T-Stack

Better-T-Stack is a modern CLI tool for scaffolding end-to-end type-safe TypeScript projects with customizable configurations. This skill provides expert guidance for using it effectively.

When to Use This Skill

Use this skill when:

• Creating a new TypeScript project with frontend, backend, database, ORM, auth, or addons
• Adding features (addons, deployment config) to an existing Better-T-Stack project
• Troubleshooting compatibility issues between stack components
• Deciding on the right stack combination for a project's needs
• Understanding CLI options and their interactions

Quick Start

Interactive Mode

npx create-better-t-stack@latest

Follow the prompts to choose your stack interactively.

Non-Interactive (Recommended for Agents)

npx create-better-t-stack@latest my-project \
  --frontend tanstack-router \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth \
  --addons turborepo \
  --yes

Add to Existing Project

cd my-existing-project
npx create-better-t-stack@latest add --addons pwa biome --install

Key Commands

create - Create new project

create-better-t-stack [project-directory] [options]

Core flags:

• --template [template]: Use predefined stack (choices: "mern", "pern", "t3", "uniwind", "none")
• --frontend <type>: tanstack-router, next, react-router, nuxt, svelte, solid, astro, native-uniwind, native-nativewind, none
• --backend <type>: hono, express, fastify, elysia, convex, self, none
• --database <type>: sqlite, postgres, mysql, mongodb, none
• --orm <type>: drizzle, prisma, mongoose, none
• --auth <provider>: better-auth, clerk, none
• --api <type>: trpc, orpc, none
• --addons <types...>: pwa, tauri, biome, turborepo, starlight, fumadocs, etc.
• --yes: Use defaults, skip prompts (RECOMMENDED for automation)
• --yolo: Bypass all validations (use with caution)

add - Add to existing project

create-better-t-stack add [options]

Used in project directory with bts.jsonc. Supports adding addons and deployment configs.

Critical Compatibility Rules

Must-Have Pairings

• Database + ORM: Always required together (both must be non-none)
• MongoDB: Requires prisma or mongoose (not drizzle)
• Workers runtime: Requires hono backend, drizzle or prisma ORM, SQLite database

Single-Selection Constraints

• Web frameworks: Only one allowed (tanstack-router, next, etc.)
• Native frameworks: Only one allowed (native-uniwind or native-nativewind)
• Backend: Only one allowed
• Database: Only one allowed
• ORM: Only one allowed

API Compatibility

• tRPC: Not supported with nuxt, svelte, solid, or astro frontends (use oRPC instead)
• oRPC: Works with all frontends

Frontend + Backend Rules

• Web + Native: Can combine one web + one native
• Self backend (fullstack): Only supports next, tanstack-start, nuxt, and astro
• Convex backend: Not compatible with solid or astro frontends

Cloudflare Workers Constraints

--runtime workers REQUIRES:
  backend: hono (only)
  orm: drizzle or prisma (no mongoose)
  database: sqlite only (no postgres, mysql, mongodb)
  db-setup: d1 only (no docker)

Addon Compatibility

Some addons require specific frontends:

• PWA: Requires tanstack-router, react-router, solid, or next
• Tauri: Requires tanstack-router, react-router, nuxt, svelte, solid, or next
• Others: No frontend restrictions

Common Stack Patterns

Using Predefined Templates

npx create-better-t-stack my-app --template t3

Available templates:

• t3: Modern full-stack TypeScript stack
• mern: MongoDB, Express, React, Node
• pern: PostgreSQL, Express, React, Node
• uniwind: React Native with NativeWind styling
• none: No predefined template (configure manually)

Templates set multiple options at once. You can override specific flags:

npx create-better-t-stack my-app --template t3 --database postgres

Full-Stack Web App (Default)

npx create-better-t-stack my-webapp \
  --frontend tanstack-router \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth \
  --addons turborepo \
  --yes

Backend-Only API Server

npx create-better-t-stack my-api \
  --frontend none \
  --backend fastify \
  --runtime node \
  --database postgres \
  --orm prisma \
  --api trpc \
  --yes

Frontend-Only SPA

npx create-better-t-stack my-frontend \
  --frontend next \
  --backend none \
  --api none \
  --yes

Web + Native App

npx create-better-t-stack my-app \
  --frontend next native-uniwind \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth \
  --yes

Cloudflare Workers App

npx create-better-t-stack my-workers \
  --runtime workers \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --db-setup d1 \
  --yes

Important Notes

Mobile Development

When using native frontends with local backend development:

# Use machine IP, not localhost
EXPO_PUBLIC_SERVER_URL=http://192.168.1.X:3000

bts.jsonc File

• Created automatically during project initialization
• Stores stack configuration for add command
• Safe to delete if you don't use add command
• Must exist for add command to work

Programmatic API

For automation and CI/CD:

import { init } from "create-better-t-stack";

const result = await init("my-project", {
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
  auth: "better-auth",
  yes: true
});

if (!result.success) {
  console.error(result.error);
}

Best Practices

1. Always use --yes flag for agent-driven tasks to avoid interactive prompts
2. Start with recommended defaults, then customize as needed
3. Validate compatibility before generating commands - check critical rules above
4. Use --yolo only when you're certain about compatibility and want to skip validation
5. Keep bts.jsonc if you plan to use add command later
6. Match database type to production needs (sqlite for dev, postgres/mysql/mongodb for prod)
7. Choose ORM based on database: Drizzle for SQL, Mongoose for MongoDB

Reference Documentation

For complete details on:

• All compatibility rules and validation logic: references/COMPATIBILITY.md
• Complete CLI options and flags: references/OPTIONS.md
• Best practices and patterns: references/BEST-PRACTICES.md
• Example setups for different use cases: examples/SETUPS.md

Troubleshooting

Common Issues

"Incompatible addon/frontend combination"

• Check COMPATIBILITY.md for addon requirements
• Some addons (PWA, Tauri) require specific frontends

"Cannot select multiple web frameworks"

• Use only one web framework at a time
• Can combine one web + one native (e.g., --frontend next native-uniwind)

"MongoDB database is not compatible with Cloudflare Workers runtime"

• Workers runtime only supports SQLite with Drizzle/Prisma
• Use a different runtime or database

"Database requires an ORM"

• Must select both database and ORM (both non-none)
• MongoDB requires Mongoose or Prisma (not Drizzle)

"Backend 'self' only supports Next.js and TanStack Start"

• Use a different backend (hono, express, etc.) for other frontends
• Or switch frontend to next or tanstack-start