Compatibility Rules

Overview

The CLI validates option combinations to ensure generated projects work correctly. This page documents all compatibility rules, restrictions, and valid combinations.

Use --yolo to bypass these validations, but this may create non-functional configurations.

Database & ORM Compatibility

Compatibility Matrix

Database	Compatible ORMs	Notes
`sqlite`	`drizzle`, `prisma`	Lightweight, file-based database
`postgres`	`drizzle`, `prisma`	Advanced relational database
`mysql`	`drizzle`, `prisma`	Traditional relational database
`mongodb`	`mongoose`, `prisma`	Document database, requires specific ORMs
`none`	`none`	No database setup

Rules

Database Requires ORM

Rule: If you select a database, you must also select an ORM.

# ❌ Invalid - Database without ORM
create-better-t-stack --database postgres

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

Error message:

Database requires an ORM for code generation

MongoDB + Drizzle Not Supported

Rule: Drizzle ORM does not support MongoDB.

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

# ✅ Valid - Use Mongoose or Prisma
create-better-t-stack --database mongodb --orm mongoose
create-better-t-stack --database mongodb --orm prisma

Error message:

Drizzle ORM does not support MongoDB. Use Mongoose or Prisma instead.

Mongoose Requires MongoDB

Rule: Mongoose is a MongoDB-only ODM.

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

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

Error message:

Mongoose ORM requires MongoDB database

Backend & Runtime Compatibility

Cloudflare Workers Restrictions

Workers Requires Hono Backend

Rule: Cloudflare Workers runtime only works with Hono backend.

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

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

Error message:

Cloudflare Workers runtime is only supported with Hono backend

Workers + MongoDB Not Compatible

Rule: MongoDB is not compatible with Cloudflare Workers.

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

# ✅ Valid - Use SQLite with D1
create-better-t-stack --runtime workers --backend hono --database sqlite --orm drizzle --db-setup d1

Error message:

Cloudflare Workers runtime is not compatible with MongoDB database

Workers + Docker Not Compatible

Rule: Serverless Workers cannot use Docker.

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

# ✅ Valid
create-better-t-stack --runtime workers --backend hono --database sqlite --db-setup d1

Error message:

Cloudflare Workers runtime is not compatible with Docker setup

Backend Presets

Convex Backend Auto-Configuration

Rule: Convex backend automatically sets:

--runtime none
--database none
--orm none
--api none
--db-setup none
--server-deploy none

Convex provides its own database, API, and hosting.

# ✅ Valid - Convex with Clerk
create-better-t-stack --backend convex --auth clerk --frontend next

# ✅ Valid - Convex with Better-Auth
create-better-t-stack --backend convex --auth better-auth --frontend tanstack-router

Frontend restrictions with Convex:

Solid and Astro frontends are not compatible
With Clerk auth: Nuxt, Svelte, Solid, and Astro are not compatible

No Backend Auto-Configuration

Rule: --backend none automatically sets:

--auth none
--database none
--orm none
--api none
--runtime none
--db-setup none
--examples none

# ✅ Valid - Frontend-only app
create-better-t-stack --backend none --frontend tanstack-router

Self Backend (Fullstack)

Rule: --backend self only works with fullstack frontends:

next - Next.js
tanstack-start - TanStack Start
nuxt - Nuxt
astro - Astro

Uses the frontend’s built-in API routes (e.g., Next.js API routes, Nuxt server routes).

# ✅ Valid
create-better-t-stack --backend self --frontend next

# ❌ Invalid
create-better-t-stack --backend self --frontend tanstack-router

Error message:

Backend 'self' (fullstack) currently only supports Next.js, TanStack Start, Nuxt, and Astro frontends

Frontend & API Compatibility

API Framework Support

tRPC Framework Compatibility

Rule: tRPC is only compatible with React-based frontends and native frameworks.

Frontend	tRPC Support	oRPC Support
`tanstack-router`	✅	✅
`react-router`	✅	✅
`tanstack-start`	✅	✅
`next`	✅	✅
`nuxt`	❌	✅
`svelte`	❌	✅
`solid`	❌	✅
`astro`	❌	✅
Native frameworks	✅	✅

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

