create-better-t-stack 开发者指南：贡献代码与扩展功能的完整教程

create-better-t-stack 是一个现代化的 CLI 工具，用于搭建端到端类型安全的 TypeScript 项目，遵循最佳实践并提供可自定义的配置。无论你是想要贡献代码还是扩展功能，这份完整指南都将帮助你快速上手。

🚀 项目概述与架构

create-better-t-stack 采用 monorepo 架构，包含两个主要应用：

• CLI 工具：位于 apps/cli/，负责项目脚手架生成
• 文档网站：位于 apps/web/，提供完整的项目文档

图：create-better-t-stack 的命令行交互演示

📋 开发环境搭建

前置要求

• Node.js (LTS 版本)
• Bun (推荐包管理器)
• Git

安装步骤

git clone https://gitcode.com/gh_mirrors/cr/create-better-t-stack.git
cd create-better-t-stack
bun install

🔧 CLI 工具开发

本地开发模式

进入 CLI 目录并启动开发环境：

cd apps/cli
bun link  # 可选：全局链接以便在任何位置测试
bun dev   # 在监视模式下运行

现在你可以到系统中的任何位置（比如测试文件夹）运行：

create-better-t-stack

这将运行本地安装的 CLI 工具。

📖 文档网站开发

本地开发设置

从项目根目录运行：

bun i
cd packages/backend
bun dev:setup  # 在提示中可以选择本地开发选项

# 将 packages/backend/.env.local 中的 Convex URL 复制到 apps/web/.env：

NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210/

配置 GitHub 凭证

在 packages/backend 目录中运行：

npx convex env set GITHUB_ACCESS_TOKEN=xxxxx
npx convex env set GITHUB_WEBHOOK_SECRET=xxxxx

# 然后在根目录运行
bun dev

🔄 贡献流程详解

完整贡献步骤

1. 提案讨论：在开始任何新功能或重大更改之前，请先开启一个 issue 来讨论你的提案并获得批准

2. 仓库分叉：Fork 项目仓库到你的账户

3. 功能分支：基于主分支创建新的功能分支

4. 代码修改：遵循现有代码风格进行修改

5. 文档更新：根据需要更新相关文档

6. 测试与格式化

# CLI 测试
cd apps/cli && bun dev
cd apps/cli && bun run test

# Web 测试
bun dev

# 代码格式化
bun run format

# 类型检查
bun check

7. 提交与推送

git add .
git commit -m "feat(cli): add new CLI feature"
git push origin <your-branch>

8. 拉取请求：开启 Pull Request 并链接相关 issues

图：项目的应用图标设计，展示现代简约风格

🎯 扩展功能开发指南

插件系统架构

create-better-t-stack 提供了强大的插件系统，支持多种扩展类型：

• 数据库插件：apps/cli/src/helpers/database-providers/
• 认证插件：apps/cli/src/helpers/core/auth-setup.ts
• 部署插件：apps/cli/src/helpers/deployment/

模板开发

项目使用 Handlebars 模板系统，模板文件位于 apps/cli/templates/ 目录，包含：

• 前端模板：React、Solid、Svelte、Nuxt 等
• 后端模板：Convex、Server 等
• 认证模板：Better-auth、Clerk 等

图：项目启动图标，采用极简几何设计

新增插件步骤

1. 创建插件文件：在对应目录下创建插件实现
2. 配置兼容性：在 apps/cli/src/utils/compatibility.ts 中添加规则
3. 模板配置：在模板目录中添加对应的模板文件
4. 测试验证：确保插件与现有配置兼容

📝 提交规范

使用约定式提交消息，包含适当的范围：

• feat(cli): 新增 CLI 功能
• fix(cli): 修复 CLI 错误
• feat(web): 新增 Web 功能
• fix(web): 修复 Web 错误
• chore(web): 更新依赖
• docs: 更新文档

🛠️ 常用开发命令

测试命令

# 运行所有测试
bun run test

# 特定测试文件
cd apps/cli && bun run test addons.test.ts

# 集成测试
cd apps/cli && bun run test integration.test.ts

构建命令

# CLI 构建
cd apps/cli && bun run build

# 文档构建
cd apps/web && bun run build

💡 最佳实践建议

代码质量保证

• 使用 Biome 进行代码格式化
• 配置 Husky 进行 Git 钩子管理
• 编写完整的类型定义

性能优化

• 利用模板缓存机制
• 优化依赖安装流程
• 减少不必要的文件操作

🔗 获取帮助

• GitHub Issues 和 Discussions：技术讨论和问题报告
• Discord 社区：实时交流与支持

通过这份完整指南，你将能够轻松地为 create-better-t-stack 项目贡献代码或开发新的扩展功能。记住，在开始重大更改之前先进行讨论，这样可以确保你的工作与项目方向保持一致，提高代码被合并的概率。

开始你的开源贡献之旅吧！ 🎉