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

Always use --yes flag for agent-driven tasks to avoid interactive prompts
Start with recommended defaults, then customize as needed
Validate compatibility before generating commands - check critical rules above
Use --yolo only when you're certain about compatibility and want to skip validation
Keep bts.jsonc if you plan to use add command later
Match database type to production needs (sqlite for dev, postgres/mysql/mongodb for prod)
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

better-t-stack