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

Common Usage Patterns

Init Command Patterns

Standard Full-Stack Setup

Default Full-Stack App (Source: apps/web/content/docs/index.mdx, line 49-56)

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

Pattern: This is the recommended starting point for most full-stack applications. It provides a complete, type-safe stack with:

• Modern React frontend (TanStack Router)
• Fast, lightweight backend (Hono)
• Local database (SQLite with Drizzle)
• Authentication (Better-Auth)
• Monorepo tooling (Turborepo)

When to use: Starting a new web application, prototype, or MVP

Minimal Setup

Empty Monorepo (Source: apps/web/content/docs/index.mdx, line 82-87)

npm create better-t-stack@latest my-workspace \
  --frontend none \
  --backend none

Pattern: Creates a minimal monorepo structure with only the essential configuration files. This gives you maximum flexibility to add what you need later.

When to use: Starting a new project from scratch, creating a custom workspace, or when you want to add components manually

Frontend-Only SPA

npm create better-t-stack@latest my-frontend \
  --frontend next \
  --backend none \
  --api none \
  --addons pwa

Pattern: Creates a frontend-only project with no backend or API layer. Perfect for static sites, SPAs consuming external APIs, or when using a separate backend service.

When to use: Marketing sites, dashboards, applications using external APIs, when backend is managed separately

Multi-Frontend Setup

Web + Native Frontends (Source: apps/web/content/docs/cli/options.mdx, line 238-239)

npm create better-t-stack@latest my-app \
  --frontend next native-uniwind

Pattern: Combines a web frontend with a React Native frontend in the same monorepo. Both share the same backend, API, and authentication infrastructure.

Key Points (Source: apps/web/content/docs/cli/compatibility.mdx, line 112-123):

• ✅ Allowed: One web + one native framework
• ❌ Not allowed: Multiple web frameworks
• ❌ Not allowed: Multiple native frameworks

When to use: Applications that need both web and mobile interfaces sharing the same backend

Important Note: Mobile app requires special configuration for local development (Source: apps/web/content/docs/faq.mdx, line 63-65):

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

Add Command Patterns

Adding Addons

Interactive Mode (Source: apps/web/content/docs/cli/index.mdx, line 82-84)

cd my-existing-project
create-better-t-stack add

Pattern: Runs the add command interactively, prompting you to select addons to add to your existing project. The CLI detects your current stack from bts.jsonc and validates compatibility.

Specific Addons (Source: apps/web/content/docs/cli/index.mdx, line 86-87)

cd my-existing-project
create-better-t-stack add --addons pwa tauri biome --install

Pattern: Adds specific addons non-interactively. Useful for automation and scripts.

Common Addon Combinations:

PWA + Biome

create-better-t-stack add --addons pwa biome --install

• PWA for mobile-friendly experience
• Biome for fast linting and formatting

Turborepo + Lefthook

create-better-t-stack add --addons turborepo lefthook --install

• Turborepo for monorepo management
• Lefthook for Git hooks

Documentation (Starlight or Fumadocs)

create-better-t-stack add --addons starlight --install

• Adds documentation site to your monorepo

Adding Deployment

Web Deployment (Source: apps/web/content/docs/cli/index.mdx, line 89-90)

cd my-project
create-better-t-stack add --web-deploy alchemy

Pattern: Adds Cloudflare Workers deployment configuration for your web frontend. This generates:

• packages/infra/ directory with Alchemy configuration
• alchemy.run.ts file for deployment
• Environment variable setup
• Deployment scripts

Server Deployment

cd my-project
create-better-t-stack add --server-deploy alchemy

Pattern: Adds Cloudflare Workers deployment configuration for your server backend.

Combined Deployment

cd my-project
create-better-t-stack add --web-deploy alchemy --server-deploy alchemy

Pattern: Adds deployment configuration for both web and server, creating a full stack deployment to Cloudflare Workers.

Important: The add command requires bts.jsonc to be present in the project root. This file is created by the init command and contains your stack configuration (Source: apps/web/content/docs/bts-config.mdx, line 6-17).

Updating Configuration

Recreate Project with Changes

# Use the reproducible command from bts.jsonc
bun create better-t-stack my-app-v2 --frontend tanstack-router --backend hono ...

Pattern: If you need to change fundamental aspects of your stack (like backend framework or ORM), it's often easier to create a new project and migrate your code.

Manual Updates

• You can manually edit bts.jsonc to reflect changes you've made to your project
• This helps the add command understand your current stack
• However, be careful as this doesn't regenerate code

Stack Combinations

Recommended Combinations

The "T3 Stack" Modernized

create-better-t-stack my-app \
  --frontend next \
  --backend next \
  --database postgres \
  --orm prisma \
  --auth better-auth \
  --api trpc

When to use: Full-stack Next.js application with API routes

Convex + React + Clerk (Source: apps/web/content/docs/index.mdx, line 58-67, slightly modified)

create-better-t-stack my-app \
  --frontend tanstack-router \
  --backend convex \
  --auth clerk \
  --database none

Pattern: Convex backend automatically sets:

• --auth clerk (if compatible frontend)
• --database none (Convex provides database)
• --orm none (Convex provides data layer)
• --api none (Convex provides API)
• --runtime none (Convex manages runtime)
• --db-setup none (Convex manages hosting)

When to use: Applications needing real-time features, automatic backend scaling, or when you prefer a managed backend solution

Cloudflare Workers + D1 + Hono + Drizzle

create-better-t-stack my-app \
  --frontend tanstack-router \
  --backend hono \
  --runtime workers \
  --database sqlite \
  --orm drizzle \
  --db-setup d1 \
  --web-deploy alchemy \
  --server-deploy alchemy

Pattern: Serverless edge deployment with type-safe infrastructure.

Constraints (Source: apps/web/content/docs/cli/compatibility.mdx, line 38-58):

• Backend must be Hono
• ORM must be Drizzle or Prisma (not Mongoose)
• Database must be SQLite (not MongoDB)
• db-setup must be d1 (not docker)

When to use: Global applications, edge computing, serverless architecture

Common Use Cases

API Server

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

When to use: Building a REST or GraphQL API, microservices, or when the frontend is separate

Full-Stack E-commerce

