create-better-t-stack/apps/web/content/docs/cli/compatibility.mdx

---
title: Compatibility Rules
description: Understanding compatibility rules and restrictions between different CLI options
---

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

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

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

```bash
# ❌ 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:

| Component | Requirement | Reason |
|-----------|-------------|--------|
| Backend | Must be `hono` | Only Hono supports Workers runtime |
| ORM | Must be `drizzle` or `none` | Workers doesn't support Prisma/Mongoose |
| Database | Cannot be `mongodb` | MongoDB requires Prisma/Mongoose |
| Database Setup | Cannot be `docker` | Workers is serverless, no Docker support |

```bash
# ❌ 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

| Frontend | tRPC Support | oRPC Support | Notes |
|----------|-------------|-------------|-------|
| `tanstack-router` | ✅ | ✅ | Full support |
| `react-router` | ✅ | ✅ | Full support |
| `tanstack-start` | ✅ | ✅ | Full support |
| `next` | ✅ | ✅ | Full support |
| `nuxt` | ❌ | ✅ | tRPC not supported |
| `svelte` | ❌ | ✅ | tRPC not supported |
| `solid` | ❌ | ✅ | tRPC not supported |
| Native frameworks | ✅ | ✅ | Full support |

```bash
# ❌ 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

```bash
# ❌ 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

| Setup Provider | Required Database | Notes |
|---------------|------------------|-------|
| `turso` | `sqlite` | Distributed SQLite |
| `d1` | `sqlite` | Cloudflare D1 (requires Workers runtime) |
| `neon` | `postgres` | Serverless PostgreSQL |
| `supabase` | `postgres` | PostgreSQL with additional features |
| `prisma-postgres` | `postgres` | Managed PostgreSQL via Prisma |
| `mongodb-atlas` | `mongodb` | Managed MongoDB |
| `docker` | `postgres`, `mysql`, `mongodb` | Not compatible with `sqlite` or Workers |

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

```bash
# ❌ 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"
```bash
# Fix by using MongoDB
create-better-t-stack --database mongodb --orm mongoose
```

### "Cloudflare Workers runtime is only supported with Hono backend"
```bash
# Fix by using Hono
create-better-t-stack --runtime workers --backend hono
```

### "Cannot select multiple web frameworks"
```bash
# Fix by choosing one web framework
create-better-t-stack --frontend tanstack-router
```

### "Authentication requires a database"
```bash
# 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.