Regras de compatibilidade

Visão geral

A CLI valida combinações de opções para garantir que os projetos gerados funcionem corretamente. Aqui estão as principais regras e restrições de compatibilidade.

Compatibilidade de banco e ORM

Combinações obrigatórias

Restrições

• MongoDB + Drizzle: ❌ Não suportado — o Drizzle não suporta MongoDB
• Banco sem ORM: ❌ Não suportado — o banco exige um ORM para geração de código
• ORM sem banco: ❌ Não suportado — o ORM exige um banco de destino

# ❌ Invalid - MongoDB with Drizzle
kubojs --database mongodb --orm drizzle

# ✅ Valid - MongoDB with Mongoose
kubojs --database mongodb --orm mongoose

Compatibilidade de backend e runtime

Restrições do Cloudflare Workers

O Cloudflare Workers tem requisitos específicos de compatibilidade:

# ❌ Invalid - Workers with Express
kubojs --runtime workers --backend express

# ✅ Valid - Workers with Hono
kubojs --runtime workers --backend hono --database sqlite --orm drizzle --db-setup d1

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

Presets de backend

Backend Convex

Ao usar --backend convex, estas restrições se aplicam:

• --runtime none
• --database none (o Convex fornece o banco)
• --orm none (o Convex fornece a camada de dados)
• --api none (o Convex fornece a API)
• --db-setup none (o Convex gerencia a hospedagem)
• --server-deploy none
• Auth pode ser better-auth, clerk ou none conforme a compatibilidade do frontend

Nota: O Convex suporta autenticação Clerk com frontends compatíveis (frameworks React, Next.js, TanStack Start e frameworks native). Nuxt, Svelte, Solid e Astro não são compatíveis com Clerk.

Better Auth com Convex: frontends suportados são react-router, tanstack-router, tanstack-start, next, native-bare, native-uniwind e native-unistyles. Nuxt, Svelte, Solid e Astro não são suportados com Convex Better Auth.

Sem backend

Ao usar --backend none, as opções a seguir são definidas automaticamente:

• --auth none (sem backend para auth)
• --database none (sem backend para banco)
• --orm none (sem banco)
• --api none (sem backend para API)
• --runtime none (sem backend para rodar)
• --db-setup none (sem banco para hospedar)
• --examples none (exemplos exigem backend)

Compatibilidade de frontend e API

Suporte a frameworks de API

# ❌ Invalid - Nuxt with tRPC
kubojs --frontend nuxt --api trpc

# ✅ Valid - Nuxt with oRPC
kubojs --frontend nuxt --api orpc

Restrições de frontend

• Vários frontends web: ❌ Apenas um framework web permitido
• Vários frontends native: ❌ Apenas um framework native permitido
• Web + native: ✅ Um web e um native permitidos

# ❌ Invalid - Multiple web frontends
kubojs --frontend next tanstack-router

# ✅ Valid - Web + native
kubojs --frontend next native-uniwind

Compatibilidade de setup de banco

Requisitos por provider

Casos especiais

Cloudflare D1

• Exige --database sqlite
• Exige um destes alvos de deploy Cloudflare:
  • --backend hono --runtime workers --server-deploy cloudflare
  • --backend self --web-deploy cloudflare
• Com --backend self, D1 é suportado em next, tanstack-start, nuxt, svelte e astro
• Com --backend self, a compatibilidade de API do frontend ainda se aplica: nuxt, svelte e astro exigem --api orpc ou --api none

Setup Docker

• Não pode ser usado com sqlite (banco baseado em arquivo)
• Não pode ser usado com runtime workers (ambiente serverless)

Compatibilidade de addons

Suporte a PWA

• Exige frontend web
• Frontends compatíveis: tanstack-router, react-router, next, solid
• Não compatível com projetos só native

Tauri (apps desktop)

• Exige frontend web
• Frontends compatíveis: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, astro
• Builds desktop empacotam saída web estática, então tanstack-start, next, nuxt, svelte e astro precisam de configuração static/export antes do empacotamento
• Não compatível com --backend self, porque backends fullstack self emitem rotas de server dentro de apps/web
• Não pode ser combinado com frameworks native

Electrobun (apps desktop)

• Exige frontend web
• Frontends compatíveis: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, astro
• Usa um shell gerado em apps/desktop que carrega apps/web no desenvolvimento e empacota a saída de build estática para distribuição
• Builds desktop empacotam saída web estática, então tanstack-start, next, nuxt, svelte e astro precisam de configuração static/export antes do empacotamento
• Não compatível com --backend self, porque backends fullstack self emitem rotas de server dentro de apps/web

Task runners

• nx, turborepo e vite-plus são mutuamente exclusivos — só um pode ser selecionado por projeto

# ❌ Invalid - two task runners
kubojs --addons turborepo nx

# ✅ Valid - a single task runner
kubojs --addons turborepo

Deploy web

• --web-deploy cloudflare, --web-deploy docker e --web-deploy vercel exigem um frontend web
• Não podem ser usados com projetos só native

Deploy de server

• --server-deploy cloudflare exige --runtime workers com --backend hono
• --server-deploy docker e --server-deploy vercel exigem --runtime bun ou --runtime node
• --server-deploy não é usado com --backend self, porque backends fullstack fazem deploy junto com o app web

Requisitos de autenticação

Requisitos do Better-Auth

A autenticação Better-Auth exige:

• Um framework de backend (não pode ser none)
• Com banco: exige um ORM
• Sem banco: funciona com backend Convex ou configuração custom
• Com --backend convex: exige react-router, tanstack-router, tanstack-start, next ou um frontend native Expo

Requisitos do Clerk

A autenticação Clerk exige:

• Frontends compatíveis (frameworks React, Next.js, TanStack Start, frameworks native)
• Backends suportados: Convex, Hono, Express, Fastify e Elysia
• Suporte fullstack (--backend self) com Next.js ou TanStack Start
• Não compatível com Nuxt, Svelte, Solid ou Astro

Compatibilidade de exemplos

Exemplo Todo

• Exige um banco quando o backend está presente (exceto Convex)
• Exige uma camada de API (trpc ou orpc) para backends não-Convex
• Não pode ser usado com --backend none

Exemplo AI

• Não compatível com --frontend solid
• Não compatível com --frontend astro
• Com --backend convex, frontends Nuxt e Svelte não são suportados

Mensagens de erro comuns

"Mongoose ORM requires MongoDB database"

# Fix by using MongoDB
kubojs --database mongodb --orm mongoose

"Cloudflare Workers runtime is only supported with Hono backend"

# Fix by using Hono
kubojs --runtime workers --backend hono

"Cannot select multiple web frameworks"

# Fix by choosing one web framework
kubojs --frontend tanstack-router

Estratégia de validação

A CLI valida a compatibilidade nesta ordem:

1. Validação básica: parâmetros obrigatórios, valores de enum válidos
2. Validação de combinação: compatibilidade Database + ORM, Backend + Runtime
3. Validação de recursos: requisitos de auth, compatibilidade de addons
4. Validação de exemplos: compatibilidade de exemplo + stack

Entender essas regras ajuda a criar configurações válidas e a diagnosticar problemas quando a CLI reporta erros de compatibilidade.