create-better-t-stack my-shop \
  --frontend next \
  --backend hono \
  --runtime bun \
  --database postgres \
  --orm drizzle \
  --auth better-auth \
  --payments polar \
  --examples todo

Pattern: Includes Better-Auth for authentication and Polar payments for payment processing.

When to use: E-commerce sites, SaaS applications with payments

Documentation Site

create-better-t-stack my-docs \
  --frontend none \
  --backend none \
  --addons starlight

Pattern: Creates a documentation-only site using Starlight (Astro-based).

When to use: Project documentation, knowledge base, static documentation sites

Example Stacks

Todo App Example (Source: apps/web/content/docs/cli/options.mdx, line 315-316)

create-better-t-stack my-app \
  --examples todo

Pattern: Adds a complete todo example application to your project. This example demonstrates:

• CRUD operations
• Database integration
• API communication (if API selected)
• Authentication flows (if auth selected)

Requirements (Source: apps/web/content/docs/cli/compatibility.mdx, line 211-215):

• Requires database when backend is present (except Convex)
• Cannot be used with --backend none and --database none

AI Chat Example (Source: apps/web/content/docs/cli/options.mdx, line 316)

create-better-t-stack my-app \
  --examples ai

Pattern: Adds an AI chat interface example. This example demonstrates:

• AI integration patterns
• Real-time communication
• Complex state management

Restrictions (Source: apps/web/content/docs/cli/compatibility.mdx, line 217-221):

• Not compatible with --backend elysia
• Not compatible with --frontend solid

Workflow Patterns

Development Workflow

Interactive Development

# 1. Create project with prompts
npm create better-t-stack@latest my-app

# 2. Navigate to project
cd my-app

# 3. Install dependencies (if not auto-installed)
bun install

# 4. Start development server
bun run dev

Pattern: Use interactive mode when exploring options or learning the tool. The prompts guide you through choices and validate compatibility.

Non-Interactive Development

# 1. Create project with all options specified
npm create better-t-stack@latest my-app \
  --frontend tanstack-router \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth \
  --yes

# 2. Navigate to project
cd my-app

# 3. Start development
bun run dev

Pattern: Use non-interactive mode for reproducible project creation, automation, or when you know exactly what you want.

Using Stack Builder UI (Source: apps/web/content/docs/index.mdx, line 35-42)

# 1. Open stack builder
npm create better-t-stack@latest builder

# 2. Visual configuration opens in browser
# 3. Select stack components visually
# 4. Copy generated command

# 5. Paste and run command
npm create better-t-stack@latest my-app [pasted command]

Pattern: Use the UI when you're unsure about options, want to visualize your stack, or prefer visual selection over command-line flags.

Testing Workflow

Local Testing

# 1. Start development server
bun run dev

# 2. Run database migrations (if needed)
bun run db:push

# 3. Open database studio (optional)
bun run db:studio

# 4. Run tests (if any)
bun test

Pattern: Standard development workflow for testing changes locally.

Testing CLI Changes (Source: apps/web/content/docs/contributing.mdx, line 84-86)

# 1. Build CLI
cd apps/cli
bun dev

# 2. Test in separate directory
cd /tmp
create-better-t-stack test-project

Pattern: When developing CLI changes, use bun link or test in a separate directory to verify changes.

Deployment Workflow

Traditional Deployment

# 1. Build project
bun run build

# 2. Deploy to your platform
# (Platform-specific commands)

Cloudflare Workers Deployment (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 456-497)

# 1. Set environment variables
# Edit packages/infra/.env
ALCHEMY_PASSWORD=your-secure-password
STAGE=prod

# 2. Deploy
bun run deploy

# 3. Update environment variables for production
# Edit apps/web/.env and apps/server/.env
VITE_SERVER_URL=https://my-app-server.subdomain.workers.dev
CORS_ORIGIN=https://my-app-web.subdomain.workers.dev

# 4. Deploy again to apply changes
bun run deploy

Pattern: Deploy to Cloudflare Workers using Alchemy infrastructure-as-code.

Multi-Stage Deployment

# 1. Deploy to development (default)
bun run deploy

# 2. Deploy to staging
bun run deploy --stage staging

# 3. Deploy to production
bun run deploy --stage prod

Pattern: Use multiple stages for development, testing, and production environments.

Migration Workflow

Adding Features to Existing Project

# 1. Ensure bts.jsonc exists
cd my-project
ls bts.jsonc  # Should exist

# 2. Add features
create-better-t-stack add --addons pwa tauri --install

# 3. Restart development server
bun run dev

Pattern: Use the add command to incrementally add features to an existing project.

Migrating to New Stack

# 1. Create new project with desired stack
create-better-t-stack my-app-v2 \
  --frontend next \
  --backend hono \
  --database postgres \
  --orm drizzle

# 2. Copy application code
cp -r my-app/src my-app-v2/src

# 3. Adapt code to new stack
# (Manual changes to match new stack structure)

# 4. Test thoroughly
cd my-app-v2
bun run dev

Pattern: When changing fundamental aspects of your stack, it's often easier to create a new project and migrate code manually.

Programmatic API Patterns

Automation Workflows (Source: apps/web/content/docs/cli/programmatic-api.mdx, line 20-47)

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

async function createProject() {
  const result = await create("my-app", {
    yes: true,
    frontend: ["tanstack-router"],
    backend: "hono",
    database: "sqlite",
    orm: "drizzle",
    auth: "better-auth",
    packageManager: "bun",
    install: false,
    disableAnalytics: true,
  });

  if (result.success) {
    console.log(`✅ Project created at: ${result.projectDirectory}`);
    console.log(`📝 Reproducible command: ${result.reproducibleCommand}`);
  } else {
    console.error(`❌ Failed: ${result.error}`);
  }
}

createProject();

Pattern: Use the programmatic API for automation, CI/CD pipelines, and custom tooling.

Directory Conflict Handling (Source: apps/web/content/docs/cli/programmatic-api.mdx, line 52-59)

const result = await create("existing-folder", {
  yes: true,
  directoryConflict: "increment", // Creates "existing-folder-1"
  renderTitle: false,
});

Pattern: Handle existing directories gracefully by incrementing the name.

Custom Template Patterns