# ✅ Valid
create-better-t-stack --frontend nuxt --api orpc

Error message:

tRPC API is not supported with 'nuxt' frontend. Please use --api orpc or --api none

Frontend Restrictions

Only One Web Framework

Rule: You can only select one web framework.

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

# ✅ Valid - One web framework
create-better-t-stack --frontend next

# ✅ Valid - One web + one native
create-better-t-stack --frontend next native-uniwind

Error message:

Cannot select multiple web frameworks. Choose only one of: tanstack-router, tanstack-start, react-router, next, nuxt, svelte, solid

Only One Native Framework

Rule: You can only select one native framework.

# ❌ Invalid
create-better-t-stack --frontend native-bare native-uniwind

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

# ✅ Valid - One web + one native
create-better-t-stack --frontend tanstack-router native-uniwind

Error message:

Cannot select multiple native frameworks. Choose only one of: native-bare, native-uniwind, native-unistyles

Database Setup Compatibility

Provider Requirements

Setup Provider	Required Database	Additional Requirements
`turso`	`sqlite`	Works with Drizzle and Prisma
`d1`	`sqlite`	Requires `--runtime workers`
`neon`	`postgres`	-
`supabase`	`postgres`	-
`prisma-postgres`	`postgres`	-
`planetscale`	`mysql`, `postgres`	-
`mongodb-atlas`	`mongodb`	-
`docker`	`postgres`, `mysql`, `mongodb`	Cannot be used with `sqlite` or Workers

Cloudflare D1 Requirements

Rule: D1 requires:

--database sqlite
--runtime workers
--backend hono

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

Docker Setup Restrictions

Rule: Docker cannot be used with:

SQLite (file-based database)
Cloudflare Workers (serverless)

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

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

Authentication & Payments

Better-Auth Requirements

Rule: Better-Auth requires a backend framework (cannot be none).

# ❌ Invalid
create-better-t-stack --backend none --auth better-auth

# ✅ Valid
create-better-t-stack --backend hono --auth better-auth

Better-Auth can work with or without a database:

With database: Requires an ORM
Without database: Works with Convex or custom configuration

Clerk Requirements

Rule: Clerk authentication requires:

--backend convex
Compatible frontends (not Nuxt, Svelte, Solid, or Astro)

# ✅ Valid - Clerk with Convex
create-better-t-stack --auth clerk --backend convex --frontend next

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

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

Compatible frontends with Clerk:

React frameworks: TanStack Router, React Router, TanStack Start, Next.js
Native frameworks: All native frameworks

Polar Payments Requirements

Rule: Polar payments requires:

--auth better-auth
A web frontend (or no frontend selected)

# ✅ Valid
create-better-t-stack --auth better-auth --payments polar --frontend next

# ❌ Invalid - Requires Better-Auth
create-better-t-stack --auth clerk --payments polar

# ❌ Invalid - Native-only not supported
create-better-t-stack --auth better-auth --payments polar --frontend native-uniwind

Addon Compatibility

PWA Requirements

Rule: PWA requires a web frontend.Compatible frontends:

tanstack-router
react-router
next
solid

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

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

Tauri Requirements

Rule: Tauri requires a web frontend and cannot be combined with native frameworks.Compatible frontends:

tanstack-router
react-router
next
nuxt
svelte
solid

# ✅ Valid
create-better-t-stack --addons tauri --frontend next

# ❌ Invalid - Cannot combine with native
create-better-t-stack --addons tauri --frontend next native-uniwind

Examples Compatibility

Todo Example Requirements

Rule: Todo example requires:

A database (or Convex backend)
An API layer (or Convex backend)

# ✅ Valid - With database and API
create-better-t-stack \
  --examples todo \
  --database postgres \
  --orm drizzle \
  --api trpc

# ✅ Valid - With Convex
create-better-t-stack --examples todo --backend convex

# ❌ Invalid - No database
create-better-t-stack --examples todo --database none

# ❌ Invalid - No API
create-better-t-stack --examples todo --api none

AI Example Requirements

Rule: AI example is not compatible with:

solid frontend
astro frontend
With Convex backend: also incompatible with nuxt and svelte

# ✅ Valid
create-better-t-stack --examples ai --frontend next

