Compatibility Rules

Overview

The CLI validates option combinations to ensure generated projects work correctly. Here are the key compatibility rules and restrictions.

Database & ORM Compatibility

Required Combinations

Restrictions

• MongoDB + Drizzle: ❌ Not supported - Drizzle doesn't support MongoDB
• Database without ORM: ❌ Not supported - Database requires an ORM for code generation
• ORM without Database: ❌ Not supported - ORM requires a database target

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

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

Backend & Runtime Compatibility

Cloudflare Workers Restrictions

Cloudflare Workers has specific compatibility requirements:

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

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

Backend Presets

Convex Backend

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

• --auth clerk (if compatible frontends selected, otherwise none)
• --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)
• --examples todo (Todo example works with Convex)

Note: Convex supports Clerk authentication with compatible frontends (React frameworks, Next.js, TanStack Start, and native frameworks). Nuxt, Svelte, and Solid are not compatible with Clerk.

No Backend

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

• --auth none (No backend for auth)
• --database none (No backend for database)
• --orm none (No database)
• --api none (No backend for API)
• --runtime none (No backend to run)
• --db-setup none (No database to host)
• --examples none (Examples require backend)

Frontend & API Compatibility

API Framework Support

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

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

Frontend Restrictions

• Multiple Web Frontends: ❌ Only one web framework allowed
• Multiple Native Frontends: ❌ Only one native framework allowed
• Web + Native: ✅ One web and one native framework allowed

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

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

Database Setup Compatibility

Provider Requirements

Special Cases

Cloudflare D1

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

Docker Setup

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

Addon Compatibility

PWA Support

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

Tauri (Desktop Apps)

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

Web Deployment

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

Authentication Requirements

Better-Auth Requirements

Better-Auth authentication requires:

• A backend framework (cannot be none)
• A database (cannot be none)
• An ORM (cannot be none)

Clerk Requirements

Clerk authentication requires:

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

# ❌ Invalid - Better-Auth without database
create-better-t-stack --auth better-auth --database none

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

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

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

Example Compatibility

Todo Example

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

AI Example

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

Common Error Messages

"Mongoose ORM requires MongoDB database"

# Fix by using MongoDB
create-better-t-stack --database mongodb --orm mongoose

"Cloudflare Workers runtime is only supported with Hono backend"

# Fix by using Hono
create-better-t-stack --runtime workers --backend hono

"Cannot select multiple web frameworks"

# Fix by choosing one web framework
create-better-t-stack --frontend tanstack-router

"Authentication requires a database"

# Fix by adding database for Better-Auth
create-better-t-stack --auth better-auth --database postgres --orm drizzle

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

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

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