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

AWS Lambda Restrictions

The lambda runtime runs your server as an AWS Lambda function with a function URL:

# ❌ Invalid - Lambda with Express
create-better-t-stack --runtime lambda --backend express --server-deploy aws

# ✅ Valid - Lambda with Hono and an AWS server deployment
create-better-t-stack --runtime lambda --backend hono --server-deploy aws

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, svelte, solid, and astro
• With --backend self, frontend API compatibility still applies: nuxt, svelte, solid, 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)

AWS Aurora

• Requires --database postgres or --database mysql
• Requires an AWS deployment target for the database-owning app: --server-deploy aws, or --web-deploy aws with --backend self
• Cannot be used with workers or lambda runtime (the cluster is only reachable from its private VPC network)
• Alchemy does not run migrations for Aurora; apply them from inside the VPC with db:migrate:deploy

Addon Compatibility

PWA Support

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

The TanStack Router PWA caches its application shell for offline reloads. Solid, React Router, and Next.js register a service worker and show a cached offline page when a server-rendered page cannot be reached. Authenticated pages and API responses are not cached. Test installation and offline behavior against a production build served over HTTPS (or localhost), rather than relying on the development server.

Tauri (Desktop Apps)

• Requires web frontend
• Compatible frontends: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, astro
• Desktop builds package static web output, so tanstack-start, next, nuxt, svelte, and astro need static/export configuration before packaging
• Not compatible with --backend self, because fullstack self backends emit server routes inside apps/web
• Cannot be combined with native frameworks

Electrobun (Desktop Apps)

• Requires web frontend
• Compatible frontends: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, 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
• Not compatible with --backend self, because fullstack self backends emit server routes inside apps/web

Task Runners

• nx, turborepo, and vite-plus are mutually exclusive — only one can be selected per project

# ❌ Invalid - two task runners
create-better-t-stack --addons turborepo nx

# ✅ Valid - a single task runner
create-better-t-stack --addons turborepo

Linting and Formatting

• eslint (ESLint + Prettier) and vite-plus are mutually exclusive — Vite+ already provides linting and formatting
• oxlint, vite-plus, and biome are the preferred linting/formatting choices; eslint exists for compatibility

# ❌ Invalid - Vite+ already lints and formats
create-better-t-stack --addons eslint vite-plus

# ✅ Valid
create-better-t-stack --addons eslint

Web Deployment

• --web-deploy cloudflare, --web-deploy docker, and --web-deploy vercel require a web frontend
• --web-deploy aws requires a web frontend and supports Next.js, Nuxt, Astro, SvelteKit, Solid, TanStack Start, React Router, and TanStack Router
• Cannot be used with native-only projects

Server Deployment

• --server-deploy cloudflare requires --runtime workers with --backend hono
• --server-deploy aws requires --runtime bun, --runtime node, or --runtime lambda
• --runtime lambda also requires --backend hono and --server-deploy aws
• --server-deploy docker and --server-deploy vercel require --runtime bun or --runtime node
• --server-deploy is not used for --backend self, because fullstack backends deploy with the web app

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

# ✅ 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

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

# ✅ 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

Payments Requirements

All payments providers require Better-Auth authentication. Polar also supports the Convex backend and native-only stacks.

Stripe, Autumn, Dodo Payments, Creem, Chargebee, and Commet require:

• A non-Convex backend (--backend convex supports Polar only)
• A web frontend or no frontend (not available with native-only stacks)
• Autumn additionally requires a React web frontend (Next.js, TanStack Router, React Router, or TanStack Start)

Stripe, Dodo Payments, Creem, and Chargebee extend the Better Auth schema. After scaffolding, run bun run auth:generate, then apply the generated schema with your ORM's migration workflow.

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

# ✅ Valid - Stripe with a React web frontend
create-better-t-stack --payments stripe --auth better-auth --frontend tanstack-router --backend hono --database postgres --orm drizzle

# ✅ Valid - Commet with fullstack Next.js
create-better-t-stack --payments commet --auth better-auth --frontend next --backend self

# ❌ Invalid - other providers also require Better-Auth
create-better-t-stack --payments stripe --auth clerk --frontend next --backend self

# ❌ Invalid - only Polar supports the Convex backend
create-better-t-stack --payments autumn --auth better-auth --frontend next --backend convex

# ❌ Invalid - Autumn requires a React web frontend
create-better-t-stack --payments autumn --auth better-auth --frontend nuxt --backend self

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

"Stripe payments requires Better Auth"

The message names the selected provider; every payments provider requires Better-Auth.

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

# Or use Clerk without 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.