mirror of
https://github.com/FranP-code/create-better-t-stack.git
synced 2025-10-12 23:52:15 +00:00
chore(web): improve docs
This commit is contained in:
Aman Varshney
219
apps/web/content/docs/cli/compatibility.mdx
Normal file
219
apps/web/content/docs/cli/compatibility.mdx
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
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 false` (Convex handles auth)
|
||||
- `--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)
|
||||
|
||||
#### No Backend
|
||||
When using `--backend none`, the following options are automatically set:
|
||||
|
||||
- `--auth false` (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`
|
||||
- Cannot be combined with native frameworks
|
||||
|
||||
### Web Deployment
|
||||
- `--web-deploy workers` requires a web frontend
|
||||
- Cannot be used with native-only projects
|
||||
|
||||
## Authentication Requirements
|
||||
|
||||
Authentication requires:
|
||||
- A backend framework (cannot be `none`)
|
||||
- A database (cannot be `none`)
|
||||
- An ORM (cannot be `none`)
|
||||
|
||||
```bash
|
||||
# ❌ Invalid - Auth without database
|
||||
create-better-t-stack --auth --database none
|
||||
|
||||
# ✅ Valid - Auth with full stack
|
||||
create-better-t-stack --auth --database postgres --orm drizzle --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
|
||||
create-better-t-stack --auth --database postgres --orm drizzle
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user