Using Predefined Templates (Source: apps/web/content/docs/cli/options.mdx, line 16-28)

# T3 Stack
create-better-t-stack my-app --template t3

# MERN Stack
create-better-t-stack my-app --template mern

# PERN Stack
create-better-t-stack my-app --template pern

# UniWind React Native
create-better-t-stack my-app --template uniwind

Pattern: Use predefined templates for common stack combinations.

Customizing After Creation

# 1. Create with base template
create-better-t-stack my-app --template t3

# 2. Add additional features
cd my-app
create-better-t-stack add --addons pwa biome

# 3. Customize manually
# Edit generated code as needed

Pattern: Start with a template and customize incrementally.

Interactive Prompt Usage

Single Select Prompts (Source: apps/web/content/docs/cli/prompts.mdx, line 18-22)

• Navigation: Up/Down arrow keys
• Selection: Enter to confirm highlighted option
• Typical uses: Choosing web or native framework, runtime, API type

Multi-Select Prompts (Source: apps/web/content/docs/cli/prompts.mdx, line 24-29)

• Navigation: Up/Down arrow keys
• Toggle: Space to highlight option on/off
• Confirm: Enter to confirm selections
• Note: Some prompts allow selecting none (press Enter without toggling)
• Typical uses: Selecting project types (web/native), choosing examples

Grouped Multi-Select Prompts (Source: apps/web/content/docs/cli/prompts.mdx, line 33-39)

• Structure: Options organized under group headings
• Navigation: Up/Down, Space to toggle, Enter to confirm
• Note: Group headings are informational; toggle items within groups
• Typical uses: Selecting addons (Biome, PWA, Turborepo, etc.)

Confirm Prompts (Source: apps/web/content/docs/cli/prompts.mdx, line 41-45)

• Navigation: Left/Right or Up/Down to highlight Yes/No
• Confirm: Enter to select
• Typical uses: Installing dependencies, initializing Git

Text Input Prompts (Source: apps/web/content/docs/cli/prompts.mdx, line 47-52)

• Input: Type your answer and press Enter
• Validation: If validation fails, message explains what to fix
• Correction: Edit and press Enter again
• Typical uses: Project name/path, database URLs, provider-specific inputs

Tips (Source: apps/web/content/docs/cli/prompts.mdx, line 54-57):

• Skip all prompts with --yes to use defaults
• Press Ctrl+C to cancel safely if you start the wrong flow

Environment Setup Patterns

Package Manager Selection (Source: apps/web/content/docs/cli/options.mdx, line 38-44)

# Use Bun (recommended)
create-better-t-stack my-app --package-manager bun

# Use pnpm
create-better-t-stack my-app --package-manager pnpm

# Use npm
create-better-t-stack my-app --package-manager npm

Pattern: Choose the package manager that fits your workflow and team standards.

Git Initialization (Source: apps/web/content/docs/cli/options.mdx, line 54-60)

# Initialize Git repository
create-better-t-stack my-app --git

# Skip Git initialization
create-better-t-stack my-app --no-git

Pattern: Control whether Git is initialized during project creation.

Dependency Installation (Source: apps/web/content/docs/cli/options.mdx, line 46-52)

# Install dependencies after creation (default)
create-better-t-stack my-app --install

# Skip dependency installation
create-better-t-stack my-app --no-install

Pattern: Skip installation if you want to install manually or if you're in a CI/CD environment that handles dependencies separately.

Better-T-Stack Skill

Expert guidance for using the Better-T-Stack CLI to scaffold type-safe TypeScript projects.

Overview

This skill provides comprehensive documentation for AI agents to use the Better-T-Stack CLI flawlessly. It covers:

• Complete CLI command reference with all flags and options
• Critical compatibility rules between frontend, backend, database, ORM, auth, and runtime
• Common stack patterns for different use cases (full-stack, backend-only, frontend-only, mobile, workers)
• Best practices and troubleshooting guidance
• Programmatic API usage for automation

Skill Structure

better-t-stack/
├── SKILL.md                      # Main instructions for agents (254 lines)
├── references/
│   ├── COMPATIBILITY.md            # Complete compatibility rules (640 lines)
│   ├── OPTIONS.md                  # CLI options reference (274 lines)
│   └── BEST-PRACTICES.md          # Development best practices (495 lines)
└── examples/
    └── SETUPS.md                  # Example configurations (622 lines)

Total: 2,285 lines of documentation

Critical Features Documented

1. Template System

Predefined stacks: t3, mern, pern, uniwind

2. Compatibility Rules

• Database × ORM pairing constraints
• Backend × Runtime compatibility (especially Cloudflare Workers)
• Frontend × API layer compatibility (tRPC vs oRPC)
• Addon frontend restrictions (PWA, Tauri)
• Auth provider compatibility

3. Astro Framework Support

Added complete Astro compatibility information:

• Not compatible with Convex backend
• Not compatible with tRPC API (use oRPC)
• Not compatible with Clerk + Convex
• Not compatible with AI example
• Supported by Self backend (fullstack)

4. Key CLI Commands

• create - New project with full customization
• add - Add features to existing projects
• builder - Visual stack builder
• docs - Open documentation
• sponsors - Show sponsors
• history - Creation history

Usage

Load the skill to get expert guidance:

# In opencode
skill load better-t-stack

Or reference directly when working with Better-T-Stack CLI:

"Use the better-t-stack skill to create a full-stack TypeScript project"

Review Status

Reviewed by: code-reviewer agent (2026-02-03) Score: 8.5/10 (after fixes) Critical Issues Resolved:

• ✅ Added template system documentation
• ✅ Fixed Astro compatibility gaps across all files
• ✅ Updated Self backend support (next, tanstack-start, nuxt, astro)

Status: Production-ready for agent use

Sources

Based on:

• Official documentation: https://better-t-stack.dev/docs
• Source code: https://github.com/AmanVarshney01/create-better-t-stack
• CLI help: npx create-better-t-stack@latest --help

All claims reference specific file paths and line numbers for verification.

Contributing

To improve this skill: 1. Test commands with actual Better-T-Stack CLI 2. Verify compatibility rules against source code 3. Add new patterns and examples 4. Update documentation for new CLI versions

Better-T-Stack Best Practices

Choosing the Right Stack

