mirror of
https://github.com/FranP-code/create-better-t-stack.git
synced 2025-10-12 23:52:15 +00:00
chore(web): improve docs
This commit is contained in:
Aman Varshney
@@ -1,60 +1,343 @@
|
||||
---
|
||||
title: Project Structure
|
||||
description: High-level overview of the generated monorepo layout
|
||||
description: Understanding the structure of projects created by Better-T Stack CLI
|
||||
---
|
||||
|
||||
import { File, Folder, Files } from 'fumadocs-ui/components/files';
|
||||
## Overview
|
||||
|
||||
### Server-based projects
|
||||
Better-T Stack CLI scaffolds a monorepo with `apps/*` and, when needed, `packages/*`. The exact structure depends on your choices (frontend, backend, API, database/ORM, auth, addons, runtime, deploy). This page mirrors what the CLI actually writes.
|
||||
|
||||
<Files>
|
||||
<Folder name="apps" defaultOpen>
|
||||
<Folder name="server" defaultOpen>
|
||||
<Folder name="src" />
|
||||
</Folder>
|
||||
<Folder name="web" defaultOpen disabled>
|
||||
<Folder name="src" />
|
||||
<Folder name="public" />
|
||||
</Folder>
|
||||
<Folder name="native" defaultOpen disabled>
|
||||
<Folder name="app" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
</Files>
|
||||
## Root layout
|
||||
|
||||
At the repository root you will see:
|
||||
|
||||
```
|
||||
/
|
||||
├── apps/ # Applications (web, server, native, docs)
|
||||
├── packages/ # Only when needed (e.g. Convex backend)
|
||||
├── package.json # Root package.json (scripts updated by CLI)
|
||||
├── bts.jsonc # Better‑T Stack configuration (always written)
|
||||
├── turbo.json # Only when addon "turborepo" is selected
|
||||
├── pnpm-workspace.yaml # Only when packageManager=pnpm
|
||||
├── bunfig.toml # Only when packageManager=bun
|
||||
├── .npmrc # pnpm + (native or nuxt) for alias resolution
|
||||
└── README.md # Generated quickstart
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `apps/server` is present for backends like `hono`, `express`, `fastify`, `elysia`, `next`.
|
||||
- `apps/web` and `apps/native` are optional; they appear only if you select a web or native frontend.
|
||||
- `bts.jsonc` lets the CLI detect and enhance your project later; keep it if you plan to use `bts add`.
|
||||
- `turbo.json` exists only if you picked the Turborepo addon.
|
||||
|
||||
### Convex-based projects
|
||||
## Monorepo structure by backend
|
||||
|
||||
<Files>
|
||||
<Folder name="apps" defaultOpen>
|
||||
<Folder name="web" defaultOpen disabled>
|
||||
<Folder name="src" />
|
||||
<Folder name="public" />
|
||||
</Folder>
|
||||
<Folder name="native" defaultOpen disabled>
|
||||
<Folder name="app" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
<Folder name="packages" defaultOpen>
|
||||
<Folder name="backend" defaultOpen>
|
||||
<Folder name="convex" />
|
||||
</Folder>
|
||||
</Folder>
|
||||
</Files>
|
||||
### Non-Convex backends (hono, express, fastify, elysia, next)
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── apps/
|
||||
│ ├── web/ # Present if you picked a web framework
|
||||
│ ├── server/ # Backend API (framework depends on your choice)
|
||||
│ ├── native/ # Present if you picked React Native (Expo)
|
||||
│ └── docs/ # Present if you picked the Starlight/Fumadocs addon
|
||||
└── packages/ # May exist but not used by default
|
||||
```
|
||||
|
||||
### Convex backend
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── apps/
|
||||
│ ├── web/ # Present if you picked a web framework
|
||||
│ ├── native/ # Present if you picked React Native (Expo)
|
||||
│ └── docs/ # Present if you picked the Starlight/Fumadocs addon
|
||||
└── packages/
|
||||
└── backend/ # Convex functions, schema and config
|
||||
```
|
||||
|
||||
## Frontend Structure (apps/web)
|
||||
|
||||
The structure varies by framework. Items marked “(auth)” or “(API)” appear only when those options are enabled.
|
||||
|
||||
### React with TanStack Router
|
||||
|
||||
```
|
||||
apps/web/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ │ ├── ui/ # shadcn/ui primitives (from web base)
|
||||
│ │ ├── header.tsx
|
||||
│ │ ├── loader.tsx
|
||||
│ │ ├── mode-toggle.tsx
|
||||
│ │ └── theme-provider.tsx
|
||||
│ ├── routes/
|
||||
│ │ ├── __root.tsx # Root layout
|
||||
│ │ └── index.tsx # Home
|
||||
│ ├── lib/
|
||||
│ │ └── utils.ts
|
||||
│ ├── utils/
|
||||
│ │ └── trpc.ts (API=trpc) | orpc.ts (API=orpc)
|
||||
│ ├── main.tsx
|
||||
│ └── index.css
|
||||
├── index.html
|
||||
├── components.json # shadcn/ui config
|
||||
├── tsconfig.json
|
||||
├── vite.config.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Next.js
|
||||
|
||||
```
|
||||
apps/web/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── layout.tsx
|
||||
│ │ └── page.tsx
|
||||
│ └── components/
|
||||
│ ├── mode-toggle.tsx
|
||||
│ ├── providers.tsx
|
||||
│ └── theme-provider.tsx
|
||||
├── components.json
|
||||
├── next.config.ts
|
||||
├── postcss.config.mjs
|
||||
├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Convex replaces the server app; `packages/backend` is generated instead of `apps/server`.
|
||||
- Auth, DB/ORM, and API scaffolding are disabled for Convex presets.
|
||||
- If you choose `backend=next`, the backend is scaffolded separately in `apps/server`. The web app does not include API routes.
|
||||
- (auth) adds `src/app/login/*` and `src/app/dashboard/*` plus sign-in components.
|
||||
|
||||
### Where features land (high level)
|
||||
## Backend Structure (apps/server)
|
||||
|
||||
- API layer: merged into `apps/server` and `apps/web` when applicable.
|
||||
- Database & ORM: merged into `apps/server` when both are selected.
|
||||
- Authentication: merged into `apps/server`, `apps/web`, and `apps/native` when enabled and compatible.
|
||||
- Addons: PWA merges into `apps/web`; others merge at the appropriate location.
|
||||
- Web deployment (Workers): deployment files merge into `apps/web` per frontend.
|
||||
- Runtime extras (Workers): Workers-specific files added at the repo root.
|
||||
The server structure depends on your backend choice:
|
||||
|
||||
### Hono backend
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/
|
||||
│ ├── routers/
|
||||
│ │ └── index.ts # Base router
|
||||
│ └── index.ts # Hono app entry
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
### Express / Fastify / Elysia
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/
|
||||
│ └── index.ts # Framework entry
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
### Next (backend)
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ └── route.ts # App Router endpoint
|
||||
│ └── middleware.ts
|
||||
├── next.config.ts
|
||||
├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Workers runtime (optional)
|
||||
|
||||
When `runtime=workers`, you’ll also get:
|
||||
|
||||
```
|
||||
apps/server/
|
||||
└── wrangler.jsonc # Cloudflare Workers config (template)
|
||||
```
|
||||
|
||||
API and auth scaffolding (conditional):
|
||||
- API=trpc: `src/lib/trpc.ts`, `src/lib/context.ts`
|
||||
- API=orpc: `src/lib/orpc.ts`, `src/lib/context.ts`
|
||||
- Auth: `src/lib/auth.ts`
|
||||
|
||||
## Database Configuration
|
||||
|
||||
Added only when you selected a database and ORM:
|
||||
|
||||
### Drizzle ORM
|
||||
|
||||
```
|
||||
apps/server/
|
||||
├── src/db/
|
||||
│ └── index.ts # Database connection
|
||||
├── drizzle.config.ts # Drizzle configuration
|
||||
└── drizzle/ # Generated migrations (after you run commands)
|
||||
```
|
||||
|
||||
### Prisma ORM
|
||||
|
||||
```
|
||||
apps/server/
|
||||
└── prisma/
|
||||
├── schema.prisma # Database schema
|
||||
└── migrations/ # Generated after running Prisma commands
|
||||
```
|
||||
|
||||
### Mongoose (MongoDB)
|
||||
|
||||
```
|
||||
apps/server/
|
||||
└── src/db/
|
||||
└── index.ts # Mongoose connection
|
||||
```
|
||||
|
||||
### Auth + DB
|
||||
|
||||
If you selected auth, additional files are added for your ORM:
|
||||
- Drizzle: `src/db/schema/auth.ts`
|
||||
- Prisma: `prisma/schema/auth.prisma`
|
||||
- Mongoose: `src/db/models/auth.model.ts`
|
||||
|
||||
### Docker compose (optional)
|
||||
|
||||
If `dbSetup=docker`, a `docker-compose.yml` is added in `apps/server/` for your database.
|
||||
|
||||
## Native App Structure (apps/native)
|
||||
|
||||
Created only when you include React Native (NativeWind or Unistyles):
|
||||
|
||||
```
|
||||
apps/native/
|
||||
├── app/ # App screens
|
||||
│ ├── (tabs)/ # Tab navigation
|
||||
│ ├── _layout.tsx # Root layout
|
||||
│ └── index.tsx # Home screen
|
||||
├── components/ # React Native components
|
||||
├── lib/ # Utilities
|
||||
├── assets/ # Images, fonts
|
||||
├── app.json # Expo configuration
|
||||
├── package.json # Dependencies
|
||||
└── tsconfig.json # TypeScript config
|
||||
```
|
||||
|
||||
If an API is selected, a client utility is added:
|
||||
- API=trpc: `utils/trpc.ts`
|
||||
- API=orpc: `utils/orpc.ts`
|
||||
|
||||
## Documentation Structure (apps/docs)
|
||||
|
||||
When using Starlight or Fumadocs addon:
|
||||
|
||||
```
|
||||
apps/docs/
|
||||
├── src/
|
||||
│ ├── content/ # Documentation content
|
||||
│ │ └── docs/ # Doc pages
|
||||
│ └── pages/ # Astro pages (Starlight)
|
||||
├── astro.config.mjs # Astro config (Starlight)
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Better-T Stack Config (bts.jsonc)
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://r2.better-t-stack.dev/schema.json",
|
||||
"version": "<cli-version>",
|
||||
"createdAt": "<timestamp>",
|
||||
"database": "<none|sqlite|postgres|mysql|mongodb>",
|
||||
"orm": "<none|drizzle|prisma|mongoose>",
|
||||
"backend": "<none|hono|express|fastify|elysia|next|convex>",
|
||||
"runtime": "<bun|node|workers>",
|
||||
"frontend": ["<next|tanstack-router|react-router|tanstack-start|nuxt|svelte|solid>"] ,
|
||||
"addons": ["<turborepo|biome|husky|pwa|starlight>"] ,
|
||||
"examples": ["<ai|todo|none>"] ,
|
||||
"auth": <true|false>,
|
||||
"packageManager": "<bun|pnpm|npm>",
|
||||
"dbSetup": "<none|docker|d1>",
|
||||
"api": "<none|trpc|orpc>",
|
||||
"webDeploy": "<none|workers>"
|
||||
}
|
||||
```
|
||||
|
||||
### Turborepo Config (turbo.json)
|
||||
|
||||
Generated only if you chose the Turborepo addon.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://turbo.build/schema.json",
|
||||
"tasks": {
|
||||
"build": {
|
||||
"dependsOn": ["^build"],
|
||||
"outputs": ["dist/**", ".next/**"]
|
||||
},
|
||||
"dev": {
|
||||
"cache": false,
|
||||
"persistent": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Shared packages
|
||||
|
||||
By default, no shared packages are created. You will see `packages/backend` only when using the Convex backend. You can add more packages manually as your repo grows.
|
||||
|
||||
```
|
||||
packages/
|
||||
└── backend/ # Only with Convex backend
|
||||
```
|
||||
|
||||
## Development Scripts
|
||||
|
||||
Scripts are adjusted based on your package manager and whether the Turborepo addon is selected.
|
||||
|
||||
With Turborepo:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "turbo dev",
|
||||
"build": "turbo build",
|
||||
"check-types": "turbo check-types",
|
||||
"dev:web": "turbo -F web dev",
|
||||
"dev:server": "turbo -F server dev",
|
||||
"db:push": "turbo -F server db:push",
|
||||
"db:studio": "turbo -F server db:studio"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Without Turborepo (example for Bun):
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "bun run --filter '*' dev",
|
||||
"build": "bun run --filter '*' build",
|
||||
"check-types": "bun run --filter '*' check-types",
|
||||
"dev:web": "bun run --filter web dev",
|
||||
"dev:server": "bun run --filter server dev"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Convex adds `dev:setup` for initial backend configuration.
|
||||
|
||||
## Key Details
|
||||
|
||||
- **Monorepo**: `apps/*` always; `packages/*` only when needed (Convex)
|
||||
- **React web base**: shadcn/ui primitives, `components.json`, common utilities
|
||||
- **API clients**: `src/utils/trpc.ts` or `src/utils/orpc.ts` added to web/native when selected
|
||||
- **Auth**: Adds `src/lib/auth.ts` on the server and login/dashboard pages on the web app
|
||||
- **ORM/DB**: Drizzle/Prisma/Mongoose files added only when selected
|
||||
- **Extras**: `pnpm-workspace.yaml`, `bunfig.toml`, or `.npmrc` added based on package manager and choices
|
||||
- **Deploy**: Workers deploy adds `wrangler.jsonc` templates to the appropriate app(s)
|
||||
|
||||
This reflects the actual files written by the CLI so new projects match what’s documented here.
|
||||
Reference in New Issue
Block a user