better-t-stackBetter T Stack
文档构建器分析展示
npmxdiscord

项目结构

了解 Better-T-Stack CLI 创建的项目结构

概述

Better-T-Stack CLI 搭建一个包含 apps/* 的 monorepo，并在需要时包含 packages/*。具体结构取决于您的选择（前端、后端、API、数据库/ORM、认证、附加组件、运行时、部署）。本页面反映了 CLI 实际写入的内容。

根目录布局

在仓库根目录您将看到：

/
├── apps/                  # 应用程序（web、server、native、docs）
├── packages/             # 仅在需要时存在（例如 Convex 后端）
├── package.json          # 根目录 package.json（脚本由 CLI 更新）
├── bts.jsonc             # Better‑T Stack 配置（始终写入）
├── turbo.json            # 仅在选择了 "turborepo" 附加组件时存在
├── pnpm-workspace.yaml   # 仅在 packageManager=pnpm 时存在
├── bunfig.toml           # 仅在 packageManager=bun 时存在
├── .npmrc                # pnpm + (native 或 nuxt) 用于别名解析
└── README.md             # 生成的快速入门指南

注意：

  • bts.jsonc 让 CLI 能够检测并在以后增强您的项目；如果您计划使用 bts add，请保留它。
  • turbo.json 仅在您选择了 Turborepo 附加组件时存在。

按后端分类的 Monorepo 结构

非 Convex 后端（hono、express、fastify、elysia、next）

my-app/
├── apps/
│   ├── web/           # 如果您选择了 web 框架则存在
│   ├── server/        # 后端 API（框架取决于您的选择）
│   ├── native/        # 如果您选择了 React Native (Expo) 则存在
│   └── docs/          # 如果您选择了 Starlight/Fumadocs 附加组件则存在
└── packages/          # 可能存在但默认不使用

Convex 后端

my-app/
├── apps/
│   ├── web/           # 如果您选择了 web 框架则存在
│   ├── native/        # 如果您选择了 React Native (Expo) 则存在
│   └── docs/          # 如果您选择了 Starlight/Fumadocs 附加组件则存在
└── packages/
    └── backend/       # Convex 函数、模式配置

前端结构 (apps/web)

结构因框架而异。标记为“(auth)”或“(API)”的项目仅在启用这些选项时出现。

React with TanStack Router

apps/web/
├── src/
│   ├── components/
│   │   ├── ui/                 # shadcn/ui 基础组件（来自 web base）
│   │   ├── header.tsx
│   │   ├── loader.tsx
│   │   ├── mode-toggle.tsx
│   │   └── theme-provider.tsx
│   ├── routes/
│   │   ├── __root.tsx          # 根布局
│   │   └── index.tsx           # 首页
│   ├── lib/
│   │   └── utils.ts
│   ├── utils/
│   │   └── trpc.ts (API=trpc) | orpc.ts (API=orpc)
│   ├── main.tsx
│   └── index.css
├── index.html
├── components.json            # shadcn/ui 配置
├── 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

注意：

  • 如果您选择 backend=next，后端会在 apps/server 中单独搭建。web 应用不包含 API 路由。
  • (auth) 添加 src/app/login/* 和 src/app/dashboard/* 以及登录组件。

后端结构 (apps/server)

服务器结构取决于您的后端选择：

Hono 后端

apps/server/
├── src/
│   ├── routers/
│   │   └── index.ts          # 基础路由器
│   └── index.ts              # Hono 应用入口
├── package.json
└── tsconfig.json

Express / Fastify / Elysia

apps/server/
├── src/
│   └── index.ts              # 框架入口
├── package.json
└── tsconfig.json

Next (后端)

apps/server/
├── src/
│   ├── app/
│   │   └── route.ts          # App Router 端点
│   └── middleware.ts
├── next.config.ts
├── tsconfig.json
└── package.json

Workers 运行时（可选）

当 runtime=workers 时，您还会得到：

apps/server/
└── wrangler.jsonc            # Cloudflare Workers 配置（模板）

API 和认证脚手架（条件性）：

  • 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

数据库配置

仅在您选择了数据库和 ORM 时添加：

Drizzle ORM

apps/server/
├── src/db/
│   └── index.ts              # 数据库连接
├── drizzle.config.ts         # Drizzle 配置
└── drizzle/                  # 生成的迁移（在运行命令后）

Prisma ORM

apps/server/
└── prisma/
    ├── schema.prisma         # 数据库模式
    └── migrations/           # 运行 Prisma 命令后生成

Mongoose (MongoDB)

apps/server/
└── src/db/
    └── index.ts              # Mongoose 连接

认证 + 数据库

如果您选择了认证，会为您的 ORM 添加额外文件：

  • Drizzle: src/db/schema/auth.ts
  • Prisma: prisma/schema/auth.prisma
  • Mongoose: src/db/models/auth.model.ts

Docker compose（可选）

如果 dbSetup=docker，会在 apps/server/ 中添加 docker-compose.yml 用于您的数据库。

原生应用结构 (apps/native)

仅在您包含 React Native (NativeWind 或 Unistyles) 时创建：

apps/native/
├── app/                 # 应用屏幕
│   ├── (tabs)/         # 标签导航
│   ├── _layout.tsx     # 根布局
│   └── index.tsx       # 主屏幕
├── components/         # React Native 组件
├── lib/               # 工具函数
├── assets/            # 图片、字体
├── app.json          # Expo 配置
├── package.json      # 依赖项
└── tsconfig.json     # TypeScript 配置

如果选择了 API，会添加客户端工具：

  • API=trpc: utils/trpc.ts
  • API=orpc: utils/orpc.ts

文档结构 (apps/docs)

当使用 Starlight 或 Fumadocs 附加组件时：

apps/docs/
├── src/
│   ├── content/        # 文档内容
│   │   └── docs/       # 文档页面
│   └── pages/          # Astro 页面（Starlight）
├── astro.config.mjs    # Astro 配置（Starlight）
├── package.json
└── tsconfig.json

配置文件

Better-T-Stack 配置 (bts.jsonc)

{
  "$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": <"better-auth"|"clerk"|"none">,
  "packageManager": "<bun|pnpm|npm>",
  "dbSetup": "<none|docker|d1>",
  "api": "<none|trpc|orpc>",
  "webDeploy": "<none|wrangler|alchemy>",
  "serverDeploy": "<none|wrangler|alchemy>"
}

Turborepo 配置 (turbo.json)

仅在您选择了 Turborepo 附加组件时生成。

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

共享包

默认情况下，不创建共享包。您只会在使用 Convex 后端时看到 packages/backend。随着仓库的增长，您可以手动添加更多包。

packages/
└── backend/            # 仅在使用 Convex 后端时存在

开发脚本

脚本会根据您的包管理器和是否选择了 Turborepo 附加组件进行调整。

使用 Turborepo：

{
  "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"
  }
}

不使用 Turborepo（Bun 示例）：

{
  "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"
  }
}

注意：

  • Convex 添加 dev:setup 用于初始后端配置。

关键细节

  • Monorepo: apps/* 始终存在；packages/* 仅在需要时存在（Convex）
  • React web base: shadcn/ui 基础组件、components.json、通用工具函数
  • API 客户端: 在选择时向 web/native 添加 src/utils/trpc.ts 或 src/utils/orpc.ts
  • 认证: 根据提供商添加认证设置：
    • better-auth: 服务器上的 src/lib/auth.ts 和 web 应用上的登录/仪表板页面
    • clerk: Clerk 提供商设置和认证组件
  • ORM/DB: 仅在选择时添加 Drizzle/Prisma/Mongoose 文件
  • 额外项: 根据包管理器和选择添加 pnpm-workspace.yaml、bunfig.toml 或 .npmrc
  • 部署: Workers 部署向相应的应用添加 wrangler.jsonc 模板

这反映了 CLI 实际写入的文件，因此新项目与此处记录的内容相匹配。

指南

常见设置的实用指南

bts.jsonc

bts.jsonc 的作用及其重要性