For Full-Stack Apps

Recommended Default Stack (Source: apps/web/content/docs/index.mdx, line 49-56):

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

This stack provides:

• TanStack Router: Modern React routing with type-safe navigation
• Hono: Fast, lightweight backend framework
• SQLite + Drizzle: Simple local development with TypeScript-first ORM
• Better-Auth: Flexible authentication solution
• Turborepo: Monorepo management for efficient builds

For Backend-Only Projects

API Server (Source: apps/web/content/docs/index.mdx, line 61-67):

npm create better-t-stack@latest my-api \
  --frontend none \
  --backend fastify \
  --runtime node \
  --database postgres \
  --orm prisma \
  --api trpc

Best practices:

• Use Fastify for high-performance Node.js backends
• Prisma for robust database management in production
• PostgreSQL for production databases
• tRPC for type-safe API communication

For Frontend-Only Projects

SPA with External API:

npm create better-t-stack@latest my-frontend \
  --frontend next \
  --backend none \
  --api none

Considerations:

• Next.js for SSR/SSG capabilities
• TanStack Router for pure SPAs
• Add PWA addon for mobile-friendly experience

For Native Apps

Mobile App (Source: apps/web/content/docs/index.mdx, line 72-79):

npm create better-t-stack@latest my-native \
  --frontend native-uniwind \
  --backend hono \
  --database sqlite \
  --orm drizzle \
  --auth better-auth

Best practices:

• NativeWind/Unistyles for React Native styling
• Hono backend for fast API responses
• SQLite for local development database
• Set EXPO_PUBLIC_SERVER_URL to machine IP (not localhost) for mobile connection (Source: apps/web/content/docs/faq.mdx, line 63-65)

Configuration Management

bts.jsonc Management

Purpose: (Source: apps/web/content/docs/bts-config.mdx, line 6-8)

• Captures stack choices during project creation
• Required for add command to detect current stack
• Helps validate compatibility and pre-fill sensible defaults

Safe to Delete: (Source: apps/web/content/docs/bts-config.mdx, line 19-21)

• Safe to delete for normal development
• Generated code remains the source of truth
• Must keep if using add command later

Structure: (Source: apps/web/content/docs/bts-config.mdx, line 27-47)

{
  "$schema": "https://r2.better-t-stack.dev/schema.json",
  "version": "x.y.z",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "reproducibleCommand": "bun create better-t-stack my-app --frontend tanstack-router ...",
  "frontend": ["tanstack-router"],
  "backend": "hono",
  "runtime": "bun",
  "database": "sqlite",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "better-auth",
  "addons": ["turborepo"],
  "examples": [],
  "dbSetup": "none",
  "webDeploy": "none",
  "serverDeploy": "none",
  "packageManager": "bun"
}

Environment Variables

For Traditional Runtimes: (Source: apps/web/content/docs/project-structure.mdx, line 406-416)

• Use process.env for server environment variables
• Client variables use VITE_ prefix with t3-env validation

For Cloudflare Workers: (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 396-411)

• Server env vars come from Worker bindings, not process.env
• Types come from Alchemy via env.d.ts file
• No t3-env validation needed for server env (bindings are already type-safe)
• Client env vars always use t3-env validation

Project Updates

Using Add Command: (Source: apps/web/content/docs/cli/index.mdx, line 63-91)

# Add addons interactively
create-better-t-stack add

# Add specific addons
create-better-t-stack add --addons pwa tauri --install

# Add deployment setup
create-better-t-stack add --web-deploy alchemy

Important: The add command requires bts.jsonc to be present in the project root.

Usage Patterns

init vs add Commands

Use `init` (default command) when: (Source: apps/web/content/docs/cli/index.mdx, line 10-61)

• Creating a new project from scratch
• Starting with a fresh codebase
• Using a predefined template

Use `add` when: (Source: apps/web/content/docs/cli/index.mdx, line 63-91)

• Adding features to an existing Better-T-Stack project
• Adding deployment configuration
• Adding addons to an existing project

Workflow Patterns

Interactive Mode: (Source: apps/web/content/docs/cli/prompts.mdx, line 8-58)

• Use prompts when exploring options
• Navigate with Up/Down arrows
• Confirm with Enter
• Cancel with Ctrl+C
• Toggle multi-select options with Space

Non-Interactive Mode: (Source: apps/web/content/docs/cli/index.mdx, line 24-25)

npm create better-t-stack@latest --yes

• Skip all prompts and use defaults
• Useful for automation and CI/CD

UI-Based Stack Builder: (Source: apps/web/content/docs/index.mdx, line 35-42)

npm create better-t-stack@latest builder

• Opens web-based stack builder at /new
• Visual selection of stack components
• Generates command to copy and paste

Common Workflows

Development Workflow: (Source: apps/web/content/docs/project-structure.mdx, line 386-417)

With Turborepo:

# Start all apps
turbo dev

# Start specific app
turbo -F web dev
turbo -F server dev

# Build all
turbo build

# Database operations
turbo -F server db:push
turbo -F server db:studio

Without Turborepo (Bun example):

# Start all apps
bun run --filter '*' dev

# Start specific app
bun run --filter web dev
bun run --filter server dev

# Build all
bun run --filter '*' build

Development Practices

Testing

Testing CLI: (Source: .search-data/better-t-stack/repo/AGENTS.md, line 15-20)

# Run all tests
bun test

# Run specific test file
bun test apps/cli/test/cli.test.ts

# Run specific test case
bun test -t "test name pattern"

# Always build before testing build artifacts
bun run build

Run in Watch Mode: (Source: apps/web/content/docs/contributing.mdx, line 40-42)

cd apps/cli
bun dev

Deployment

Cloudflare Workers with Alchemy: (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 440-497)

Deploy commands:

# Deploy to default stage
bun run deploy

# Deploy to specific stage
bun run deploy --stage prod

# Development mode (local emulation)
bun run dev

# Destroy resources
bun run destroy

Multi-stage deployments:

• Each stage has isolated state and resources
• State stored in .alchemy/<stage>/ directories
• Stage resolution order: --stage > ALCHEMY_STAGE > STAGE > $USER > "dev"

Maintenance

Linting and Formatting: (Source: .search-data/better-t-stack/repo/AGENTS.md, line 22-24)

