diff --git a/apps/web/content/docs/bts-config.mdx b/apps/web/content/docs/bts-config.mdx index ab2c436..9b8e80b 100644 --- a/apps/web/content/docs/bts-config.mdx +++ b/apps/web/content/docs/bts-config.mdx @@ -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) diff --git a/apps/web/content/docs/cli/add.mdx b/apps/web/content/docs/cli/add.mdx deleted file mode 100644 index 388a897..0000000 --- a/apps/web/content/docs/cli/add.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: add -description: Add addons or deployment to an existing project ---- - -## Usage - - - - ```bash - bun create better-t-stack@latest add - ``` - - - ```bash - pnpm create better-t-stack@latest add - ``` - - - ```bash - npx create-better-t-stack@latest add - ``` - - - -## 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. - diff --git a/apps/web/content/docs/cli/builder.mdx b/apps/web/content/docs/cli/builder.mdx deleted file mode 100644 index 1d30afa..0000000 --- a/apps/web/content/docs/cli/builder.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: builder -description: Open the web-based stack builder ---- - -## Usage - - - - ```bash - bun create better-t-stack@latest builder - ``` - - - ```bash - pnpm create better-t-stack@latest builder - ``` - - - ```bash - npx create-better-t-stack@latest builder - ``` - - - -This command has no flags. diff --git a/apps/web/content/docs/cli/compatibility.mdx b/apps/web/content/docs/cli/compatibility.mdx new file mode 100644 index 0000000..b05811f --- /dev/null +++ b/apps/web/content/docs/cli/compatibility.mdx @@ -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. diff --git a/apps/web/content/docs/cli/docs.mdx b/apps/web/content/docs/cli/docs.mdx deleted file mode 100644 index 649e3e7..0000000 --- a/apps/web/content/docs/cli/docs.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: docs -description: Open the documentation ---- - -## Usage - - - - ```bash - bun create better-t-stack@latest docs - ``` - - - ```bash - pnpm create better-t-stack@latest docs - ``` - - - ```bash - npx create-better-t-stack@latest docs - ``` - - - -This command has no flags. diff --git a/apps/web/content/docs/cli/index.mdx b/apps/web/content/docs/cli/index.mdx index 94774e6..a25ce37 100644 --- a/apps/web/content/docs/cli/index.mdx +++ b/apps/web/content/docs/cli/index.mdx @@ -1,23 +1,149 @@ --- -title: CLI -description: Command reference index +title: Commands +description: Complete reference for all CLI commands --- - - - Create a new Better‑T‑Stack project (prompts or --yes) - - - Add addons or deployment to an existing project - - - Open the web-based Stack Builder - - - Open documentation - - - View project sponsors - - +## 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 `: `npm`, `pnpm`, `bun` +- `--install / --no-install`: Install dependencies after creation +- `--git / --no-git`: Initialize Git repository +- `--frontend `: Web and/or native frameworks (see [Options](/docs/cli/options#frontend)) +- `--backend `: `hono`, `express`, `fastify`, `elysia`, `next`, `convex`, `none` +- `--runtime `: `bun`, `node`, `workers` (`none` only with `--backend convex` or `--backend none`) +- `--database `: `none`, `sqlite`, `postgres`, `mysql`, `mongodb` +- `--orm `: `none`, `drizzle`, `prisma`, `mongoose` +- `--api `: `none`, `trpc`, `orpc` +- `--db-setup `: `none`, `turso`, `d1`, `neon`, `supabase`, `prisma-postgres`, `mongodb-atlas`, `docker` +- `--examples `: `none`, `todo`, `ai` +- `--web-deploy `: `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 `: Addons to add (see [Addons](/docs/cli/options#addons)) +- `--web-deploy `: Web deployment setup (`workers`, `none`) +- `--project-dir `: Project directory (defaults to current directory) +- `--install`: Install dependencies after adding +- `--package-manager `: 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 +``` diff --git a/apps/web/content/docs/cli/init.mdx b/apps/web/content/docs/cli/init.mdx deleted file mode 100644 index f094019..0000000 --- a/apps/web/content/docs/cli/init.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: init -description: Create a new Better-T-Stack project ---- - -## Usage - - - - ```bash - bun create better-t-stack@latest [project-directory] - ``` - - - ```bash - pnpm create better-t-stack@latest [project-directory] - ``` - - - ```bash - npx create-better-t-stack@latest [project-directory] - ``` - - - -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. - diff --git a/apps/web/content/docs/cli/meta.json b/apps/web/content/docs/cli/meta.json index fd5ecda..c979c61 100644 --- a/apps/web/content/docs/cli/meta.json +++ b/apps/web/content/docs/cli/meta.json @@ -1,5 +1,9 @@ { "title": "CLI", "defaultOpen": true, - "pages": ["index", "init", "add", "builder", "docs", "sponsors"] -} + "pages": [ + "index", + "options", + "compatibility" + ] +} \ No newline at end of file diff --git a/apps/web/content/docs/cli/options.mdx b/apps/web/content/docs/cli/options.mdx new file mode 100644 index 0000000..c6f3054 --- /dev/null +++ b/apps/web/content/docs/cli/options.mdx @@ -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 ` + +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 ` + +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 ` + +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 ` + +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 ` + +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 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 ` + +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 ` + +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 ` + +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 ` + +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 ` + +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 +``` diff --git a/apps/web/content/docs/cli/sponsors.mdx b/apps/web/content/docs/cli/sponsors.mdx deleted file mode 100644 index 4e8f802..0000000 --- a/apps/web/content/docs/cli/sponsors.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: sponsors -description: View project sponsors ---- - -## Usage - - - - ```bash - bun create better-t-stack@latest sponsors - ``` - - - ```bash - pnpm create better-t-stack@latest sponsors - ``` - - - ```bash - npx create-better-t-stack@latest sponsors - ``` - - - -This command has no flags. diff --git a/apps/web/content/docs/compatibility.mdx b/apps/web/content/docs/compatibility.mdx index 4eddcfe..60b5f9d 100644 --- a/apps/web/content/docs/compatibility.mdx +++ b/apps/web/content/docs/compatibility.mdx @@ -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 diff --git a/apps/web/content/docs/faq.mdx b/apps/web/content/docs/faq.mdx index 7b93952..524b926 100644 --- a/apps/web/content/docs/faq.mdx +++ b/apps/web/content/docs/faq.mdx @@ -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. diff --git a/apps/web/content/docs/guides/index.mdx b/apps/web/content/docs/guides/index.mdx new file mode 100644 index 0000000..70cc87c --- /dev/null +++ b/apps/web/content/docs/guides/index.mdx @@ -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 + + diff --git a/apps/web/content/docs/guides/meta.json b/apps/web/content/docs/guides/meta.json new file mode 100644 index 0000000..1937052 --- /dev/null +++ b/apps/web/content/docs/guides/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Guides", + "defaultOpen": true, + "pages": [ + "index" + ] +} \ No newline at end of file diff --git a/apps/web/content/docs/index.mdx b/apps/web/content/docs/index.mdx index 8131476..aaf0ae4 100644 --- a/apps/web/content/docs/index.mdx +++ b/apps/web/content/docs/index.mdx @@ -39,17 +39,17 @@ Skip prompts and use the default stack: ```bash - bun create better-t-stack@latest my-app --yes + bun create better-t-stack@latest --yes ``` ```bash - pnpm create better-t-stack@latest my-app --yes + pnpm create better-t-stack@latest --yes ``` ```bash - npx create-better-t-stack@latest my-app --yes + npx create-better-t-stack@latest --yes ``` @@ -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 diff --git a/apps/web/content/docs/meta.json b/apps/web/content/docs/meta.json index 0753258..656119f 100644 --- a/apps/web/content/docs/meta.json +++ b/apps/web/content/docs/meta.json @@ -2,6 +2,7 @@ "pages": [ "index", "cli", + "guides", "project-structure", "bts-config", "analytics", diff --git a/apps/web/content/docs/project-structure.mdx b/apps/web/content/docs/project-structure.mdx index 466dbc7..b1828b0 100644 --- a/apps/web/content/docs/project-structure.mdx +++ b/apps/web/content/docs/project-structure.mdx @@ -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. - - - - - - - - - - - - - - +## 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 - - - - - - - - - - - - - - - - +### 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": "", + "createdAt": "", + "database": "", + "orm": "", + "backend": "", + "runtime": "", + "frontend": [""] , + "addons": [""] , + "examples": [""] , + "auth": , + "packageManager": "", + "dbSetup": "", + "api": "", + "webDeploy": "" +} +``` + +### 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. \ No newline at end of file