mirror of
https://github.com/FranP-code/create-better-t-stack.git
synced 2025-10-12 23:52:15 +00:00
feat(web): improve docs and refactor cli (#476)
This commit is contained in:
Aman Varshney
55
apps/web/content/docs/analytics.mdx
Normal file
55
apps/web/content/docs/analytics.mdx
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Analytics & Telemetry
|
||||
description: What we collect, how to disable it, and where to view aggregated insights
|
||||
---
|
||||
|
||||
## What is collected
|
||||
|
||||
On successful project creation, the CLI sends a single event (`project_created`) with:
|
||||
|
||||
- Selected options (stack choices): `frontend`, `backend`, `runtime`, `database`, `orm`, `api`, `auth`, `addons`, `examples`, `dbSetup`, `webDeploy`, `packageManager`
|
||||
- Environment data: `cli_version`, `node_version`, `platform`
|
||||
- A random session id: `distinct_id` like `cli_<random>`
|
||||
- IP removed: `$ip: null`
|
||||
|
||||
Not collected:
|
||||
|
||||
- Project name, path, or file contents (explicitly omitted)
|
||||
- Secrets or environment variables from your machine
|
||||
|
||||
|
||||
|
||||
## Disable telemetry
|
||||
|
||||
Telemetry is enabled by default. To disable:
|
||||
|
||||
```bash
|
||||
# Disable for a single run
|
||||
BTS_TELEMETRY_DISABLED=1 bun create better-t-stack@latest
|
||||
```
|
||||
|
||||
Add `export BTS_TELEMETRY_DISABLED=1` to your shell profile to make it permanent.
|
||||
|
||||
## Where to view analytics
|
||||
|
||||
- Charts: [`/analytics`](/analytics)
|
||||
- Raw JSON snapshot: `https://r2.amanv.dev/analytics-data.json`
|
||||
- CSV export: `https://r2.amanv.dev/export.csv`
|
||||
|
||||
Notes:
|
||||
|
||||
- Aggregates are periodically regenerated from incoming events
|
||||
- Raw data is not publicly exposed; the `/analytics` page presents only summary statistics
|
||||
|
||||
## Full transparency
|
||||
|
||||
Single event per scaffold; randomized id; no IP or project identifiers. See source code below.
|
||||
|
||||
If in doubt, set `BTS_TELEMETRY_DISABLED=1` and proceed. You can still use all CLI features.
|
||||
|
||||
## Source code
|
||||
|
||||
- CLI event sender: [`apps/cli/src/utils/analytics.ts`](https://github.com/AmanVarshney01/create-better-t-stack/blob/main/apps/cli/src/utils/analytics.ts)
|
||||
- Telemetry toggle logic: [`apps/cli/src/utils/telemetry.ts`](https://github.com/AmanVarshney01/create-better-t-stack/blob/main/apps/cli/src/utils/telemetry.ts)
|
||||
- Aggregation script (builds the charts data): [`apps/web/scripts/generate-analytics.ts`](https://github.com/AmanVarshney01/create-better-t-stack/blob/main/apps/web/scripts/generate-analytics.ts)
|
||||
|
||||
54
apps/web/content/docs/bts-config.mdx
Normal file
54
apps/web/content/docs/bts-config.mdx
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: bts.jsonc
|
||||
description: What bts.jsonc does and why it matters
|
||||
---
|
||||
|
||||
## What is it?
|
||||
|
||||
`bts.jsonc` is a small config file written to your project root when you create a project. It captures the stack choices you selected (frontend, backend, API, DB/ORM, auth, addons, etc.). The file uses JSONC (JSON with comments) and includes a schema for editor hints.
|
||||
|
||||
Where: `./bts.jsonc`
|
||||
|
||||
## Why it exists
|
||||
|
||||
- Required for the `add` command to detect your current stack
|
||||
- Helps validate compatibility and pre‑fill sensible defaults
|
||||
|
||||
If `bts.jsonc` is missing, the `add` command cannot run because the project cannot be detected.
|
||||
|
||||
## Safe to delete (with a caveat)
|
||||
|
||||
It’s safe to delete for normal development; the generated code in `apps/*` and `packages/*` remains the source of truth. However, if you plan to use the `add` command later, you must keep `bts.jsonc` (or recreate it) so the CLI can detect your project.
|
||||
|
||||
## Format
|
||||
|
||||
The file is JSONC with comments enabled and includes a `$schema` URL for tooling.
|
||||
|
||||
```jsonc
|
||||
// Better-T-Stack configuration file
|
||||
// safe to delete
|
||||
{
|
||||
"$schema": "https://r2.better-t-stack.dev/schema.json",
|
||||
"version": "x.y.z",
|
||||
"createdAt": "2025-01-01T00:00:00.000Z",
|
||||
"frontend": ["tanstack-router"],
|
||||
"backend": "hono",
|
||||
"runtime": "bun",
|
||||
"database": "sqlite",
|
||||
"orm": "drizzle",
|
||||
"api": "trpc",
|
||||
"auth": true,
|
||||
"addons": ["turborepo"],
|
||||
"examples": [],
|
||||
"dbSetup": "none",
|
||||
"webDeploy": "none",
|
||||
"packageManager": "bun"
|
||||
}
|
||||
```
|
||||
|
||||
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)
|
||||
|
||||
@@ -3,6 +3,32 @@ title: CLI Commands
|
||||
description: Complete reference for all Better-T-Stack CLI commands and options
|
||||
---
|
||||
|
||||
## Quick Usage
|
||||
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
# Interactive setup
|
||||
bun create better-t-stack@latest
|
||||
|
||||
# With project name
|
||||
bun create better-t-stack@latest my-project
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest
|
||||
pnpm create better-t-stack@latest my-project
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest
|
||||
npx create-better-t-stack@latest my-project
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Commands Overview
|
||||
|
||||
| Command | Description |
|
||||
@@ -21,19 +47,39 @@ The primary command for creating new Better-T-Stack projects.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Interactive setup
|
||||
npx create-better-t-stack@latest
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
# Interactive setup
|
||||
bun create better-t-stack@latest
|
||||
|
||||
# With project name
|
||||
npx create-better-t-stack@latest my-project
|
||||
# With project name
|
||||
bun create better-t-stack@latest my-project
|
||||
|
||||
# With specific directory
|
||||
npx create-better-t-stack@latest ./path/to/project
|
||||
# With specific directory
|
||||
bun create better-t-stack@latest ./path/to/project
|
||||
|
||||
# Use current directory
|
||||
npx create-better-t-stack@latest .
|
||||
```
|
||||
# Use current directory
|
||||
bun create better-t-stack@latest .
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest
|
||||
pnpm create better-t-stack@latest my-project
|
||||
pnpm create better-t-stack@latest ./path/to/project
|
||||
pnpm create better-t-stack@latest .
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest
|
||||
npx create-better-t-stack@latest my-project
|
||||
npx create-better-t-stack@latest ./path/to/project
|
||||
npx create-better-t-stack@latest .
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Flags Reference
|
||||
|
||||
@@ -71,13 +117,13 @@ npx create-better-t-stack@latest .
|
||||
# Web + Mobile
|
||||
--frontend tanstack-router native-nativewind
|
||||
|
||||
# Multiple frontends
|
||||
--frontend next solid
|
||||
|
||||
# No frontend (API-only)
|
||||
--frontend none
|
||||
```
|
||||
|
||||
Note: Select at most one web frontend (one of: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid) and at most one native frontend (one of: native-nativewind, native-unistyles).
|
||||
Do not combine `none` with other frontend values.
|
||||
|
||||
#### Backend Options
|
||||
|
||||
| Flag | Values | Default | Description |
|
||||
@@ -200,8 +246,13 @@ npx create-better-t-stack@latest .
|
||||
- `biome` - Biome linter/formatter
|
||||
- `husky` - Git hooks with Husky
|
||||
- `starlight` - Documentation site
|
||||
- `fumadocs` - Fumadocs docs site
|
||||
- `ultracite` - Markdown/MDX processing
|
||||
- `oxlint` - Fast linter
|
||||
- `none` - No addons
|
||||
|
||||
Note: Do not combine `none` with other addon values.
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
--addons turborepo pwa
|
||||
@@ -227,6 +278,8 @@ npx create-better-t-stack@latest .
|
||||
--examples none
|
||||
```
|
||||
|
||||
Note: Do not combine `none` with other example values.
|
||||
|
||||
#### Database Setup Options
|
||||
|
||||
| Flag | Values | Default | Description |
|
||||
@@ -295,19 +348,39 @@ Add addons or deployment configurations to existing Better-T-Stack projects.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Interactive addon selection
|
||||
npx create-better-t-stack@latest add
|
||||
<Tabs items={['bun', 'pnpm', 'npm']}>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
# Interactive addon selection
|
||||
bun create better-t-stack@latest add
|
||||
|
||||
# Add specific addons
|
||||
npx create-better-t-stack@latest add --addons pwa tauri
|
||||
# Add specific addons
|
||||
bun create better-t-stack@latest add --addons pwa tauri
|
||||
|
||||
# Add deployment
|
||||
npx create-better-t-stack@latest add --web-deploy workers
|
||||
# Add deployment
|
||||
bun create better-t-stack@latest add --web-deploy workers
|
||||
|
||||
# Add both
|
||||
npx create-better-t-stack@latest add --addons biome --web-deploy workers
|
||||
```
|
||||
# Add both
|
||||
bun create better-t-stack@latest add --addons biome --web-deploy workers
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest add
|
||||
pnpm create better-t-stack@latest add --addons pwa tauri
|
||||
pnpm create better-t-stack@latest add --web-deploy workers
|
||||
pnpm create better-t-stack@latest add --addons biome --web-deploy workers
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest add
|
||||
npx create-better-t-stack@latest add --addons pwa tauri
|
||||
npx create-better-t-stack@latest add --web-deploy workers
|
||||
npx create-better-t-stack@latest add --addons biome --web-deploy workers
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Flags
|
||||
|
||||
@@ -341,9 +414,23 @@ Display Better-T-Stack project sponsors.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest sponsors
|
||||
```
|
||||
<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>
|
||||
|
||||
Shows a list of project sponsors with their GitHub profiles and websites.
|
||||
|
||||
@@ -355,9 +442,23 @@ Open Better-T-Stack documentation in your default browser.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest docs
|
||||
```
|
||||
<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>
|
||||
|
||||
Opens: https://better-t-stack.dev/docs
|
||||
|
||||
@@ -369,9 +470,23 @@ Open the web-based interactive stack builder.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest builder
|
||||
```
|
||||
<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>
|
||||
|
||||
Opens: https://better-t-stack.dev/new
|
||||
|
||||
@@ -384,7 +499,7 @@ The web builder provides a visual interface for configuring your stack and gener
|
||||
### Full-Stack Web Application
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-webapp \
|
||||
bun create better-t-stack@latest my-webapp \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--runtime bun \
|
||||
@@ -400,7 +515,7 @@ npx create-better-t-stack@latest my-webapp \
|
||||
### Mobile + Web Application
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-mobile-app \
|
||||
bun create better-t-stack@latest my-mobile-app \
|
||||
--frontend tanstack-router native-nativewind \
|
||||
--backend hono \
|
||||
--database sqlite \
|
||||
@@ -413,7 +528,7 @@ npx create-better-t-stack@latest my-mobile-app \
|
||||
### Cloudflare Workers Project
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-workers-app \
|
||||
bun create better-t-stack@latest my-workers-app \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--runtime workers \
|
||||
@@ -426,7 +541,7 @@ npx create-better-t-stack@latest my-workers-app \
|
||||
### API-Only Project
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-api \
|
||||
bun create better-t-stack@latest my-api \
|
||||
--frontend none \
|
||||
--backend fastify \
|
||||
--runtime node \
|
||||
@@ -440,10 +555,10 @@ npx create-better-t-stack@latest my-api \
|
||||
|
||||
```bash
|
||||
# Use all defaults with immediate setup
|
||||
npx create-better-t-stack@latest my-project --yes
|
||||
bun create better-t-stack@latest my-project --yes
|
||||
|
||||
# Convex full-stack (automatically configures compatible options)
|
||||
npx create-better-t-stack@latest my-convex-app --backend convex
|
||||
bun create better-t-stack@latest my-convex-app --backend convex
|
||||
```
|
||||
|
||||
---
|
||||
@@ -452,11 +567,29 @@ npx create-better-t-stack@latest my-convex-app --backend convex
|
||||
|
||||
Some options have compatibility requirements:
|
||||
|
||||
- **Cloudflare Workers**: Only with `--backend hono`, `--orm drizzle`, `--runtime workers`
|
||||
- **Cloudflare Workers**: Only with `--backend hono`, `--orm drizzle` or `--orm none`, `--runtime workers`
|
||||
- **MongoDB**: Requires `--orm mongoose` or `--orm prisma`
|
||||
- **Convex**: Incompatible with custom database/ORM/API options
|
||||
- **Convex**: Forces `--no-auth`, `--database none`, `--orm none`, `--api none`, `--runtime none`, `--db-setup none`; sets `--examples todo`; Solid frontend is not supported with Convex
|
||||
- **PWA**: Requires compatible web frontend
|
||||
- **Tauri**: Requires compatible web frontend
|
||||
- **AI Examples**: Not compatible with `--backend elysia` or `--frontend solid`
|
||||
- **tRPC + Nuxt/Svelte/Solid**: Use `--api orpc` (tRPC is not supported with `nuxt`, `svelte`, or `solid`)
|
||||
- **Todo Example**: Requires a database when a backend (other than Convex) is selected
|
||||
- **Web Deploy**: `--web-deploy workers` requires selecting a web frontend
|
||||
- **Examples with `--api none`**: Cannot select examples when `--api none` (unless `--backend convex`)
|
||||
- **Runtime `none`**: Only allowed with `--backend convex` or `--backend none`
|
||||
- **Mongoose ORM**: Requires `--database mongodb`
|
||||
- **Drizzle ORM**: Not compatible with `--database mongodb`
|
||||
- **Database requires ORM**: Selecting a database requires a non-`none` ORM
|
||||
- **ORM requires database**: Selecting a non-`none` ORM requires a database
|
||||
- **Auth requires database**: `--auth` requires a non-`none` database
|
||||
- **DB Setup constraints**:
|
||||
- `--db-setup turso` → requires `--database sqlite`
|
||||
- `--db-setup neon` → requires `--database postgres`
|
||||
- `--db-setup prisma-postgres` → requires `--database postgres`
|
||||
- `--db-setup mongodb-atlas` → requires `--database mongodb`
|
||||
- `--db-setup supabase` → requires `--database postgres`
|
||||
- `--db-setup d1` → requires `--database sqlite` and `--runtime workers`
|
||||
- `--db-setup docker` → not compatible with `--database sqlite` or `--runtime workers`
|
||||
|
||||
The CLI will validate compatibility and show helpful error messages for invalid combinations.
|
||||
|
||||
35
apps/web/content/docs/cli/add.mdx
Normal file
35
apps/web/content/docs/cli/add.mdx
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
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 [options]
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm create better-t-stack@latest add [options]
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npx create-better-t-stack@latest add [options]
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Options
|
||||
|
||||
- `--addons` Multiple values
|
||||
- `--web-deploy` One of: `workers`, `none`
|
||||
- `--project-dir` Path
|
||||
- `--install` / `--no-install`
|
||||
- `--package-manager` One of: `bun`, `pnpm`, `npm`
|
||||
|
||||
See also: [Compatibility](/docs/compatibility)
|
||||
|
||||
25
apps/web/content/docs/cli/builder.mdx
Normal file
25
apps/web/content/docs/cli/builder.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
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>
|
||||
|
||||
25
apps/web/content/docs/cli/docs.mdx
Normal file
25
apps/web/content/docs/cli/docs.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
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>
|
||||
|
||||
23
apps/web/content/docs/cli/index.mdx
Normal file
23
apps/web/content/docs/cli/index.mdx
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: CLI
|
||||
description: Command reference index
|
||||
---
|
||||
|
||||
<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>
|
||||
|
||||
35
apps/web/content/docs/cli/init.mdx
Normal file
35
apps/web/content/docs/cli/init.mdx
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
See also: [Compatibility](/docs/compatibility)
|
||||
|
||||
5
apps/web/content/docs/cli/meta.json
Normal file
5
apps/web/content/docs/cli/meta.json
Normal file
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "CLI",
|
||||
"defaultOpen": true,
|
||||
"pages": ["index", "init", "add", "builder", "docs", "sponsors"]
|
||||
}
|
||||
25
apps/web/content/docs/cli/sponsors.mdx
Normal file
25
apps/web/content/docs/cli/sponsors.mdx
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
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>
|
||||
|
||||
29
apps/web/content/docs/compatibility.mdx
Normal file
29
apps/web/content/docs/compatibility.mdx
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Compatibility
|
||||
description: Valid and invalid combinations across frontend, backend, runtime, database, and addons
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
- **Convex backend**: Disables authentication, database, ORM, and API options
|
||||
- **Backend `none`**: Forces API, ORM, database, authentication, and runtime to `none`; disables examples
|
||||
- **Frontend `none`**: Backend-only project; PWA/Tauri/examples may be disabled
|
||||
- **API `none`**: No tRPC/oRPC setup; use framework-native APIs
|
||||
- **Database `none`**: Disables ORM and authentication
|
||||
- **ORM `none`**: No ORM setup; manage DB manually
|
||||
- **Runtime `none`**: Only with Convex backend or when backend is `none`
|
||||
|
||||
## Cloudflare Workers
|
||||
|
||||
- Backend: `hono` only
|
||||
- Database: `sqlite` with Cloudflare D1
|
||||
- ORM: `drizzle` (or none)
|
||||
- Not compatible with MongoDB
|
||||
|
||||
## Framework Notes
|
||||
|
||||
- SvelteKit, Nuxt, and SolidJS frontends are only compatible with `orpc` API layer
|
||||
- PWA addon requires React (TanStack Router/React Router) 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
|
||||
|
||||
94
apps/web/content/docs/contributing.mdx
Normal file
94
apps/web/content/docs/contributing.mdx
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: Contributing
|
||||
description: How to set up your environment and contribute changes
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This project is a monorepo with two main apps:
|
||||
|
||||
- CLI: `apps/cli`
|
||||
- Documentation site: `apps/web`
|
||||
|
||||
> Note: Planning to add a new feature? Please open an issue first to confirm it aligns with the project's future goals. We don't want you to spend time on work that might not land.
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- Bun (recommended)
|
||||
- Git
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/AmanVarshney01/create-better-t-stack.git
|
||||
cd create-better-t-stack
|
||||
bun install
|
||||
```
|
||||
|
||||
## Develop the CLI
|
||||
|
||||
```bash
|
||||
cd apps/cli
|
||||
# optional global link for testing anywhere
|
||||
bun link
|
||||
# run in watch mode
|
||||
bun dev:cli
|
||||
```
|
||||
|
||||
## Develop the Docs
|
||||
|
||||
```bash
|
||||
# from repo root
|
||||
bun dev:web
|
||||
```
|
||||
|
||||
## Contribution Flow
|
||||
|
||||
1. Open an issue/discussion before starting major work
|
||||
2. Create a feature branch
|
||||
3. Make changes following existing code style
|
||||
4. Update docs as needed
|
||||
5. Test and format
|
||||
|
||||
```bash
|
||||
# CLI
|
||||
cd apps/cli && bun dev:cli
|
||||
|
||||
# Web
|
||||
bun dev:web
|
||||
|
||||
# Format
|
||||
bun run format
|
||||
|
||||
# Type checks
|
||||
bun check
|
||||
```
|
||||
|
||||
6. (CLI changes) Add a changeset
|
||||
|
||||
```bash
|
||||
bunx changeset select create-better-t-stack
|
||||
# Choose 'patch' for small fixes, 'minor' for features
|
||||
# Never choose 'major'
|
||||
```
|
||||
|
||||
7. Commit and push
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat(web): ..." # or fix(cli): ...
|
||||
git push origin <your-branch>
|
||||
```
|
||||
|
||||
8. Open a Pull Request and link any related issues
|
||||
|
||||
## Help
|
||||
|
||||
- Issues and Discussions on GitHub
|
||||
- Discord: https://discord.gg/ZYsbjpDaM5
|
||||
|
||||
See full contributor guide in the repository: `.github/CONTRIBUTING.md`.
|
||||
|
||||
@@ -1,334 +1,46 @@
|
||||
---
|
||||
title: Frequently Asked Questions
|
||||
description: Common questions and answers about Better-T-Stack CLI
|
||||
description: Short answers to common beginner questions
|
||||
---
|
||||
|
||||
## General Questions
|
||||
## General
|
||||
|
||||
### What is Better-T-Stack?
|
||||
### What is Better‑T‑Stack?
|
||||
An opinionated CLI that scaffolds full‑stack TypeScript projects (frontend, backend, API, DB/ORM, auth, addons) with a clean monorepo. See the Quick Start on the docs home.
|
||||
|
||||
Better-T-Stack is a modern CLI tool that helps you scaffold end-to-end type-safe TypeScript projects. It provides opinionated, production-ready configurations for full-stack applications with support for multiple frontend frameworks, backend frameworks, databases, and deployment options.
|
||||
### Do I need to install anything globally?
|
||||
No. Run the CLI directly with your package manager. See Quick Start and the per‑command pages under CLI.
|
||||
|
||||
### How is Better-T-Stack different from other scaffolding tools?
|
||||
### Which package manager can I use?
|
||||
`npm`, `pnpm`, or `bun` (all supported).
|
||||
|
||||
- **End-to-End Type Safety**: TypeScript across your entire stack with proper type sharing
|
||||
- **Modern Stack Focus**: Latest versions of popular frameworks and tools
|
||||
- **Production Ready**: Configurations used in real production applications
|
||||
- **Highly Customizable**: Mix and match technologies based on your needs
|
||||
- **Monorepo Structure**: Organized project structure with shared packages
|
||||
- **Database Integration**: Built-in database setup and ORM configuration
|
||||
- **Authentication**: Integrated auth with Better-Auth
|
||||
- **Multi-Platform**: Web, mobile, and desktop app support in one project
|
||||
### What Node.js version is required?
|
||||
Node.js 18+ (LTS recommended).
|
||||
|
||||
### Is Better-T-Stack free to use?
|
||||
### 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.
|
||||
|
||||
Yes, Better-T-Stack is completely free and open-source under the MIT license. You can use it for personal and commercial projects without any restrictions.
|
||||
### Where do generated files live?
|
||||
See Project Structure for high‑level layouts (server‑based vs. Convex, optional web/native).
|
||||
|
||||
### Do I need to know all these technologies to use Better-T-Stack?
|
||||
## Choosing options
|
||||
|
||||
No! Better-T-Stack is designed to help you learn modern full-stack development. Each generated project includes:
|
||||
- Comprehensive README with setup instructions
|
||||
- Example code and patterns
|
||||
- TypeScript for better developer experience
|
||||
- Best practices and folder structure
|
||||
### Does the CLI recommend a stack?
|
||||
No. Pick what fits your needs. The CLI validates compatibility. See CLI (per command) and Compatibility for rules.
|
||||
|
||||
---
|
||||
### I’m unsure between tRPC and oRPC / Drizzle and Prisma
|
||||
See Compatibility for guidance and constraints. Both pairs work well; choose based on team and hosting needs.
|
||||
|
||||
## Installation & Setup
|
||||
## Common issues
|
||||
|
||||
### Which package manager should I use?
|
||||
|
||||
You can use any of the major package managers:
|
||||
- **npm**: Most widely supported, comes with Node.js
|
||||
- **pnpm**: Faster installs, better disk space efficiency
|
||||
- **bun**: All-in-one runtime, extremely fast
|
||||
|
||||
For monorepo projects, we recommend **pnpm** for its excellent workspace support.
|
||||
|
||||
### Do I need to install the CLI globally?
|
||||
|
||||
No, you can use npx to run the latest version without installation:
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-project
|
||||
```
|
||||
|
||||
This ensures you always use the latest version with the newest features and bug fixes.
|
||||
|
||||
### What Node.js version do I need?
|
||||
|
||||
Better-T-Stack requires **Node.js 18 or higher**. We recommend using the latest LTS version for the best experience.
|
||||
|
||||
### Can I use Better-T-Stack with existing projects?
|
||||
|
||||
Better-T-Stack is designed for new projects. For existing projects, you can:
|
||||
1. Create a new Better-T-Stack project
|
||||
2. Gradually migrate your code
|
||||
3. Use the `add` command to add specific features to existing Better-T-Stack projects
|
||||
|
||||
---
|
||||
|
||||
## Configuration & Stack Choices
|
||||
|
||||
### Can I change my stack choices after creating a project?
|
||||
|
||||
Some changes are possible:
|
||||
- **Easy**: Add addons, examples, or deployment configurations using the `add` command
|
||||
- **Medium**: Switch between compatible ORMs or databases (requires manual migration)
|
||||
- **Hard**: Change frontend/backend frameworks (requires significant refactoring)
|
||||
|
||||
It's best to plan your stack carefully during initial setup.
|
||||
|
||||
### What's the difference between tRPC and oRPC?
|
||||
|
||||
- **tRPC**: End-to-end type safety with TypeScript inference, great for TypeScript-only projects
|
||||
- **oRPC**: OpenAPI-compatible type-safe APIs, better for teams using multiple languages or requiring OpenAPI specs
|
||||
|
||||
Both provide excellent type safety, choose based on your team's needs.
|
||||
|
||||
### Should I use Drizzle or Prisma?
|
||||
|
||||
- **Drizzle**: TypeScript-first, lightweight, great for edge deployments, SQL-like syntax
|
||||
- **Prisma**: Feature-rich, mature ecosystem, great tooling, GraphQL-like schema
|
||||
|
||||
Choose Drizzle for modern TypeScript projects and Prisma for feature-rich applications.
|
||||
|
||||
### What's the recommended stack for beginners?
|
||||
|
||||
For beginners, we recommend:
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-first-project \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--database sqlite \
|
||||
--orm drizzle \
|
||||
--auth \
|
||||
--addons turborepo biome
|
||||
```
|
||||
|
||||
This provides a simple but powerful full-stack setup that's easy to understand and deploy.
|
||||
|
||||
---
|
||||
|
||||
## Compatibility Questions
|
||||
|
||||
### Can I use MongoDB with Drizzle?
|
||||
|
||||
No, Drizzle doesn't support MongoDB. For MongoDB, use:
|
||||
- **Prisma ORM**: Full ORM support for MongoDB
|
||||
- **Mongoose**: Traditional MongoDB object modeling
|
||||
|
||||
### Why can't I use tRPC with Nuxt/SvelteKit/SolidJS?
|
||||
|
||||
tRPC is primarily designed for React ecosystems. For these frameworks, use:
|
||||
- **oRPC**: Provides similar type safety with broader framework support
|
||||
- **None**: Use the framework's built-in API capabilities
|
||||
|
||||
### Can I use Cloudflare Workers with any backend?
|
||||
|
||||
Cloudflare Workers runtime only supports:
|
||||
- **Backend**: Hono only
|
||||
- **Database**: SQLite with Cloudflare D1
|
||||
- **ORM**: Drizzle only
|
||||
|
||||
This is due to the serverless nature and limitations of the Workers environment.
|
||||
|
||||
### Which addons work with which frontends?
|
||||
|
||||
| Addon | Compatible Frontends |
|
||||
|-------|---------------------|
|
||||
| PWA | TanStack Router, React Router, SolidJS, Next.js |
|
||||
| Tauri | TanStack Router, React Router, Nuxt, SvelteKit, SolidJS, Next.js |
|
||||
| Turborepo | All frontends |
|
||||
| Biome | All frontends |
|
||||
| Husky | All frontends |
|
||||
| Starlight | All frontends |
|
||||
|
||||
---
|
||||
|
||||
## Database & Hosting
|
||||
|
||||
### What database should I choose for production?
|
||||
|
||||
**For small to medium applications:**
|
||||
- **SQLite + Turso**: Excellent performance, easy scaling
|
||||
- **PostgreSQL + Neon**: Serverless PostgreSQL, great for startups
|
||||
|
||||
**For large applications:**
|
||||
- **PostgreSQL + Supabase**: Full backend-as-a-service
|
||||
- **MongoDB + Atlas**: NoSQL flexibility with managed hosting
|
||||
|
||||
### Do I need Docker for development?
|
||||
|
||||
Docker is optional and only required for:
|
||||
- **Database Setup**: If you choose `--db-setup docker`
|
||||
- **Local Development**: Some setups like Supabase local development
|
||||
|
||||
Many database options (Turso, Neon, MongoDB Atlas) don't require Docker.
|
||||
|
||||
### How do I deploy my Better-T-Stack application?
|
||||
|
||||
Better-T-Stack projects are configured for easy deployment:
|
||||
|
||||
**Frontend:**
|
||||
- **Vercel**: Zero-config deployment for Next.js, React apps
|
||||
- **Netlify**: Static site deployment
|
||||
- **Cloudflare Workers**: Edge deployment with `--web-deploy workers`
|
||||
|
||||
**Backend:**
|
||||
- **Railway**: Easy backend deployment
|
||||
- **Fly.io**: Global application deployment
|
||||
- **Cloudflare Workers**: Serverless edge deployment
|
||||
|
||||
---
|
||||
|
||||
## Development & Troubleshooting
|
||||
|
||||
### My project won't start after creation. What should I do?
|
||||
|
||||
1. **Check Node.js version**: Ensure you're using Node.js 18+
|
||||
2. **Install dependencies**: Run `npm install` in the project directory
|
||||
3. **Check environment variables**: Copy `.env.example` to `.env` and fill in values
|
||||
4. **Database setup**: Run database migrations if using a database
|
||||
5. **Check the README**: Each project includes detailed setup instructions
|
||||
|
||||
### I'm getting TypeScript errors. How do I fix them?
|
||||
|
||||
1. **Install dependencies**: Ensure all packages are installed
|
||||
2. **Restart TypeScript server**: In VS Code, use Ctrl/Cmd + Shift + P → "TypeScript: Restart TS Server"
|
||||
3. **Check imports**: Ensure all imports are correct and packages are installed
|
||||
4. **Update types**: Run `npm run check-types` to see detailed errors
|
||||
|
||||
### How do I update dependencies in my project?
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
npx taze -r
|
||||
|
||||
# Update all dependencies
|
||||
npm update
|
||||
|
||||
# Or with other package managers
|
||||
pnpm update
|
||||
bun update
|
||||
```
|
||||
|
||||
### Can I use Better-T-Stack with VS Code?
|
||||
|
||||
Yes! Better-T-Stack projects work excellently with VS Code. We recommend these extensions:
|
||||
- TypeScript and JavaScript Language Features (built-in)
|
||||
- Tailwind CSS IntelliSense
|
||||
- Prisma or Drizzle Kit extensions
|
||||
- ESLint (if using Biome addon)
|
||||
|
||||
### My mobile app won't connect to the backend. What's wrong?
|
||||
|
||||
This is a common issue with Expo and local development:
|
||||
|
||||
1. **Check environment variables**: Update `EXPO_PUBLIC_SERVER_URL` in `apps/native/.env`
|
||||
2. **Use your local IP**: Replace `localhost` with your computer's IP address
|
||||
3. **Check firewall**: Ensure your firewall allows connections on port 3000
|
||||
4. **Use tunnel**: Consider using `npx expo start --tunnel`
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Can I customize the generated templates?
|
||||
|
||||
Currently, Better-T-Stack doesn't support custom templates, but you can:
|
||||
1. Fork the repository and modify templates
|
||||
2. Create a feature request for specific customizations
|
||||
3. Modify the generated project after creation
|
||||
|
||||
### How do I contribute to Better-T-Stack?
|
||||
|
||||
We welcome contributions! Here's how to get started:
|
||||
|
||||
1. **Fork the repository** on GitHub
|
||||
2. **Clone your fork** locally
|
||||
3. **Install dependencies**: `pnpm install`
|
||||
4. **Make your changes** and test them
|
||||
5. **Submit a pull request** with a clear description
|
||||
|
||||
### Can I use Better-T-Stack in my company/team?
|
||||
|
||||
Absolutely! Better-T-Stack is perfect for:
|
||||
- **Standardizing project structure** across teams
|
||||
- **Onboarding new developers** with consistent setup
|
||||
- **Rapid prototyping** and MVP development
|
||||
- **Client projects** with proven, production-ready configurations
|
||||
### My mobile app can’t connect to the backend (Expo)
|
||||
Set `EXPO_PUBLIC_SERVER_URL` in `apps/native/.env` to your machine IP (not `localhost`), check firewall, or try `npx expo start --tunnel`.
|
||||
|
||||
### How do I disable telemetry?
|
||||
Set `BTS_TELEMETRY_DISABLED=1` (shell env). For one run, prefix the command; to make it permanent, export it in your shell profile.
|
||||
|
||||
Better-T-Stack collects anonymous usage data to improve the tool. To disable:
|
||||
## Getting help
|
||||
|
||||
```bash
|
||||
# Disable for single run
|
||||
BTS_TELEMETRY_DISABLED=1 npx create-better-t-stack@latest my-app
|
||||
|
||||
# Disable globally
|
||||
export BTS_TELEMETRY_DISABLED=1
|
||||
```
|
||||
|
||||
Add the export to your shell profile (`.bashrc`, `.zshrc`, etc.) to make it permanent.
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Where can I get help?
|
||||
|
||||
- **Documentation**: Comprehensive guides at [better-t-stack.dev/docs](https://better-t-stack.dev/docs)
|
||||
- **GitHub Issues**: Report bugs or request features
|
||||
- **GitHub Discussions**: Community support and questions
|
||||
- **Discord/Twitter**: Follow for updates and community discussion
|
||||
|
||||
### How do I report a bug?
|
||||
|
||||
1. **Search existing issues** to avoid duplicates
|
||||
2. **Create a new issue** with:
|
||||
- Clear description of the problem
|
||||
- Steps to reproduce
|
||||
- Your system information (OS, Node.js version, etc.)
|
||||
- Generated project configuration
|
||||
- Error messages or screenshots
|
||||
|
||||
### How do I request a new feature?
|
||||
|
||||
1. **Check existing feature requests** in GitHub Issues
|
||||
2. **Create a new issue** with the "feature request" label
|
||||
3. **Describe the feature** and its use case
|
||||
4. **Explain why** it would benefit the community
|
||||
|
||||
### Is there a community?
|
||||
|
||||
Yes! You can connect with other Better-T-Stack users:
|
||||
- **GitHub Discussions**: Ask questions and share projects
|
||||
- **Twitter**: Follow [@AmanVarshney01](https://twitter.com/AmanVarshney01) for updates
|
||||
- **Show your projects**: Tag us when you build something with Better-T-Stack!
|
||||
|
||||
---
|
||||
|
||||
## Sponsorship & Support
|
||||
|
||||
### How can I support Better-T-Stack?
|
||||
|
||||
- **⭐ Star the repository** on GitHub
|
||||
- **🐛 Report bugs** and suggest improvements
|
||||
- **💰 Sponsor the project** on GitHub Sponsors
|
||||
- **📢 Share with others** who might find it useful
|
||||
- **🤝 Contribute code** or documentation
|
||||
|
||||
### Who sponsors Better-T-Stack?
|
||||
|
||||
View current sponsors by running:
|
||||
```bash
|
||||
npx create-better-t-stack@latest sponsors
|
||||
```
|
||||
|
||||
Or visit: [github.com/sponsors/AmanVarshney01](https://github.com/sponsors/AmanVarshney01)
|
||||
|
||||
---
|
||||
|
||||
*Still have questions? Feel free to ask in [GitHub Discussions](https://github.com/AmanVarshney01/create-better-t-stack/discussions) or check our [documentation](https://better-t-stack.dev/docs).*
|
||||
- Docs: Quick Start, CLI, Project Structure, Compatibility
|
||||
- Ask/Report: GitHub Issues & Discussions
|
||||
- Community: Discord
|
||||
|
||||
@@ -1,118 +1,127 @@
|
||||
---
|
||||
title: Getting Started
|
||||
description: A modern CLI tool for scaffolding end-to-end type-safe TypeScript projects with best practices and customizable configurations
|
||||
title: Quick Start
|
||||
description: Create your first Better-T-Stack project in minutes
|
||||
---
|
||||
|
||||
> ⚠️ **Warning:** Documentation is a work in progress.
|
||||
## Philosophy
|
||||
|
||||
## What is Better-T-Stack?
|
||||
- With Better T Stack, you freely choose only the parts you want; nothing extra is added.
|
||||
- Pick your frontend, backend, API layer, database, ORM, auth, addons — or skip any of them. Compatibility is enforced.
|
||||
- No lock‑in: it’s a generator, not a framework fork.
|
||||
|
||||
Better-T-Stack is designed to eliminate the complexity of setting up modern TypeScript projects. Instead of spending hours configuring build tools, type systems, databases, and deployment pipelines, you can get a production-ready project structure in minutes.
|
||||
## Get Started
|
||||
|
||||
### Key Features
|
||||
### Stack Builder (UI)
|
||||
|
||||
- **🏗️ Full-Stack Ready**: Choose from multiple frontend and backend frameworks
|
||||
- **🔒 End-to-End Type Safety**: TypeScript across your entire application stack
|
||||
- **🗄️ Database Integration**: Support for SQLite, PostgreSQL, MySQL, and MongoDB
|
||||
- **🔐 Built-in Authentication**: Email/password auth with Better-Auth
|
||||
- **📱 Multi-Platform**: Web, mobile (React Native), and desktop (Tauri) support
|
||||
- **☁️ Deployment Ready**: Configured for modern hosting platforms
|
||||
- **⚡ Modern Tooling**: Latest versions of your favorite tools and frameworks
|
||||
|
||||
### Supported Technologies
|
||||
|
||||
#### Frontend Frameworks
|
||||
- **React** with TanStack Router or React Router
|
||||
- **Next.js** - Full-stack React framework
|
||||
- **SvelteKit** - Web framework for Svelte
|
||||
- **Nuxt** - Vue.js framework
|
||||
- **SolidJS** - Performant reactive framework
|
||||
- **TanStack Start** - SSR with TanStack Router
|
||||
- **React Native** - Mobile development with Expo
|
||||
|
||||
#### Backend Frameworks
|
||||
- **Hono** - Lightweight, ultrafast web framework
|
||||
- **Express** - Popular Node.js framework
|
||||
- **Fastify** - Fast, low-overhead framework
|
||||
- **Elysia** - Type-safe, high-performance framework
|
||||
- **Convex** - Reactive backend-as-a-service
|
||||
- **Next.js API Routes** - Full-stack React
|
||||
|
||||
#### Databases & ORMs
|
||||
- **Databases**: SQLite/Turso, PostgreSQL, MySQL, MongoDB
|
||||
- **ORMs**: Drizzle (TypeScript-first), Prisma (feature-rich), Mongoose
|
||||
- **Hosting**: Neon, Supabase, MongoDB Atlas, Cloudflare D1
|
||||
|
||||
#### API Layers
|
||||
- **tRPC** - End-to-end type-safe APIs
|
||||
- **oRPC** - OpenAPI-compatible type-safe APIs
|
||||
|
||||
### Why Choose Better-T-Stack?
|
||||
|
||||
#### Traditional Setup Problems
|
||||
- ⏰ Hours of configuration and setup
|
||||
- 🔧 Complex toolchain integration
|
||||
- 📚 Overwhelming technology choices
|
||||
- 🐛 Configuration bugs and compatibility issues
|
||||
- 🏗️ Inconsistent project structures
|
||||
|
||||
#### Better-T-Stack Solutions
|
||||
- ⚡ **Quick Setup**: Get started in under 2 minutes
|
||||
- 🎯 **Curated Choices**: Pre-selected, compatible technology combinations
|
||||
- 📋 **Best Practices**: Industry-standard configurations out of the box
|
||||
- 🔄 **Consistent Structure**: Standardized monorepo organization
|
||||
- 🧪 **Battle-Tested**: Configurations used in production applications
|
||||
|
||||
## Quick Example
|
||||
- Visit [/new](/new) to pick your stack and copy the generated command
|
||||
- Or open it via:
|
||||
|
||||
```bash
|
||||
# Create a new project
|
||||
npx create-better-t-stack@latest my-app
|
||||
|
||||
# Choose your stack interactively or use flags
|
||||
npx create-better-t-stack@latest my-app \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--database postgres \
|
||||
--orm drizzle \
|
||||
--auth \
|
||||
--addons pwa turborepo
|
||||
bun create better-t-stack@latest builder
|
||||
```
|
||||
|
||||
## Project Types
|
||||
### CLI (prompts)
|
||||
|
||||
Better-T-Stack supports various project configurations:
|
||||
```bash
|
||||
bun create better-t-stack@latest
|
||||
```
|
||||
|
||||
### Full-Stack Web Applications
|
||||
Perfect for modern web apps with React, Vue, or Svelte frontends backed by type-safe APIs.
|
||||
Follow the interactive prompts to choose your frontend, backend, database, ORM, API layer, and addons.
|
||||
|
||||
### Mobile Applications
|
||||
Build React Native apps with Expo, sharing type definitions with your backend.
|
||||
Skip prompts and use the default stack:
|
||||
|
||||
### Desktop Applications
|
||||
Create cross-platform desktop apps using Tauri with your web frontend.
|
||||
```bash
|
||||
bun create better-t-stack@latest my-app --yes
|
||||
```
|
||||
|
||||
### API-Only Projects
|
||||
Build standalone APIs and microservices with your preferred backend framework.
|
||||
Prefer a visual flow? Use the Stack Builder at [/new](/new) to pick your stack and copy the generated command. You can also open it via:
|
||||
|
||||
### Monorepo Projects
|
||||
Organize multiple applications (web, mobile, API) in a single repository with shared packages.
|
||||
```bash
|
||||
bun create better-t-stack@latest builder
|
||||
```
|
||||
|
||||
## Who Should Use Better-T-Stack?
|
||||
## Common Setups
|
||||
|
||||
- **Indie Developers**: Quickly prototype and build full-stack applications
|
||||
- **Startups**: Get to market faster with production-ready project structure
|
||||
- **Teams**: Standardize project setup across your organization
|
||||
- **Students**: Learn modern full-stack development with best practices
|
||||
- **Agencies**: Rapidly scaffold client projects with consistent quality
|
||||
### Default Stack
|
||||
|
||||
## What's Next?
|
||||
```bash
|
||||
bun create better-t-stack@latest my-webapp \
|
||||
--frontend tanstack-router \
|
||||
--backend hono \
|
||||
--database sqlite \
|
||||
--orm drizzle \
|
||||
--auth \
|
||||
--addons turborepo
|
||||
```
|
||||
|
||||
Ready to get started? Check out our [Quick Start Guide](/docs/quick-start) to create your first Better-T-Stack project, or explore the [Configuration Options](/docs/frontend) to learn about all available technologies and features.
|
||||
### Convex + React
|
||||
|
||||
### Need Help?
|
||||
```bash
|
||||
bun create better-t-stack@latest my-convex-app \
|
||||
--frontend tanstack-router \
|
||||
--backend convex
|
||||
```
|
||||
|
||||
- 📖 **Documentation**: Comprehensive guides and references
|
||||
- 🐛 **Issues**: Report bugs on [GitHub](https://github.com/AmanVarshney01/create-better-t-stack/issues)
|
||||
- 💬 **Discussions**: Community support and questions
|
||||
- 🌟 **Star us**: Show support on [GitHub](https://github.com/AmanVarshney01/create-better-t-stack)
|
||||
### API Only
|
||||
|
||||
```bash
|
||||
bun create better-t-stack@latest my-api \
|
||||
--frontend none \
|
||||
--backend fastify \
|
||||
--runtime node \
|
||||
--database postgres \
|
||||
--orm prisma \
|
||||
--api trpc
|
||||
```
|
||||
|
||||
### Mobile App (Expo)
|
||||
|
||||
```bash
|
||||
bun create better-t-stack@latest my-native \
|
||||
--frontend native-nativewind \
|
||||
--backend hono \
|
||||
--database sqlite \
|
||||
--orm drizzle \
|
||||
--auth
|
||||
```
|
||||
|
||||
### Empty Monorepo
|
||||
|
||||
```bash
|
||||
bun create better-t-stack@latest my-workspace \
|
||||
--frontend none \
|
||||
--backend none
|
||||
```
|
||||
|
||||
## Flags Cheat Sheet
|
||||
|
||||
See the full list in the [CLI Reference](/docs/cli). Key flags:
|
||||
|
||||
- `--frontend`: tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, native-nativewind, native-unistyles, none
|
||||
- `--backend`: hono, express, fastify, elysia, next, convex, none
|
||||
- `--runtime`: bun, node, workers, none
|
||||
- `--database`: sqlite, postgres, mysql, mongodb, none
|
||||
- `--orm`: drizzle, prisma, mongoose, none
|
||||
- `--api`: trpc, orpc, none
|
||||
- `--addons`: turborepo, pwa, tauri, biome, husky, starlight, none
|
||||
- `--examples`: todo, ai, none
|
||||
|
||||
## Next Steps
|
||||
|
||||
<Cards>
|
||||
<Card href="/docs/cli" title="CLI (per-command)">
|
||||
Flags, usage, and examples for each command
|
||||
</Card>
|
||||
<Card href="/docs/project-structure" title="Project Structure">
|
||||
See how web/server/native and Convex layouts are generated
|
||||
</Card>
|
||||
<Card href="/docs/compatibility" title="Compatibility">
|
||||
Valid combinations for backend, runtime, database, ORM, API
|
||||
</Card>
|
||||
<Card href="/docs/bts-config" title="bts.jsonc">
|
||||
Required for the add command; safe to delete if you don’t use add
|
||||
</Card>
|
||||
<Card href="/docs/contributing" title="Contributing">
|
||||
Dev setup and contribution flow
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
@@ -1,236 +0,0 @@
|
||||
---
|
||||
title: Installation
|
||||
description: How to install and set up Better-T-Stack CLI
|
||||
---
|
||||
|
||||
## System Requirements
|
||||
|
||||
Before installing Better-T-Stack, ensure your system meets these requirements:
|
||||
|
||||
- **Node.js**: Version 18 or higher
|
||||
- **Package Manager**: npm, pnpm, or bun
|
||||
- **Git**: For repository initialization (optional but recommended)
|
||||
|
||||
### Optional Dependencies
|
||||
|
||||
Depending on your project configuration, you may need:
|
||||
|
||||
- **Docker**: For local database development with Docker Compose
|
||||
- **Rust & System Dependencies**: For Tauri desktop applications
|
||||
- **Cloudflare CLI**: For Workers deployment
|
||||
|
||||
## Quick Start (Recommended)
|
||||
|
||||
The fastest way to get started is using npx, which runs the latest version without installation:
|
||||
|
||||
```bash
|
||||
npx create-better-t-stack@latest my-project
|
||||
```
|
||||
|
||||
This command will:
|
||||
1. Download the latest version of the CLI
|
||||
2. Run the interactive setup wizard
|
||||
3. Create your project in the `my-project` directory
|
||||
|
||||
## Package Manager Specific Commands
|
||||
|
||||
### npm
|
||||
|
||||
```bash
|
||||
# Run without installing
|
||||
npx create-better-t-stack@latest my-project
|
||||
|
||||
# Or install globally
|
||||
npm install -g create-better-t-stack
|
||||
create-better-t-stack my-project
|
||||
```
|
||||
|
||||
### pnpm
|
||||
|
||||
```bash
|
||||
# Run without installing (recommended)
|
||||
pnpm create better-t-stack@latest my-project
|
||||
|
||||
# Or install globally
|
||||
pnpm add -g create-better-t-stack
|
||||
create-better-t-stack my-project
|
||||
```
|
||||
|
||||
### bun
|
||||
|
||||
```bash
|
||||
# Run without installing (recommended)
|
||||
bun create better-t-stack@latest my-project
|
||||
|
||||
# Or install globally
|
||||
bun add -g create-better-t-stack
|
||||
create-better-t-stack my-project
|
||||
```
|
||||
|
||||
## Global Installation
|
||||
|
||||
If you frequently create new projects, you might want to install the CLI globally:
|
||||
|
||||
<Tabs items={['npm', 'pnpm', 'bun']}>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npm install -g create-better-t-stack
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm add -g create-better-t-stack
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun add -g create-better-t-stack
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
After global installation, you can run:
|
||||
|
||||
```bash
|
||||
create-better-t-stack my-project
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
Verify your installation by checking the version:
|
||||
|
||||
```bash
|
||||
# If installed globally
|
||||
create-better-t-stack --version
|
||||
|
||||
# Or with npx
|
||||
npx create-better-t-stack@latest --version
|
||||
```
|
||||
|
||||
You should see output similar to:
|
||||
|
||||
```
|
||||
2.26.3
|
||||
```
|
||||
|
||||
## Development Installation
|
||||
|
||||
For contributing to Better-T-Stack or running the latest development version:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/AmanVarshney01/create-better-t-stack.git
|
||||
cd create-better-t-stack
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Build the CLI
|
||||
cd apps/cli
|
||||
pnpm build
|
||||
|
||||
# Link for local development
|
||||
pnpm link --global
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Permission Errors (npm)
|
||||
|
||||
If you encounter permission errors with npm global installation:
|
||||
|
||||
```bash
|
||||
# Use npx instead (recommended)
|
||||
npx create-better-t-stack@latest my-project
|
||||
|
||||
# Or configure npm to use a different directory
|
||||
mkdir ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
#### Node.js Version Issues
|
||||
|
||||
Ensure you're using Node.js 18 or higher:
|
||||
|
||||
```bash
|
||||
node --version
|
||||
```
|
||||
|
||||
If you need to upgrade Node.js:
|
||||
|
||||
- **Using nvm**: `nvm install 18 && nvm use 18`
|
||||
- **Using n**: `n 18`
|
||||
- **Download**: Visit [nodejs.org](https://nodejs.org/)
|
||||
|
||||
#### Package Manager Not Found
|
||||
|
||||
If you prefer a specific package manager but it's not installed:
|
||||
|
||||
```bash
|
||||
# Install pnpm
|
||||
npm install -g pnpm
|
||||
|
||||
# Install bun
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
```
|
||||
|
||||
#### Network Issues
|
||||
|
||||
If you experience network timeouts or connection issues:
|
||||
|
||||
```bash
|
||||
# Try with different registry
|
||||
npm config set registry https://registry.npmjs.org/
|
||||
|
||||
# Or clear npm cache
|
||||
npm cache clean --force
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once installed, you're ready to create your first project:
|
||||
|
||||
1. **Quick Start**: Follow our [Quick Start Guide](/docs/quick-start)
|
||||
2. **Configuration**: Learn about [Configuration Options](/docs/frontend)
|
||||
3. **CLI Reference**: Explore all [CLI Commands](/docs/cli-commands)
|
||||
|
||||
## Staying Updated
|
||||
|
||||
To ensure you're always using the latest version with bug fixes and new features:
|
||||
|
||||
### Using npx (Automatic)
|
||||
When using `npx create-better-t-stack@latest`, you automatically get the latest version.
|
||||
|
||||
### Global Installation Updates
|
||||
|
||||
If you have it installed globally, update regularly:
|
||||
|
||||
<Tabs items={['npm', 'pnpm', 'bun']}>
|
||||
<Tab value="npm">
|
||||
```bash
|
||||
npm update -g create-better-t-stack
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="pnpm">
|
||||
```bash
|
||||
pnpm update -g create-better-t-stack
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="bun">
|
||||
```bash
|
||||
bun update -g create-better-t-stack
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Release Notes
|
||||
|
||||
Stay informed about new features and changes:
|
||||
|
||||
- **GitHub Releases**: [View releases](https://github.com/AmanVarshney01/create-better-t-stack/releases)
|
||||
- **Changelog**: Check the repository for detailed changes
|
||||
- **Breaking Changes**: Major version updates may include breaking changes
|
||||
@@ -1,32 +1,12 @@
|
||||
{
|
||||
"pages": [
|
||||
"index",
|
||||
"installation",
|
||||
"quick-start",
|
||||
"cli",
|
||||
"project-structure",
|
||||
"---Configuration Options---",
|
||||
"frontend",
|
||||
"backend",
|
||||
"database",
|
||||
"orm",
|
||||
"authentication",
|
||||
"runtime",
|
||||
"api-layer",
|
||||
"---Addons & Features---",
|
||||
"addons",
|
||||
"examples",
|
||||
"deployment",
|
||||
"---Database Setup---",
|
||||
"database-providers",
|
||||
"---CLI Reference---",
|
||||
"cli-commands",
|
||||
"cli-flags",
|
||||
"---Guides---",
|
||||
"migration-guide",
|
||||
"troubleshooting",
|
||||
"best-practices",
|
||||
"---FAQ---",
|
||||
"faq",
|
||||
"compatibility"
|
||||
"bts-config",
|
||||
"analytics",
|
||||
"contributing",
|
||||
"compatibility",
|
||||
"faq"
|
||||
]
|
||||
}
|
||||
|
||||
60
apps/web/content/docs/project-structure.mdx
Normal file
60
apps/web/content/docs/project-structure.mdx
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Project Structure
|
||||
description: High-level overview of the generated monorepo layout
|
||||
---
|
||||
|
||||
import { File, Folder, Files } from 'fumadocs-ui/components/files';
|
||||
|
||||
### Server-based projects
|
||||
|
||||
<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>
|
||||
|
||||
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.
|
||||
|
||||
### Convex-based projects
|
||||
|
||||
<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>
|
||||
|
||||
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.
|
||||
|
||||
### Where features land (high level)
|
||||
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user