bun check  # Runs oxfmt and oxlint
oxfmt .     # Fix formatting issues

Commit Conventions: (Source: apps/web/content/docs/contributing.mdx, line 108-118)

feat(cli): add new CLI feature
fix(cli): fix CLI bug
feat(web): add new web feature
fix(web): fix web bug
chore(web): update dependencies
docs: update documentation

Performance Considerations

Runtime Selection

Bun: (Source: apps/web/content/docs/index.mdx, line 95)

• Recommended package manager and runtime
• Fastest JavaScript runtime
• Best for development and production
• Native support for file operations

Node.js: (Source: apps/web/content/docs/index.mdx, line 95)

• LTS version required (20+) (Source: apps/web/content/docs/faq.mdx, line 27)
• Traditional, stable runtime
• Best for legacy integration
• Good ecosystem support

Cloudflare Workers: (Source: apps/web/content/docs/cli/compatibility.mdx, line 38-58)

• Serverless edge computing
• Must use Hono backend
• Supports Drizzle and Prisma (not Mongoose)
• Cannot use MongoDB
• Requires D1 database setup
• No Docker support

Database Selection

SQLite: (Source: apps/web/content/docs/cli/options.mdx, line 125)

• Lightweight, file-based database
• Best for local development
• Works with Drizzle and Prisma
• Compatible with Turso and Cloudflare D1

PostgreSQL: (Source: apps/web/content/docs/cli/options.mdx, line 126)

• Advanced relational database
• Production-ready
• Works with Drizzle and Prisma
• Compatible with Neon, Supabase, PlanetScale

MySQL: (Source: apps/web/content/docs/cli/options.mdx, line 127)

• Traditional relational database
• Works with Drizzle and Prisma
• Compatible with PlanetScale

MongoDB: (Source: apps/web/content/docs/cli/options.mdx, line 128)

• Document database
• Requires Mongoose or Prisma (not Drizzle)
• Compatible with MongoDB Atlas

Addon Selection

Turborepo: (Source: apps/web/content/docs/project-structure.mdx, line 355-402)

• Use for monorepos with multiple packages
• Provides build caching and task orchestration
• Improves build performance
• Adds turbo.json configuration

PWA: (Source: apps/web/content/docs/cli/options.mdx, line 289)

• Requires web frontend
• Compatible with tanstack-router, react-router, next, solid
• Not compatible with native-only projects
• Adds offline capabilities

Tauri: (Source: apps/web/content/docs/cli/options.mdx, line 290)

• Desktop app support
• Requires web frontend
• Cannot be combined with native frameworks
• Compatible with tanstack-router, react-router, nuxt, svelte, solid, next

Security Best Practices

Authentication Setup

Better-Auth Requirements: (Source: apps/web/content/docs/cli/options.mdx, line 263-266)

• Requires both a database and backend framework
• Can work without database (with Convex backend or custom config)
• Adds src/lib/auth.ts on server
• Adds login/dashboard pages on web app

Clerk Requirements: (Source: apps/web/content/docs/cli/options.mdx, line 264)

• Only available with Convex backend
• Compatible with React frameworks, Next.js, TanStack Start, native frameworks
• Not compatible with Nuxt, Svelte, or Solid

Cross-Subdomain Cookies (Cloudflare Workers): (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 549-576)

// packages/auth/src/auth.ts
export const auth = betterAuth({
  session: {
    cookieCache: {
      enabled: true,
      maxAge: 5 * 60, // 5 minutes
    },
  },
  advanced: {
    crossSubDomainCookies: {
      enabled: true,
      domain: ".workers.dev", // Shared domain for cookies
    },
  },
});

Database Security

ORM Security:

• Always use parameterized queries (ORMs handle this automatically)
• Validate user input at the application layer
• Use environment variables for database credentials
• Never commit database connection strings

Environment Variables: (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 161-204)

• Use alchemy.secret.env for sensitive values (API keys, credentials, secrets)
• Use alchemy.env for non-sensitive values (URLs, feature flags, stage identifiers)
• Secrets are encrypted with AES-256-GCM
• Set ALCHEMY_PASSWORD for secret encryption/decryption

Deployment Security

Analytics: (Source: apps/web/content/docs/analytics.mdx, line 6-19)

• CLI sends project_created event with stack choices and environment data
• Random session ID (no IP collection)
• Project name, path, and file contents are NOT collected
• Disable with BTS_TELEMETRY_DISABLED=1 environment variable

Secrets in CI/CD: (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 208-220)

# GitHub Actions
env:
  ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}

• Generate strong password: openssl rand -base64 32
• Store password securely (never commit to source control)
• For Convex backends, use convex env set to set secrets directly

Cross-Domain Considerations: (Source: apps/web/content/docs/guides/cloudflare-alchemy.mdx, line 525-578)

• Web and server Workers have different domains
• Update VITE_SERVER_URL and CORS_ORIGIN for production URLs
• Configure crossSubDomainCookies for auth across subdomains
• Pay attention to CORS settings when moving between stages

Contributing

Prerequisites: (Source: apps/web/content/docs/contributing.mdx, line 20-24)

• Node.js LTS
• Bun (recommended)
• Git

Development Setup: (Source: apps/web/content/docs/contributing.mdx, line 28-50)

# Clone repository
git clone https://github.com/AmanVarshney01/create-better-t-stack.git
cd create-better-t-stack
bun install

# Develop CLI
cd apps/cli
bun link  # Optional global link
bun dev    # Watch mode

# Develop docs
bun i
cd packages/backend
bun dev:setup

Contribution Flow: (Source: apps/web/content/docs/contributing.mdx, line 74-107) 1. Open an issue/discussion before starting major work 2. Fork repository 3. Create feature branch 4. Make changes following existing code style 5. Update docs as needed 6. Test and format 7. Commit and push 8. Open Pull Request

Programmatic Usage

Use Programmatic API for: (Source: apps/web/content/docs/cli/index.mdx, line 163-187)

• Build tools and generators
• CI/CD pipelines
• Development workflows
• Custom tooling integration

Basic Example: (Source: apps/web/content/docs/cli/programmatic-api.mdx, line 22-47)

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

