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

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

Backend Presets

Convex Backend

When using --backend convex, these constraints apply:

• --runtime none
• --database none (Convex provides database)
• --orm none (Convex provides data layer)
• --api none (Convex provides API)
• --db-setup none (Convex manages hosting)
• --server-deploy none
• Auth can be better-auth, clerk, or none depending frontend compatibility

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

Better Auth with Convex: supported frontends are react-router, tanstack-router, tanstack-start, next, native-bare, native-uniwind, and native-unistyles. Nuxt, Svelte, Solid, and Astro are not supported with Convex Better Auth.

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-uniwind

Database Setup Compatibility

Provider Requirements

Special Cases

Cloudflare D1

• Requires --database sqlite
• Requires one of these Cloudflare deployment targets:
  • --backend hono --runtime workers --server-deploy cloudflare
  • --backend self --web-deploy cloudflare
• With --backend self, D1 is supported on next, tanstack-start, nuxt, and astro
• With --backend self, frontend API compatibility still applies: nuxt and astro require --api orpc or --api none

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, tanstack-start, next, nuxt, svelte, solid, astro
• Desktop builds package static web output, so tanstack-start, next, nuxt, svelte, and astro need static/export configuration before packaging
• Cannot be combined with native frameworks

Electrobun (Desktop Apps)

• Requires web frontend
• Compatible frontends: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, astro
• Uses a generated apps/desktop shell that loads apps/web during development and bundles its static build output for distribution
• Desktop builds package static web output, so tanstack-start, next, nuxt, svelte, and astro need static/export configuration before packaging

Web Deployment

• --web-deploy cloudflare 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)
• With database: Requires an ORM
• Without database: Works with Convex backend or custom configuration
• With --backend convex: requires react-router, tanstack-router, tanstack-start, next, or a native Expo frontend

Clerk Requirements

Clerk authentication requires:

• Compatible frontends (React frameworks, Next.js, TanStack Start, native frameworks)
• Supported backends: Convex, Hono, Express, Fastify, and Elysia
• Fullstack (--backend self) support with Next.js or TanStack Start
• Not compatible with Nuxt, Svelte, Solid, or Astro

Payments Requirements

Polar payments require:

• Better-Auth authentication
• A web frontend (or no frontend selected)

# ✅ Valid - 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 Hono
create-better-t-stack --auth clerk --backend hono --frontend tanstack-router

# ✅ Valid - Clerk with fullstack Next.js
create-better-t-stack --auth clerk --backend self --frontend next

# ❌ Invalid - Clerk with Astro
create-better-t-stack --auth clerk --backend self --frontend astro

Example Compatibility

Todo Example

• Requires a database when backend is present (except Convex)
• Requires an API layer (trpc or orpc) for non-Convex backends
• Cannot be used with --backend none

AI Example

• Not compatible with --frontend solid
• Not compatible with --frontend astro
• With --backend convex, Nuxt and Svelte frontends are not supported

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

"Polar payments requires Better Auth"

# Fix by using Better-Auth
create-better-t-stack --payments polar --auth better-auth

# Or use Clerk without Polar payments
create-better-t-stack --auth clerk --backend hono --frontend tanstack-router

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.