# ❌ Invalid
create-better-t-stack --examples ai --frontend solid

# ❌ Invalid - Convex + Nuxt
create-better-t-stack --examples ai --backend convex --frontend nuxt

Deployment Compatibility

Web Deployment Requirements

Rule: Web deployment requires a web frontend.

# ✅ Valid
create-better-t-stack --web-deploy cloudflare --frontend next

# ❌ Invalid - Native-only
create-better-t-stack --web-deploy cloudflare --frontend native-uniwind

Server Deployment Requirements

Rule: Server deployment requires a backend (not none or convex).

# ✅ Valid
create-better-t-stack --server-deploy cloudflare --backend hono

# ❌ Invalid
create-better-t-stack --server-deploy cloudflare --backend none

Validation Strategy

The CLI validates in this order:

Schema validation - Valid enum values, correct types
Basic rules - Database requires ORM, etc.
Backend/Runtime - Workers + Hono, Self + fullstack frontend
Frontend/API - tRPC compatibility
Auth/Payments - Better-Auth/Clerk requirements
Addons - Frontend compatibility
Examples - Stack compatibility

Common Error Messages

❌ Drizzle ORM does not support MongoDB

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

Valid Configuration Examples

Full-Stack (Hono + Bun)
Cloudflare Workers
Convex + Clerk
Next.js Fullstack
Monorepo (Web + Native)

create-better-t-stack \
  --frontend tanstack-router \
  --backend hono \
  --runtime bun \
  --database postgres \
  --orm drizzle \
  --api trpc \
  --auth better-auth \
  --payments polar \
  --addons pwa biome \
  --examples todo ai \
  --db-setup neon

create-better-t-stack \
  --frontend next \
  --backend hono \
  --runtime workers \
  --database sqlite \
  --orm drizzle \
  --api orpc \
  --db-setup d1 \
  --web-deploy cloudflare \
  --server-deploy cloudflare

create-better-t-stack \
  --frontend next \
  --backend convex \
  --auth clerk \
  --addons pwa \
  --examples ai

create-better-t-stack \
  --frontend next \
  --backend self \
  --database postgres \
  --orm prisma \
  --auth better-auth \
  --db-setup supabase

create-better-t-stack \
  --frontend tanstack-router native-uniwind \
  --backend hono \
  --runtime node \
  --database mongodb \
  --orm mongoose \
  --api orpc \
  --addons turborepo

For the complete source code of compatibility rules, see:

~/workspace/source/apps/cli/src/utils/compatibility-rules.ts
~/workspace/source/apps/cli/src/validation.ts

Getting Started

CLI Reference

Configuration

Guides

Stack Options

Overview

Database & ORM Compatibility

Compatibility Matrix

Rules

Backend & Runtime Compatibility

Cloudflare Workers Restrictions

Backend Presets

Frontend & API Compatibility

API Framework Support

Frontend Restrictions

Database Setup Compatibility

Provider Requirements

Authentication & Payments

Addon Compatibility

Examples Compatibility

Deployment Compatibility

Validation Strategy

Common Error Messages

Valid Configuration Examples

Build docs developers (and LLMs) love

Getting Started

CLI Reference

Configuration

Guides

Stack Options

Documentation Index

​Overview

​Database & ORM Compatibility

​Compatibility Matrix

​Rules

​Backend & Runtime Compatibility

​Cloudflare Workers Restrictions

​Backend Presets

​Frontend & API Compatibility

​API Framework Support

​Frontend Restrictions

​Database Setup Compatibility

​Provider Requirements

​Authentication & Payments

​Addon Compatibility

​Examples Compatibility

​Deployment Compatibility

​Validation Strategy

​Common Error Messages

​Valid Configuration Examples

Build docs developers (and LLMs) love

Overview

Database & ORM Compatibility

Compatibility Matrix

Rules

Backend & Runtime Compatibility

Cloudflare Workers Restrictions

Backend Presets

Frontend & API Compatibility

API Framework Support

Frontend Restrictions

Database Setup Compatibility

Provider Requirements

Authentication & Payments

Addon Compatibility

Examples Compatibility

Deployment Compatibility

Validation Strategy

Common Error Messages

Valid Configuration Examples