const result = await create("my-app", {
  yes: true, // Use defaults, no prompts
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
  auth: "better-auth",
  packageManager: "bun",
  install: false,
  disableAnalytics: true,
});

if (result.success) {
  console.log(`✅ Project created at: ${result.projectDirectory}`);
  console.log(`📝 Reproducible command: ${result.reproducibleCommand}`);
  console.log(`⏱️  Time taken: ${result.elapsedTimeMs}ms`);
} else {
  console.error(`❌ Failed: ${result.error}`);
}

Getting Help

• Docs: Quick Start, CLI, Project Structure, Compatibility (Source: apps/web/content/docs/faq.mdx, line 76-78)
• Ask/Report: GitHub Issues & Discussions
• Community: Discord (Source: apps/web/content/docs/contributing.mdx, line 122)
• Analytics: /analytics page or https://r2.better-t-stack.dev/analytics-data.json (Source: apps/web/content/docs/analytics.mdx, line 34-36)

Compatibility Rules Reference

Overview

The Better-T-Stack CLI validates option combinations to ensure generated projects work correctly. This document provides a comprehensive reference of all compatibility rules and restrictions.

Source: apps/web/content/docs/cli/compatibility.mdx

Database & ORM Compatibility

Required Combinations

Source: apps/web/content/docs/cli/compatibility.mdx, line 14-20

Restrictions

MongoDB + Drizzle: ❌ Not supported

• Drizzle doesn't support MongoDB
• Solution: Use Mongoose or Prisma with MongoDB

Database without ORM: ❌ Not supported

• Database requires an ORM for code generation
• Solution: Select an ORM (drizzle, prisma, or mongoose)

ORM without Database: ❌ Not supported

• ORM requires a database target
• Solution: Select a database (sqlite, postgres, mysql, or mongodb)

Source: apps/web/content/docs/cli/compatibility.mdx, line 22-27

Valid Combinations

# ✅ Valid - SQLite with Drizzle
create-better-t-stack --database sqlite --orm drizzle

# ✅ Valid - SQLite with Prisma
create-better-t-stack --database sqlite --orm prisma

# ✅ Valid - PostgreSQL with Drizzle
create-better-t-stack --database postgres --orm drizzle

# ✅ Valid - PostgreSQL with Prisma
create-better-t-stack --database postgres --orm prisma

# ✅ Valid - MySQL with Drizzle
create-better-t-stack --database mysql --orm drizzle

# ✅ Valid - MySQL with Prisma
create-better-t-stack --database mysql --orm prisma

# ✅ Valid - MongoDB with Mongoose
create-better-t-stack --database mongodb --orm mongoose

# ✅ Valid - MongoDB with Prisma
create-better-t-stack --database mongodb --orm prisma

# ❌ Invalid - MongoDB with Drizzle
create-better-t-stack --database mongodb --orm drizzle

Source: apps/web/content/docs/cli/compatibility.mdx, line 28-34

Backend & Runtime Compatibility

Cloudflare Workers Restrictions

Cloudflare Workers has specific compatibility requirements:

Source: apps/web/content/docs/cli/compatibility.mdx, line 40-47

Valid Cloudflare Workers Combinations

# ✅ Valid - Workers with Hono and Drizzle (D1)
create-better-t-stack --runtime workers --backend hono --database sqlite --orm drizzle --db-setup d1

# ✅ Valid - Workers with Hono and Prisma (D1)
create-better-t-stack --runtime workers --backend hono --database sqlite --orm prisma --db-setup d1

# ❌ Invalid - Workers with Express
create-better-t-stack --runtime workers --backend express

# ❌ Invalid - Workers with MongoDB
create-better-t-stack --runtime workers --database mongodb

# ❌ Invalid - Workers with Docker
create-better-t-stack --runtime workers --db-setup docker

Source: apps/web/content/docs/cli/compatibility.mdx, line 48-58

Backend Presets

Convex Backend

When using --backend convex, the following options are automatically set:

Source: apps/web/content/docs/cli/compatibility.mdx, line 62-72

Convex Clerk Support: Convex supports Clerk authentication with compatible frontends:

• ✅ Supported: React frameworks, Next.js, TanStack Start, native frameworks
• ❌ Not supported: Nuxt, Svelte, Solid

Source: apps/web/content/docs/cli/compatibility.mdx, line 74

No Backend

When using --backend none, the following options are automatically set:

Source: apps/web/content/docs/cli/compatibility.mdx, line 76-86

Frontend & API Compatibility

API Framework Support

Source: apps/web/content/docs/cli/compatibility.mdx, line 90-101

Valid API Combinations

# ✅ Valid - React frameworks with tRPC
create-better-t-stack --frontend tanstack-router --api trpc
create-better-t-stack --frontend next --api trpc

# ✅ Valid - React frameworks with oRPC
create-better-t-stack --frontend tanstack-router --api orpc
create-better-t-stack --frontend next --api orpc

# ✅ Valid - Nuxt/Svelte/Solid with oRPC
create-better-t-stack --frontend nuxt --api orpc
create-better-t-stack --frontend svelte --api orpc
create-better-t-stack --frontend solid --api orpc

# ❌ Invalid - Nuxt with tRPC
create-better-t-stack --frontend nuxt --api trpc

# ❌ Invalid - Svelte with tRPC
create-better-t-stack --frontend svelte --api trpc

# ❌ Invalid - Solid with tRPC
create-better-t-stack --frontend solid --api trpc

Source: apps/web/content/docs/cli/compatibility.mdx, line 103-109

Frontend Restrictions

Multiple Web Frontends: ❌ Not allowed

• Only one web framework allowed per project

Multiple Native Frontends: ❌ Not allowed

• Only one native framework allowed per project

Web + Native: ✅ Allowed

• One web and one native framework allowed together

Source: apps/web/content/docs/cli/compatibility.mdx, line 111-116

Valid Frontend Combinations

# ✅ Valid - Single web frontend
create-better-t-stack --frontend next

# ✅ Valid - Single native frontend
create-better-t-stack --frontend native-uniwind

# ✅ Valid - Web + native
create-better-t-stack --frontend next native-uniwind

# ❌ Invalid - Multiple web frontends
create-better-t-stack --frontend next tanstack-router

