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
@@ -50,5 +50,5 @@ Notes:
|
||||
- Values mirror what you selected during project creation
|
||||
- The file may be updated when you run `add` (e.g., addons or webDeploy)
|
||||
|
||||
See also: [`add` command](/docs/cli/add)
|
||||
See also: [`add` command](/docs/cli#add)
|
||||
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
title: add
|
||||
description: Add addons or deployment to an existing project
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun create better-t-stack@latest add
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest add
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest add
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Flags
|
||||
|
||||
### Addons
|
||||
|
||||
- `--addons` Multiple values to add features
|
||||
- Values: `pwa`, `tauri`, `starlight`, `biome`, `husky`, `turborepo`, `fumadocs`, `ultracite`, `oxlint`, `none`
|
||||
- Do not combine `none` with other values
|
||||
|
||||
### Deployment
|
||||
|
||||
- `--web-deploy` One of: `workers`, `none`
|
||||
- Requires that the project includes a web frontend
|
||||
|
||||
### Project directory and install
|
||||
|
||||
- `--project-dir` Path to target project (default: current directory)
|
||||
- `--install` / `--no-install` Install dependencies after applying changes
|
||||
- `--package-manager` One of: `bun`, `pnpm`, `npm`
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Add PWA and Turborepo to the current project
|
||||
bun create better-t-stack@latest add --addons pwa turborepo --install
|
||||
```
|
||||
|
||||
```bash
|
||||
# Add Cloudflare Workers deployment
|
||||
bun create better-t-stack@latest add --web-deploy workers
|
||||
```
|
||||
|
||||
```bash
|
||||
# Operate on a specific project directory using bun
|
||||
bun create better-t-stack@latest add --project-dir ./apps/web --addons biome --package-manager bun
|
||||
```
|
||||
|
||||
## Compatibility notes
|
||||
|
||||
- Web deployment requires a web frontend to be present
|
||||
- Addons must be compatible with the selected frontend; the CLI validates this and fails with a clear error if incompatible
|
||||
|
||||
For general compatibility rules, see the main CLI reference.
|
||||
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: builder
|
||||
description: Open the web-based stack builder
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun create better-t-stack@latest builder
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest builder
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest builder
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
This command has no flags.
|
||||
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.
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: docs
|
||||
description: Open the documentation
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun create better-t-stack@latest docs
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest docs
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest docs
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
This command has no flags.
|
||||
@@ -1,23 +1,149 @@
|
||||
---
|
||||
title: CLI
|
||||
description: Command reference index
|
||||
title: Commands
|
||||
description: Complete reference for all CLI commands
|
||||
---
|
||||
|
||||
<Cards>
|
||||
<Card href="/docs/cli/init" title="init">
|
||||
Create a new Better‑T‑Stack project (prompts or --yes)
|
||||
</Card>
|
||||
<Card href="/docs/cli/add" title="add">
|
||||
Add addons or deployment to an existing project
|
||||
</Card>
|
||||
<Card href="/docs/cli/builder" title="builder">
|
||||
Open the web-based Stack Builder
|
||||
</Card>
|
||||
<Card href="/docs/cli/docs" title="docs">
|
||||
Open documentation
|
||||
</Card>
|
||||
<Card href="/docs/cli/sponsors" title="sponsors">
|
||||
View project sponsors
|
||||
</Card>
|
||||
</Cards>
|
||||
## Overview
|
||||
|
||||
The Better-T Stack CLI provides several commands to manage your TypeScript projects.
|
||||
|
||||
## `init` (Default Command)
|
||||
|
||||
Creates a new Better-T Stack project.
|
||||
|
||||
```bash
|
||||
create-better-t-stack [project-directory] [options]
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
- `project-directory` (optional): Name or path for your project directory
|
||||
|
||||
### Key Options
|
||||
|
||||
- `--yes, -y`: Use default configuration (skips prompts)
|
||||
- `--package-manager <pm>`: `npm`, `pnpm`, `bun`
|
||||
- `--install / --no-install`: Install dependencies after creation
|
||||
- `--git / --no-git`: Initialize Git repository
|
||||
- `--frontend <types...>`: Web and/or native frameworks (see [Options](/docs/cli/options#frontend))
|
||||
- `--backend <framework>`: `hono`, `express`, `fastify`, `elysia`, `next`, `convex`, `none`
|
||||
- `--runtime <runtime>`: `bun`, `node`, `workers` (`none` only with `--backend convex` or `--backend none`)
|
||||
- `--database <type>`: `none`, `sqlite`, `postgres`, `mysql`, `mongodb`
|
||||
- `--orm <type>`: `none`, `drizzle`, `prisma`, `mongoose`
|
||||
- `--api <type>`: `none`, `trpc`, `orpc`
|
||||
- `--db-setup <setup>`: `none`, `turso`, `d1`, `neon`, `supabase`, `prisma-postgres`, `mongodb-atlas`, `docker`
|
||||
- `--examples <types...>`: `none`, `todo`, `ai`
|
||||
- `--web-deploy <setup>`: `none`, `workers`
|
||||
|
||||
See the full reference in [Options](/docs/cli/options).
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Default setup with prompts
|
||||
create-better-t-stack
|
||||
|
||||
# Quick setup with defaults
|
||||
create-better-t-stack --yes
|
||||
|
||||
# Specific configuration
|
||||
create-better-t-stack --database postgres --backend hono --frontend tanstack-router
|
||||
```
|
||||
|
||||
## `add`
|
||||
|
||||
Adds addons or deployment configurations to an existing Better-T Stack project.
|
||||
|
||||
```bash
|
||||
create-better-t-stack add [options]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
- `--addons <types...>`: Addons to add (see [Addons](/docs/cli/options#addons))
|
||||
- `--web-deploy <setup>`: Web deployment setup (`workers`, `none`)
|
||||
- `--project-dir <path>`: Project directory (defaults to current directory)
|
||||
- `--install`: Install dependencies after adding
|
||||
- `--package-manager <pm>`: Package manager to use
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Add addons interactively
|
||||
create-better-t-stack add
|
||||
|
||||
# Add specific addons
|
||||
create-better-t-stack add --addons pwa tauri --install
|
||||
|
||||
# Add deployment setup
|
||||
create-better-t-stack add --web-deploy workers
|
||||
```
|
||||
|
||||
## `sponsors`
|
||||
|
||||
Displays Better-T Stack sponsors.
|
||||
|
||||
```bash
|
||||
create-better-t-stack sponsors
|
||||
```
|
||||
|
||||
Shows a list of project sponsors and supporters.
|
||||
|
||||
## `docs`
|
||||
|
||||
Opens the Better-T Stack documentation in your default browser.
|
||||
|
||||
```bash
|
||||
create-better-t-stack docs
|
||||
```
|
||||
|
||||
Opens `https://better-t-stack.dev/docs` in your browser.
|
||||
|
||||
## `builder`
|
||||
|
||||
Opens the web-based stack builder in your default browser.
|
||||
|
||||
```bash
|
||||
create-better-t-stack builder
|
||||
```
|
||||
|
||||
Opens `https://better-t-stack.dev/new` where you can configure your stack visually.
|
||||
|
||||
## Global Options
|
||||
|
||||
These options work with any command:
|
||||
|
||||
- `--help, -h`: Display help information
|
||||
- `--version, -V`: Display CLI version
|
||||
|
||||
## Command Examples
|
||||
|
||||
### Create a Full-Stack App
|
||||
|
||||
```bash
|
||||
create-better-t-stack \
|
||||
--database postgres \
|
||||
--orm drizzle \
|
||||
--backend hono \
|
||||
--frontend tanstack-router \
|
||||
--auth \
|
||||
--addons pwa biome
|
||||
```
|
||||
|
||||
### Create a Backend-Only Project
|
||||
|
||||
```bash
|
||||
create-better-t-stack api-server \
|
||||
--frontend none \
|
||||
--backend hono \
|
||||
--database postgres \
|
||||
--orm drizzle \
|
||||
--api trpc
|
||||
```
|
||||
|
||||
### Add Features to Existing Project
|
||||
|
||||
```bash
|
||||
cd my-existing-project
|
||||
create-better-t-stack add --addons tauri starlight --install
|
||||
```
|
||||
|
||||
@@ -1,151 +0,0 @@
|
||||
---
|
||||
title: init
|
||||
description: Create a new Better-T-Stack project
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun create better-t-stack@latest [project-directory]
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest [project-directory]
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest [project-directory]
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
You can pass `.` to use the current directory.
|
||||
|
||||
### Skip prompts
|
||||
|
||||
```bash
|
||||
bun create better-t-stack@latest my-app --yes
|
||||
```
|
||||
|
||||
## Flags Reference
|
||||
|
||||
### General
|
||||
|
||||
- `--yes, -y` Skip all prompts and use defaults
|
||||
- `--help, -h` Show help
|
||||
- `--version, -V` Show CLI version
|
||||
|
||||
### Frontend
|
||||
|
||||
- `--frontend` Choose one web frontend and optionally one native frontend
|
||||
- Web: `tanstack-router`, `react-router`, `tanstack-start`, `next`, `nuxt`, `svelte`, `solid`
|
||||
- Native: `native-nativewind`, `native-unistyles`
|
||||
- Special: `none`
|
||||
- Notes: At most one from each group; do not combine `none` with others
|
||||
|
||||
### Backend
|
||||
|
||||
- `--backend` One of: `hono`, `express`, `fastify`, `next`, `elysia`, `convex`, `none`
|
||||
|
||||
### Runtime
|
||||
|
||||
- `--runtime` One of: `bun`, `node`, `workers`, `none`
|
||||
- `workers` only with `--backend hono`
|
||||
- `none` only with `--backend convex` or `--backend none`
|
||||
|
||||
### Database
|
||||
|
||||
- `--database` One of: `sqlite`, `postgres`, `mysql`, `mongodb`, `none`
|
||||
|
||||
### ORM
|
||||
|
||||
- `--orm` One of: `drizzle`, `prisma`, `mongoose`, `none`
|
||||
- `mongoose` requires `--database mongodb`
|
||||
- `drizzle` is not compatible with `--database mongodb`
|
||||
|
||||
### API
|
||||
|
||||
- `--api` One of: `trpc`, `orpc`, `none`
|
||||
- Use `orpc` with `nuxt`, `svelte`, or `solid` (tRPC not supported there)
|
||||
|
||||
### Authentication
|
||||
|
||||
- `--auth` Enable auth
|
||||
- `--no-auth` Disable auth
|
||||
- Auth requires a non-`none` database
|
||||
|
||||
### Addons
|
||||
|
||||
- `--addons` Multiple values: `pwa`, `tauri`, `starlight`, `biome`, `husky`, `turborepo`, `fumadocs`, `ultracite`, `oxlint`, `none`
|
||||
- Do not combine `none` with other values
|
||||
|
||||
### Examples
|
||||
|
||||
- `--examples` Multiple values: `todo`, `ai`, `none`
|
||||
- Do not combine `none` with other values
|
||||
|
||||
### Database setup
|
||||
|
||||
- `--db-setup` One of: `turso`, `neon`, `prisma-postgres`, `mongodb-atlas`, `supabase`, `d1`, `docker`, `none`
|
||||
- `turso` → requires `--database sqlite`
|
||||
- `neon`, `prisma-postgres`, `supabase` → require `--database postgres`
|
||||
- `mongodb-atlas` → requires `--database mongodb`
|
||||
- `d1` → requires `--database sqlite` and `--runtime workers`
|
||||
- `docker` → not compatible with `--database sqlite` or `--runtime workers`
|
||||
|
||||
### Web deployment
|
||||
|
||||
- `--web-deploy` One of: `workers`, `none`
|
||||
- Requires selecting a web frontend
|
||||
|
||||
### Project setup
|
||||
|
||||
- `--git` / `--no-git` Initialize git repository
|
||||
- `--install` / `--no-install` Install dependencies
|
||||
- `--package-manager` One of: `bun`, `pnpm`, `npm`
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Full-stack web app
|
||||
bun create better-t-stack@latest my-webapp \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--runtime bun \
|
||||
--database postgres \
|
||||
--orm drizzle \
|
||||
--api trpc \
|
||||
--auth \
|
||||
--db-setup neon \
|
||||
--addons pwa turborepo \
|
||||
--examples todo
|
||||
```
|
||||
|
||||
```bash
|
||||
# Cloudflare Workers
|
||||
bun create better-t-stack@latest my-workers \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--runtime workers \
|
||||
--database sqlite \
|
||||
--orm drizzle \
|
||||
--db-setup d1 \
|
||||
--web-deploy workers
|
||||
```
|
||||
|
||||
## Compatibility notes
|
||||
|
||||
- Workers runtime only with `--backend hono` and `--orm drizzle` or `--orm none`
|
||||
- MongoDB requires `--orm mongoose` or `--orm prisma`
|
||||
- Convex backend forces: no auth, no db, no orm, no api, no runtime, no db-setup; Solid is not supported
|
||||
- Todo example requires a database when a non-Convex backend is selected
|
||||
- AI example is not compatible with `--backend elysia` or `--frontend solid`
|
||||
|
||||
The CLI validates incompatible combinations and fails fast with clear messages.
|
||||
|
||||
See also: Compatibility overview in the main CLI reference.
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
{
|
||||
"title": "CLI",
|
||||
"defaultOpen": true,
|
||||
"pages": ["index", "init", "add", "builder", "docs", "sponsors"]
|
||||
"pages": [
|
||||
"index",
|
||||
"options",
|
||||
"compatibility"
|
||||
]
|
||||
}
|
||||
253
apps/web/content/docs/cli/options.mdx
Normal file
253
apps/web/content/docs/cli/options.mdx
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: Options Reference
|
||||
description: Complete reference for all CLI options and flags
|
||||
---
|
||||
|
||||
## General Options
|
||||
|
||||
### `--yes, -y`
|
||||
|
||||
Use default configuration and skip interactive prompts.
|
||||
|
||||
```bash
|
||||
create-better-t-stack --yes
|
||||
```
|
||||
|
||||
### `--package-manager <pm>`
|
||||
|
||||
Choose package manager: `npm`, `pnpm`, or `bun`.
|
||||
|
||||
```bash
|
||||
create-better-t-stack --package-manager bun
|
||||
```
|
||||
|
||||
### `--install / --no-install`
|
||||
|
||||
Control dependency installation after project creation.
|
||||
|
||||
```bash
|
||||
create-better-t-stack --no-install
|
||||
```
|
||||
|
||||
### `--git / --no-git`
|
||||
|
||||
Control Git repository initialization.
|
||||
|
||||
```bash
|
||||
create-better-t-stack --no-git
|
||||
```
|
||||
|
||||
## Database Options
|
||||
|
||||
### `--database <type>`
|
||||
|
||||
Database type to use:
|
||||
|
||||
- `none`: No database
|
||||
- `sqlite`: SQLite database
|
||||
- `postgres`: PostgreSQL database
|
||||
- `mysql`: MySQL database
|
||||
- `mongodb`: MongoDB database
|
||||
|
||||
```bash
|
||||
create-better-t-stack --database postgres
|
||||
```
|
||||
|
||||
### `--orm <type>`
|
||||
|
||||
ORM to use with your database:
|
||||
|
||||
- `none`: No ORM
|
||||
- `drizzle`: Drizzle ORM (TypeScript-first)
|
||||
- `prisma`: Prisma ORM (feature-rich)
|
||||
- `mongoose`: Mongoose ODM (for MongoDB)
|
||||
|
||||
```bash
|
||||
create-better-t-stack --database postgres --orm drizzle
|
||||
```
|
||||
|
||||
### `--db-setup <setup>`
|
||||
|
||||
Database hosting/setup provider:
|
||||
|
||||
- `none`: Manual setup
|
||||
- `turso`: Turso (SQLite)
|
||||
- `d1`: Cloudflare D1 (SQLite)
|
||||
- `neon`: Neon (PostgreSQL)
|
||||
- `supabase`: Supabase (PostgreSQL)
|
||||
- `prisma-postgres`: Prisma Postgres via Prisma Accelerate
|
||||
- `mongodb-atlas`: MongoDB Atlas
|
||||
- `docker`: Local Docker containers
|
||||
|
||||
```bash
|
||||
create-better-t-stack --database postgres --db-setup neon
|
||||
```
|
||||
|
||||
## Backend Options
|
||||
|
||||
### `--backend <framework>`
|
||||
|
||||
Backend framework to use:
|
||||
|
||||
- `none`: No backend
|
||||
- `hono`: Hono (fast, lightweight)
|
||||
- `express`: Express.js (popular, mature)
|
||||
- `fastify`: Fastify (fast, plugin-based)
|
||||
- `elysia`: Elysia (Bun-native)
|
||||
- `next`: Next.js API routes
|
||||
- `convex`: Convex backend
|
||||
|
||||
```bash
|
||||
create-better-t-stack --backend hono
|
||||
```
|
||||
|
||||
### `--runtime <runtime>`
|
||||
|
||||
Runtime environment:
|
||||
|
||||
- `none`: No specific runtime (only with `convex` or `none` backend)
|
||||
- `bun`: Bun runtime
|
||||
- `node`: Node.js runtime
|
||||
- `workers`: Cloudflare Workers
|
||||
|
||||
```bash
|
||||
create-better-t-stack --backend hono --runtime bun
|
||||
```
|
||||
|
||||
### `--api <type>`
|
||||
|
||||
API layer type:
|
||||
|
||||
- `none`: No API layer
|
||||
- `trpc`: tRPC (type-safe)
|
||||
- `orpc`: oRPC (OpenAPI-compatible)
|
||||
|
||||
```bash
|
||||
create-better-t-stack --api trpc
|
||||
```
|
||||
|
||||
## Frontend Options
|
||||
|
||||
### `--frontend <types...>`
|
||||
|
||||
Frontend frameworks (can specify multiple):
|
||||
|
||||
**Web Frameworks:**
|
||||
- `tanstack-router`: React with TanStack Router
|
||||
- `react-router`: React with React Router
|
||||
- `tanstack-start`: React with TanStack Start (SSR)
|
||||
- `next`: Next.js
|
||||
- `nuxt`: Nuxt (Vue)
|
||||
- `svelte`: SvelteKit
|
||||
- `solid`: SolidJS
|
||||
|
||||
**Native Frameworks:**
|
||||
- `native-nativewind`: React Native with NativeWind
|
||||
- `native-unistyles`: React Native with Unistyles
|
||||
|
||||
**No Frontend:**
|
||||
- `none`: Backend-only project
|
||||
|
||||
```bash
|
||||
# Single web frontend
|
||||
create-better-t-stack --frontend tanstack-router
|
||||
|
||||
# Web + native frontend
|
||||
create-better-t-stack --frontend next native-nativewind
|
||||
|
||||
# Backend-only
|
||||
create-better-t-stack --frontend none
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### `--auth / --no-auth`
|
||||
|
||||
Include or exclude authentication setup using Better-Auth.
|
||||
|
||||
```bash
|
||||
create-better-t-stack --auth
|
||||
create-better-t-stack --no-auth
|
||||
```
|
||||
|
||||
## Addons
|
||||
|
||||
### `--addons <types...>`
|
||||
|
||||
Additional features to include:
|
||||
|
||||
- `none`: No addons
|
||||
- `pwa`: Progressive Web App support
|
||||
- `tauri`: Desktop app support
|
||||
- `starlight`: Starlight documentation site
|
||||
- `fumadocs`: Fumadocs documentation site
|
||||
- `biome`: Biome linting and formatting
|
||||
- `husky`: Git hooks with Husky
|
||||
- `turborepo`: Turborepo monorepo setup
|
||||
- `ultracite`: Ultracite configuration
|
||||
- `oxlint`: Oxlint fast linting
|
||||
- `vibe-rules`: Vibe Rules configuration
|
||||
|
||||
```bash
|
||||
create-better-t-stack --addons pwa biome husky
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### `--examples <types...>`
|
||||
|
||||
Example implementations to include:
|
||||
|
||||
- `none`: No examples
|
||||
- `todo`: Todo app example
|
||||
- `ai`: AI chat interface example
|
||||
|
||||
```bash
|
||||
create-better-t-stack --examples todo ai
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### `--web-deploy <setup>`
|
||||
|
||||
Web deployment configuration:
|
||||
|
||||
- `none`: No deployment setup
|
||||
- `workers`: Cloudflare Workers deployment
|
||||
|
||||
```bash
|
||||
create-better-t-stack --web-deploy workers
|
||||
```
|
||||
|
||||
## Option Validation
|
||||
|
||||
The CLI validates option combinations and will show errors for incompatible selections. See the [Compatibility](/docs/cli/compatibility) page for detailed rules.
|
||||
|
||||
## Examples
|
||||
|
||||
### Full Configuration
|
||||
|
||||
```bash
|
||||
create-better-t-stack \
|
||||
--database postgres \
|
||||
--orm drizzle \
|
||||
--backend hono \
|
||||
--runtime bun \
|
||||
--frontend tanstack-router \
|
||||
--api trpc \
|
||||
--auth \
|
||||
--addons pwa biome \
|
||||
--examples todo \
|
||||
--package-manager bun \
|
||||
--install
|
||||
```
|
||||
|
||||
### Minimal Setup
|
||||
|
||||
```bash
|
||||
create-better-t-stack \
|
||||
--backend none \
|
||||
--frontend tanstack-router \
|
||||
--addons none \
|
||||
--examples none
|
||||
```
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: sponsors
|
||||
description: View project sponsors
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun create better-t-stack@latest sponsors
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest sponsors
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest sponsors
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
This command has no flags.
|
||||
@@ -23,7 +23,7 @@ description: Valid and invalid combinations across frontend, backend, runtime, d
|
||||
## Framework Notes
|
||||
|
||||
- SvelteKit, Nuxt, and SolidJS frontends are only compatible with `orpc` API layer
|
||||
- PWA addon requires React (TanStack Router/React Router) or SolidJS
|
||||
- PWA addon requires a web frontend: TanStack Router, React Router, Next.js, or SolidJS
|
||||
- Tauri addon requires React (TanStack Router/React Router), Nuxt, SvelteKit, SolidJS, or Next.js
|
||||
- AI example is not compatible with Elysia backend or SolidJS frontend
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ No. Run the CLI directly with your package manager. See Quick Start and the per
|
||||
`npm`, `pnpm`, or `bun` (all supported).
|
||||
|
||||
### What Node.js version is required?
|
||||
Node.js 18+ (LTS recommended).
|
||||
Node.js 20+ (LTS recommended).
|
||||
|
||||
### Can I use this with an existing project?
|
||||
The CLI is for new projects. You can migrate gradually or use `add` to extend a Better‑T‑Stack project.
|
||||
|
||||
20
apps/web/content/docs/guides/index.mdx
Normal file
20
apps/web/content/docs/guides/index.mdx
Normal file
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Guides
|
||||
description: Practical guides for common setups
|
||||
---
|
||||
|
||||
## Guides
|
||||
|
||||
Curated, task-focused guides will be added here. Planned topics include:
|
||||
|
||||
- Workers + D1 setup with Hono and Drizzle
|
||||
- Adding PWA to React Router or Next.js
|
||||
- Using Prisma with Neon or Supabase
|
||||
- Monorepo tips with Turborepo
|
||||
|
||||
For now, see:
|
||||
- CLI reference: /docs/cli
|
||||
- Compatibility: /docs/compatibility
|
||||
- Project structure: /docs/project-structure
|
||||
|
||||
|
||||
7
apps/web/content/docs/guides/meta.json
Normal file
7
apps/web/content/docs/guides/meta.json
Normal file
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"title": "Guides",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index"
|
||||
]
|
||||
}
|
||||
@@ -39,17 +39,17 @@ Skip prompts and use the default stack:
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun create better-t-stack@latest my-app --yes
|
||||
bun create better-t-stack@latest --yes
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest my-app --yes
|
||||
pnpm create better-t-stack@latest --yes
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-app --yes
|
||||
npx create-better-t-stack@latest --yes
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@@ -255,6 +255,7 @@ See the full list in the [CLI Reference](/docs/cli). Key flags:
|
||||
- `--orm`: drizzle, prisma, mongoose, none
|
||||
- `--api`: trpc, orpc, none
|
||||
- `--addons`: turborepo, pwa, tauri, biome, husky, starlight, none
|
||||
- `--addons`: turborepo, pwa, tauri, biome, husky, starlight, fumadocs, ultracite, oxlint, vibe-rules, none
|
||||
- `--examples`: todo, ai, none
|
||||
|
||||
## Next Steps
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
"pages": [
|
||||
"index",
|
||||
"cli",
|
||||
"guides",
|
||||
"project-structure",
|
||||
"bts-config",
|
||||
"analytics",
|
||||
|
||||
@@ -1,60 +1,343 @@
|
||||
---
|
||||
title: Project Structure
|
||||
description: High-level overview of the generated monorepo layout
|
||||
description: Understanding the structure of projects created by Better-T Stack CLI
|
||||
---
|
||||
|
||||
import { File, Folder, Files } from 'fumadocs-ui/components/files';
|
||||
## Overview
|
||||
|
||||
### Server-based projects
|
||||
Better-T Stack CLI scaffolds a monorepo with `apps/*` and, when needed, `packages/*`. The exact structure depends on your choices (frontend, backend, API, database/ORM, auth, addons, runtime, deploy). This page mirrors what the CLI actually writes.
|
||||
|
||||
<Files>
|
||||
<Folder name="apps" defaultOpen>
|
||||
<Folder name="server" defaultOpen>
|
||||
<Folder name="src" />
|
||||
</Folder>
|
||||
<Folder name="web" defaultOpen disabled>
|
||||
<Folder name="src" />
|
||||
<Folder name="public" />
|
||||
</Folder>
|
||||
<Folder name="native" defaultOpen disabled>
|
||||
<Folder name="app" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
</Files>
|
||||
## Root layout
|
||||
|
||||
At the repository root you will see:
|
||||
|
||||
```
|
||||
/
|
||||
├── apps/ # Applications (web, server, native, docs)
|
||||
├── packages/ # Only when needed (e.g. Convex backend)
|
||||
├── package.json # Root package.json (scripts updated by CLI)
|
||||
├── bts.jsonc # Better‑T Stack configuration (always written)
|
||||
├── turbo.json # Only when addon "turborepo" is selected
|
||||
├── pnpm-workspace.yaml # Only when packageManager=pnpm
|
||||
├── bunfig.toml # Only when packageManager=bun
|
||||
├── .npmrc # pnpm + (native or nuxt) for alias resolution
|
||||
└── README.md # Generated quickstart
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `apps/server` is present for backends like `hono`, `express`, `fastify`, `elysia`, `next`.
|
||||
- `apps/web` and `apps/native` are optional; they appear only if you select a web or native frontend.
|
||||
- `bts.jsonc` lets the CLI detect and enhance your project later; keep it if you plan to use `bts add`.
|
||||
- `turbo.json` exists only if you picked the Turborepo addon.
|
||||
|
||||
### Convex-based projects
|
||||
## Monorepo structure by backend
|
||||
|
||||
<Files>
|
||||
<Folder name="apps" defaultOpen>
|
||||
<Folder name="web" defaultOpen disabled>
|
||||
<Folder name="src" />
|
||||
<Folder name="public" />
|
||||
</Folder>
|
||||
<Folder name="native" defaultOpen disabled>
|
||||
<Folder name="app" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
<Folder name="packages" defaultOpen>
|
||||
<Folder name="backend" defaultOpen>
|
||||
<Folder name="convex" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
</Files>
|
||||
### Non-Convex backends (hono, express, fastify, elysia, next)
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── apps/
|
||||
│ ├── web/ # Present if you picked a web framework
|
||||
│ ├── server/ # Backend API (framework depends on your choice)
|
||||
│ ├── native/ # Present if you picked React Native (Expo)
|
||||
│ └── docs/ # Present if you picked the Starlight/Fumadocs addon
|
||||
└── packages/ # May exist but not used by default
|
||||
```
|
||||
|
||||
### Convex backend
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── apps/
|
||||
│ ├── web/ # Present if you picked a web framework
|
||||
│ ├── native/ # Present if you picked React Native (Expo)
|
||||
│ └── docs/ # Present if you picked the Starlight/Fumadocs addon
|
||||
└── packages/
|
||||
└── backend/ # Convex functions, schema and config
|
||||
```
|
||||
|
||||
## Frontend Structure (apps/web)
|
||||
|
||||
The structure varies by framework. Items marked “(auth)” or “(API)” appear only when those options are enabled.
|
||||
|
||||
### React with TanStack Router
|
||||
|
||||
```
|
||||
apps/web/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ │ ├── ui/ # shadcn/ui primitives (from web base)
|
||||
│ │ ├── header.tsx
|
||||
│ │ ├── loader.tsx
|
||||
│ │ ├── mode-toggle.tsx
|
||||
│ │ └── theme-provider.tsx
|
||||
│ ├── routes/
|
||||
│ │ ├── __root.tsx # Root layout
|
||||
│ │ └── index.tsx # Home
|
||||
│ ├── lib/
|
||||
│ │ └── utils.ts
|
||||
│ ├── utils/
|
||||
│ │ └── trpc.ts (API=trpc) | orpc.ts (API=orpc)
|
||||
│ ├── main.tsx
|
||||
│ └── index.css
|
||||
├── index.html
|
||||
├── components.json # shadcn/ui config
|
||||
├── tsconfig.json
|
||||
├── vite.config.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Next.js
|
||||
|
||||
```
|
||||
apps/web/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── layout.tsx
|
||||
│ │ └── page.tsx
|
||||
│ └── components/
|
||||
│ ├── mode-toggle.tsx
|
||||
│ ├── providers.tsx
|
||||
│ └── theme-provider.tsx
|
||||
├── components.json
|
||||
├── next.config.ts
|
||||
├── postcss.config.mjs
|
||||
├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Convex replaces the server app; `packages/backend` is generated instead of `apps/server`.
|
||||
- Auth, DB/ORM, and API scaffolding are disabled for Convex presets.
|
||||
- If you choose `backend=next`, the backend is scaffolded separately in `apps/server`. The web app does not include API routes.
|
||||
- (auth) adds `src/app/login/*` and `src/app/dashboard/*` plus sign-in components.
|
||||
|
||||
### Where features land (high level)
|
||||
## Backend Structure (apps/server)
|
||||
|
||||
- API layer: merged into `apps/server` and `apps/web` when applicable.
|
||||
- Database & ORM: merged into `apps/server` when both are selected.
|
||||
- Authentication: merged into `apps/server`, `apps/web`, and `apps/native` when enabled and compatible.
|
||||
- Addons: PWA merges into `apps/web`; others merge at the appropriate location.
|
||||
- Web deployment (Workers): deployment files merge into `apps/web` per frontend.
|
||||
- Runtime extras (Workers): Workers-specific files added at the repo root.
|
||||
The server structure depends on your backend choice:
|
||||
|
||||
### Hono backend
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/
|
||||
│ ├── routers/
|
||||
│ │ └── index.ts # Base router
|
||||
│ └── index.ts # Hono app entry
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
### Express / Fastify / Elysia
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/
|
||||
│ └── index.ts # Framework entry
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
### Next (backend)
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ └── route.ts # App Router endpoint
|
||||
│ └── middleware.ts
|
||||
├── next.config.ts
|
||||
├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Workers runtime (optional)
|
||||
|
||||
When `runtime=workers`, you’ll also get:
|
||||
|
||||
```
|
||||
apps/server/
|
||||
└── wrangler.jsonc # Cloudflare Workers config (template)
|
||||
```
|
||||
|
||||
API and auth scaffolding (conditional):
|
||||
- API=trpc: `src/lib/trpc.ts`, `src/lib/context.ts`
|
||||
- API=orpc: `src/lib/orpc.ts`, `src/lib/context.ts`
|
||||
- Auth: `src/lib/auth.ts`
|
||||
|
||||
## Database Configuration
|
||||
|
||||
Added only when you selected a database and ORM:
|
||||
|
||||
### Drizzle ORM
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/db/
|
||||
│ └── index.ts # Database connection
|
||||
├── drizzle.config.ts # Drizzle configuration
|
||||
└── drizzle/ # Generated migrations (after you run commands)
|
||||
```
|
||||
|
||||
### Prisma ORM
|
||||
|
||||
```
|
||||
apps/server/
|
||||
└── prisma/
|
||||
├── schema.prisma # Database schema
|
||||
└── migrations/ # Generated after running Prisma commands
|
||||
```
|
||||
|
||||
### Mongoose (MongoDB)
|
||||
|
||||
```
|
||||
apps/server/
|
||||
└── src/db/
|
||||
└── index.ts # Mongoose connection
|
||||
```
|
||||
|
||||
### Auth + DB
|
||||
|
||||
If you selected auth, additional files are added for your ORM:
|
||||
- Drizzle: `src/db/schema/auth.ts`
|
||||
- Prisma: `prisma/schema/auth.prisma`
|
||||
- Mongoose: `src/db/models/auth.model.ts`
|
||||
|
||||
### Docker compose (optional)
|
||||
|
||||
If `dbSetup=docker`, a `docker-compose.yml` is added in `apps/server/` for your database.
|
||||
|
||||
## Native App Structure (apps/native)
|
||||
|
||||
Created only when you include React Native (NativeWind or Unistyles):
|
||||
|
||||
```
|
||||
apps/native/
|
||||
├── app/ # App screens
|
||||
│ ├── (tabs)/ # Tab navigation
|
||||
│ ├── _layout.tsx # Root layout
|
||||
│ └── index.tsx # Home screen
|
||||
├── components/ # React Native components
|
||||
├── lib/ # Utilities
|
||||
├── assets/ # Images, fonts
|
||||
├── app.json # Expo configuration
|
||||
├── package.json # Dependencies
|
||||
└── tsconfig.json # TypeScript config
|
||||
```
|
||||
|
||||
If an API is selected, a client utility is added:
|
||||
- API=trpc: `utils/trpc.ts`
|
||||
- API=orpc: `utils/orpc.ts`
|
||||
|
||||
## Documentation Structure (apps/docs)
|
||||
|
||||
When using Starlight or Fumadocs addon:
|
||||
|
||||
```
|
||||
apps/docs/
|
||||
├── src/
|
||||
│ ├── content/ # Documentation content
|
||||
│ │ └── docs/ # Doc pages
|
||||
│ └── pages/ # Astro pages (Starlight)
|
||||
├── astro.config.mjs # Astro config (Starlight)
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Better-T Stack Config (bts.jsonc)
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://r2.better-t-stack.dev/schema.json",
|
||||
"version": "<cli-version>",
|
||||
"createdAt": "<timestamp>",
|
||||
"database": "<none|sqlite|postgres|mysql|mongodb>",
|
||||
"orm": "<none|drizzle|prisma|mongoose>",
|
||||
"backend": "<none|hono|express|fastify|elysia|next|convex>",
|
||||
"runtime": "<bun|node|workers>",
|
||||
"frontend": ["<next|tanstack-router|react-router|tanstack-start|nuxt|svelte|solid>"] ,
|
||||
"addons": ["<turborepo|biome|husky|pwa|starlight>"] ,
|
||||
"examples": ["<ai|todo|none>"] ,
|
||||
"auth": <true|false>,
|
||||
"packageManager": "<bun|pnpm|npm>",
|
||||
"dbSetup": "<none|docker|d1>",
|
||||
"api": "<none|trpc|orpc>",
|
||||
"webDeploy": "<none|workers>"
|
||||
}
|
||||
```
|
||||
|
||||
### Turborepo Config (turbo.json)
|
||||
|
||||
Generated only if you chose the Turborepo addon.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://turbo.build/schema.json",
|
||||
"tasks": {
|
||||
"build": {
|
||||
"dependsOn": ["^build"],
|
||||
"outputs": ["dist/**", ".next/**"]
|
||||
},
|
||||
"dev": {
|
||||
"cache": false,
|
||||
"persistent": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Shared packages
|
||||
|
||||
By default, no shared packages are created. You will see `packages/backend` only when using the Convex backend. You can add more packages manually as your repo grows.
|
||||
|
||||
```
|
||||
packages/
|
||||
└── backend/ # Only with Convex backend
|
||||
```
|
||||
|
||||
## Development Scripts
|
||||
|
||||
Scripts are adjusted based on your package manager and whether the Turborepo addon is selected.
|
||||
|
||||
With Turborepo:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "turbo dev",
|
||||
"build": "turbo build",
|
||||
"check-types": "turbo check-types",
|
||||
"dev:web": "turbo -F web dev",
|
||||
"dev:server": "turbo -F server dev",
|
||||
"db:push": "turbo -F server db:push",
|
||||
"db:studio": "turbo -F server db:studio"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Without Turborepo (example for Bun):
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "bun run --filter '*' dev",
|
||||
"build": "bun run --filter '*' build",
|
||||
"check-types": "bun run --filter '*' check-types",
|
||||
"dev:web": "bun run --filter web dev",
|
||||
"dev:server": "bun run --filter server dev"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Convex adds `dev:setup` for initial backend configuration.
|
||||
|
||||
## Key Details
|
||||
|
||||
- **Monorepo**: `apps/*` always; `packages/*` only when needed (Convex)
|
||||
- **React web base**: shadcn/ui primitives, `components.json`, common utilities
|
||||
- **API clients**: `src/utils/trpc.ts` or `src/utils/orpc.ts` added to web/native when selected
|
||||
- **Auth**: Adds `src/lib/auth.ts` on the server and login/dashboard pages on the web app
|
||||
- **ORM/DB**: Drizzle/Prisma/Mongoose files added only when selected
|
||||
- **Extras**: `pnpm-workspace.yaml`, `bunfig.toml`, or `.npmrc` added based on package manager and choices
|
||||
- **Deploy**: Workers deploy adds `wrangler.jsonc` templates to the appropriate app(s)
|
||||
|
||||
This reflects the actual files written by the CLI so new projects match what’s documented here.
|
||||
Reference in New Issue
Block a user