# ❌ Invalid - Multiple native frontends
create-better-t-stack --frontend native-uniwind native-unistyles

Source: apps/web/content/docs/cli/compatibility.mdx, line 117-123

Database Setup Compatibility

Provider Requirements

Source: apps/web/content/docs/cli/compatibility.mdx, line 127-138

Special Cases

Cloudflare D1

Requirements:

• Requires --database sqlite
• Requires --runtime workers
• Requires --backend hono

Valid Combination:

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

Source: apps/web/content/docs/cli/compatibility.mdx, line 142-147

Docker Setup

Restrictions:

• Cannot be used with sqlite (file-based database)
• Cannot be used with workers runtime (serverless environment)

Source: apps/web/content/docs/cli/compatibility.mdx, line 149-151

Valid Database Setup Combinations

# ✅ Valid - Turso with SQLite
create-better-t-stack --database sqlite --db-setup turso

# ✅ Valid - Neon with PostgreSQL
create-better-t-stack --database postgres --db-setup neon

# ✅ Valid - Supabase with PostgreSQL
create-better-t-stack --database postgres --db-setup supabase

# ✅ Valid - PlanetScale with MySQL
create-better-t-stack --database mysql --db-setup planetscale

# ✅ Valid - MongoDB Atlas with MongoDB
create-better-t-stack --database mongodb --db-setup mongodb-atlas

# ✅ Valid - Docker with PostgreSQL
create-better-t-stack --database postgres --db-setup docker

# ✅ Valid - Docker with MySQL
create-better-t-stack --database mysql --db-setup docker

# ✅ Valid - Docker with MongoDB
create-better-t-stack --database mongodb --db-setup docker

# ❌ Invalid - Docker with SQLite
create-better-t-stack --database sqlite --db-setup docker

# ❌ Invalid - Docker with Workers
create-better-t-stack --runtime workers --db-setup docker

Source: apps/web/content/docs/cli/compatibility.mdx, line 127-138

Addon Compatibility

PWA Support

Requirements:

• Requires web frontend
• Compatible frontends: tanstack-router, react-router, next, solid
• Not compatible with native-only projects

Source: apps/web/content/docs/cli/compatibility.mdx, line 155-159

Tauri (Desktop Apps)

Requirements:

• Requires web frontend
• Compatible frontends: tanstack-router, react-router, nuxt, svelte, solid, next
• Cannot be combined with native frameworks

Source: apps/web/content/docs/cli/compatibility.mdx, line 161-165

Web Deployment

Requirements:

• --web-deploy alchemy requires a web frontend
• Cannot be used with native-only projects

Source: apps/web/content/docs/cli/compatibility.mdx, line 167-170

Valid Addon Combinations

# ✅ Valid - PWA with web frontend
create-better-t-stack --frontend next --addons pwa

# ✅ Valid - Tauri with web frontend
create-better-t-stack --frontend tanstack-router --addons tauri

# ❌ Invalid - PWA with native-only
create-better-t-stack --frontend native-uniwind --addons pwa

# ❌ Invalid - Tauri with native framework
create-better-t-stack --frontend next native-uniwind --addons tauri

# ✅ Valid - Web deployment with web frontend
create-better-t-stack --frontend next --web-deploy alchemy

# ❌ Invalid - Web deployment with native-only
create-better-t-stack --frontend native-uniwind --web-deploy alchemy

Source: apps/web/content/docs/cli/compatibility.mdx, line 155-170

Authentication Requirements

Better-Auth Requirements

Better-Auth authentication requires:

1. A backend framework (cannot be none) 2. With database: Requires an ORM 3. Without database: Works with Convex backend or custom configuration

Source: apps/web/content/docs/cli/compatibility.mdx, line 174-180

Clerk Requirements

Clerk authentication requires:

1. Convex backend (--backend convex) 2. Compatible frontends (React frameworks, Next.js, TanStack Start, native frameworks) 3. Not compatible with Nuxt, Svelte, or Solid

Source: apps/web/content/docs/cli/compatibility.mdx, line 182-188

Payments Requirements

Polar payments require:

• Better-Auth authentication

Source: apps/web/content/docs/cli/compatibility.mdx, line 190-192

Valid Authentication Combinations

# ✅ Valid - Better-Auth with database and backend
create-better-t-stack --auth better-auth --database postgres --orm drizzle --backend hono

# ✅ Valid - Better-Auth without database (custom config)
create-better-t-stack --auth better-auth --database none --backend hono

# ✅ Valid - Clerk with Convex and compatible frontend
create-better-t-stack --auth clerk --backend convex --frontend tanstack-router

# ✅ Valid - Clerk with Convex and native framework
create-better-t-stack --auth clerk --backend convex --frontend native-uniwind

# ❌ Invalid - Clerk without Convex
create-better-t-stack --auth clerk --backend hono

# ❌ Invalid - Clerk with incompatible frontend (Nuxt)
create-better-t-stack --auth clerk --backend convex --frontend nuxt

# ❌ Invalid - Clerk with incompatible frontend (Svelte)
create-better-t-stack --auth clerk --backend convex --frontend svelte

# ❌ Invalid - Clerk with incompatible frontend (Solid)
create-better-t-stack --auth clerk --backend convex --frontend solid

# ❌ Invalid - Polar payments without Better-Auth
create-better-t-stack --payments polar --auth none

# ✅ Valid - Polar payments with Better-Auth
create-better-t-stack --payments polar --auth better-auth

Source: apps/web/content/docs/cli/compatibility.mdx, line 196-208

Example Compatibility

Todo Example

Requirements:

• Requires a database when backend is present (except Convex)
• Cannot be used with --backend none and --database none

Source: apps/web/content/docs/cli/compatibility.mdx, line 211-215

AI Example

Restrictions:

• Not compatible with --backend elysia
• Not compatible with --frontend solid

Source: apps/web/content/docs/cli/compatibility.mdx, line 217-221

Valid Example Combinations

# ✅ Valid - Todo example with database
create-better-t-stack --examples todo --database postgres --orm prisma

# ✅ Valid - Todo example with Convex
create-better-t-stack --examples todo --backend convex

# ❌ Invalid - Todo example without database and backend
create-better-t-stack --examples todo --backend none --database none

# ❌ Invalid - AI example with Elysia
create-better-t-stack --examples ai --backend elysia

# ❌ Invalid - AI example with Solid
create-better-t-stack --examples ai --frontend solid

Source: apps/web/content/docs/cli/compatibility.mdx, line 211-221

Common Error Messages

"Mongoose ORM requires MongoDB database"

Problem: Attempting to use Mongoose with a non-MongoDB database

Solution: Use MongoDB with Mongoose

# ❌ Invalid
create-better-t-stack --database postgres --orm mongoose

# ✅ Fix
create-better-t-stack --database mongodb --orm mongoose

Source: apps/web/content/docs/cli/compatibility.mdx, line 224-29

"Cloudflare Workers runtime is only supported with Hono backend"

Problem: Attempting to use Workers runtime with non-Hono backend

Solution: Use Hono with Workers

# ❌ Invalid
create-better-t-stack --runtime workers --backend express

# ✅ Fix
create-better-t-stack --runtime workers --backend hono

Source: apps/web/content/docs/cli/compatibility.mdx, line 231-36

"Cannot select multiple web frameworks"

Problem: Attempting to select multiple web frameworks

Solution: Choose one web framework

# ❌ Invalid
create-better-t-stack --frontend next tanstack-router

# ✅ Fix
create-better-t-stack --frontend tanstack-router

Source: apps/web/content/docs/cli/compatibility.mdx, line 238-43

"Polar payments requires Better Auth"

Problem: Attempting to use Polar payments without Better-Auth

Solution: Use Better-Auth with Polar payments

# ❌ Invalid
create-better-t-stack --payments polar --auth none

# ✅ Fix
create-better-t-stack --payments polar --auth better-auth

# Or use Clerk with Convex (no payments support)
create-better-t-stack --auth clerk --backend convex

Source: apps/web/content/docs/cli/compatibility.mdx, line 245-53

Validation Strategy

The CLI validates compatibility in this order:

1. Basic validation: Required parameters, valid enum values 2. Combination validation: Database + ORM, Backend + Runtime compatibility 3. Feature validation: Auth requirements, addon compatibility 4. Example validation: Example + stack compatibility

Source: apps/web/content/docs/cli/compatibility.mdx, line 256-63

Understanding these rules helps you create valid configurations and troubleshoot issues when the CLI reports compatibility errors.

Compatibility Matrices

Database × ORM Matrix

Backend × Runtime Matrix

Frontend × API Matrix

Database Setup × Database Matrix

Auth × Backend Matrix

Quick Reference

Default Stack (Recommended)

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

Serverless Edge Stack

create-better-t-stack my-app \
  --frontend tanstack-router \
  --backend hono \
  --runtime workers \
  --database sqlite \
  --orm drizzle \
  --db-setup d1 \
  --web-deploy alchemy \
  --server-deploy alchemy

Convex + Clerk Stack

create-better-t-stack my-app \
  --frontend tanstack-router \
  --backend convex \
  --auth clerk

Mobile + Web Stack

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

Better-T-Stack CLI Options Reference

Complete reference for all CLI flags and options.

Commands

create - Create New Project

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

Arguments

• project-directory (optional): Name or path for your project directory

Core Options

Frontend Options

Constraints:

• Only one web framework allowed
• Only one native framework allowed
• Can combine one web + one native (e.g., --frontend next native-uniwind)
• Astro: Not compatible with Convex backend or tRPC API

Backend Options

Constraints:

• Self (fullstack) backend only supports next, tanstack-start, nuxt, and astro frontends
• Convex backend not compatible with solid or astro frontend
• Workers runtime requires hono backend

Database Options

Constraints:

• Database and ORM must both be selected (both non-none)
• MongoDB requires Mongoose or Prisma (not Drizzle)
• Workers runtime only supports SQLite database

API Layer

Constraints:

• tRPC not supported with nuxt, svelte, solid, or astro frontends
• Use oRPC for those frontends

Authentication

Constraints:

• Clerk + Convex not compatible with nuxt, svelte, solid, or astro frontends

Payments

Constraints:

• Polar requires Better Auth and a web frontend

Addons

Frontend Restrictions:

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

Examples

Constraints:

• Todo example: Requires database unless using Convex or no backend
• AI example: Not compatible with solid or astro frontend

Runtime

Constraints:

• Workers only compatible with Hono backend
• Workers only supports Drizzle or Prisma ORM
• Workers only supports SQLite database
• Workers not compatible with MongoDB or Docker setup

Deployment

Constraints:

• web-deploy requires a web frontend
• server-deploy requires a backend

Directory Handling

add - Add to Existing Project

create-better-t-stack add [options]

Must be run in a project directory with bts.jsonc.

Options

Other Commands

builder - Open Stack Builder UI

create-better-t-stack builder

Opens https://better-t-stack.dev/new

docs - Open Documentation

create-better-t-stack docs

Opens https://better-t-stack.dev/docs

sponsors - Show Sponsors

create-better-t-stack sponsors

Displays project sponsors

history - Show Creation History

create-better-t-stack history

Shows project creation history

Global Options

These work with any command:

Default Configuration

When using --yes, the following defaults are applied:

{
  "frontend": ["tanstack-router"],
  "backend": "hono",
  "database": "sqlite",
  "orm": "drizzle",
  "auth": "better-auth",
  "payments": "none",
  "addons": ["turborepo"],
  "examples": [],
  "git": true,
  "install": true,
  "dbSetup": "none",
  "runtime": "bun",
  "api": "trpc",
  "webDeploy": "none",
  "serverDeploy": "none"
}

Complete Example Commands

Full-Stack App with All Options

npx create-better-t-stack@latest my-app \
  --frontend tanstack-router \
  --backend hono \
  --runtime bun \
  --database sqlite \
  --orm drizzle \
  --db-setup none \
  --auth better-auth \
  --payments none \
  --api trpc \
  --addons turborepo biome \
  --web-deploy none \
  --server-deploy none \
  --yes \
  --git \
  --install

Workers App

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

Mobile + Web App

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

Source References

• CLI implementation: apps/cli/src/
• Type definitions: apps/cli/src/types.ts
• Validation logic: apps/cli/src/utils/compatibility-rules.ts
• Constants: apps/cli/src/constants.ts