create-new-bun-package-repo

创建新的 Bun 软件包仓库

从 zenobi-us/bun-module 模板仓库创建新的 Bun 软件包的专家指南。使用 GitHub CLI 自动创建仓库、克隆并完成设置。重要：设置过程使用默认值运行（不会显示交互式提示）。

概述

本指南提供使用 bun-module 模板引导创建新 Bun 软件包的完整工作流。模板包含 TypeScript 配置、测试设置和标准化的模块结构。此工作流通过 GitHub CLI 创建仓库、克隆仓库，并运行会自动应用默认值的设置脚本。

适用场景

适用于：

• 创建新的 Bun TypeScript 软件包或库
• 启动新的 Bun 模块项目
• 需要在各项目间保持一致的软件包结构
• 希望使用 Bun 模板自动设置 GitHub 仓库

不适用于：

• 非 Bun 项目（请使用相应模板）
• 现有仓库（此模板用于新项目）
• 不需要 TypeScript 或测试基础设施的项目

重要限制：设置脚本以非交互方式运行——创建后必须手动编辑 package.json，设置正确的名称、描述和作者信息。

快速参考

步骤	命令	用途
1. 创建仓库	gh repo create OWNER/NAME --template zenobi-us/bun-module --public --clone	从模板创建
2. 转到仓库目录	cd NAME	进入仓库目录
3. 设置	bash setup.sh	运行交互式设置

完整工作流

检查先决条件

开始前，请确认：

# GitHub CLI installed and authenticated
gh auth status

# Bun installed (required for setup.sh)
bun --version

分步流程

1. 收集信息

向用户询问：

• 所有者：GitHub 用户名或组织名称（例如，zenobi-us）
• 仓库名称：新仓库的名称（例如，my-awesome-module）
• 可见性：公开或私有（默认：公开）

2. 从模板创建仓库

# Public repository (recommended for open source)
gh repo create OWNER/REPO-NAME \
  --template zenobi-us/bun-module \
  --public \
  --clone

# Private repository (if needed)
gh repo create OWNER/REPO-NAME \
  --template zenobi-us/bun-module \
  --private \
  --clone

--clone 标志会在创建后自动克隆仓库。

3. 转到仓库目录

cd REPO-NAME

4. 运行设置脚本

bash setup.sh

设置脚本将：

• 将模板文件应用到当前目录
• 使用默认值替换模板变量
• 删除旧的 Git 历史记录和模板文件
• 初始化全新的 Git 仓库
• 创建初始提交
• 尝试推送到远程（如果仓库刚刚创建，可能会失败）

注意：脚本以非交互方式运行，并使用以下默认值：

• 软件包名称：my-bun-package
• 描述：A Bun package
• 作者：Your Name <[email protected]>
• 仓库 URL：从 Git 远程仓库检测（通常正确）

设置后必须手动编辑 package.json，更正这些值。

5. 手动更新 package.json

设置脚本使用默认值，因此必须编辑 package.json：

# Edit package.json - update these fields:
# - name: Change from "my-bun-package" to your actual name
# - description: Update to your package's description
# - author.name: Your actual name
# - author.email: Your actual email

6. 信任 mise 配置

# Required before running mise tasks
mise trust

7. 安装依赖并构建

# Install dependencies
bun install

# Build the package
mise run build

# Verify build succeeded
ls -la dist/

8. 提交更新

# Stage package.json changes
git add package.json

# Commit your customizations
git commit -m "chore: update package metadata"

# Push to remote
git push -u origin main

命令选项

GitHub CLI 仓库创建

gh repo create [<owner>/]<name> [flags]

主要标志：

• --template OWNER/REPO：使用指定仓库作为模板
• --public：创建公开仓库（使用模板时的默认值）
• --private：创建私有仓库
• --clone：创建后克隆仓库
• --description DESC：仓库描述
• --homepage URL：仓库主页 URL

示例：

# Minimal - public, auto-clone
gh repo create zenobi-us/new-module \
  --template zenobi-us/bun-module \
  --public \
  --clone

# With metadata
gh repo create zenobi-us/new-module \
  --template zenobi-us/bun-module \
  --public \
  --clone \
  --description "My awesome Bun module" \
  --homepage "https://example.com"

# Organization repository
gh repo create my-org/new-module \
  --template zenobi-us/bun-module \
  --public \
  --clone

模板仓库结构

zenobi-us/bun-module 模板提供：

• TypeScript 配置：预配置的 tsconfig.json
• Mise 集成：包含构建、测试和格式化任务的任务运行器
• 测试：Vitest 测试基础设施
• 软件包配置：包含默认值的起始版 package.json
• 构建工具：使用 Bun 的打包器进行打包
• 发布自动化：用于自动发布的 Release Please 配置
• 文档：README 模板、AGENTS.md、RELEASE.md
• 代码检查：已配置 ESLint 和 Prettier
• GitHub Actions：预配置的 CI/CD 工作流

设置脚本行为

setup.sh 脚本会以这些默认值非交互式运行：

字段	默认值	更新位置
包名称	my-bun-package	package.json → name
描述	A Bun package	package.json → description
作者姓名	Your Name	package.json → author.name
作者邮箱	[email protected]	package.json → author.email
仓库 URL	自动从 git remote 检测	通常正确，请在 package.json → repository.url 中确认
GitHub 组织	username	不会存储，仅在设置过程中使用

运行 setup.sh 后，必须手动编辑 package.json，将这些值更新为实际的项目详情。

常见工作流

创建 Bun 包

# 1. Create repository from template
gh repo create zenobi-us/my-bun-package \
  --template zenobi-us/bun-module \
  --public \
  --clone \
  --description "My awesome Bun package"

# 2. Navigate to directory
cd my-bun-package

# 3. Run setup (applies defaults)
bash setup.sh

# 4. Edit package.json manually
# Update: name, description, author.name, author.email

# 5. Trust mise and build
mise trust
bun install
mise run build

# 6. Commit and push
git add package.json
git commit -m "chore: update package metadata"
git push -u origin main

组织包

# Create under organization
gh repo create my-org/shared-package \
  --template zenobi-us/bun-module \
  --public \
  --clone \
  --description "Shared Bun package for organization"

cd shared-package
bash setup.sh

# Edit package.json with org-scoped name:
# name: "@my-org/shared-package"
# ...

mise trust
bun install
mise run build
git add package.json
git commit -m "chore: update package metadata"
git push -u origin main

私有包

# Create private repository
gh repo create zenobi-us/internal-package \
  --template zenobi-us/bun-module \
  --private \
  --clone \
  --description "Internal Bun package"

cd internal-package
bash setup.sh

# Edit package.json as needed
# ...

mise trust
bun install
mise run build
git add package.json
git commit -m "chore: update package metadata"
git push -u origin main

故障排除

模板仓库未标记为模板

问题： Could not clone: zenobi-us/bun-module is not a template repository

解决方案：

# Mark repository as template
gh repo edit zenobi-us/bun-module --template

# Verify it's now a template
gh repo view zenobi-us/bun-module --json isTemplate

GitHub CLI 身份验证

问题： gh: Not authenticated

解决方案：

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

未找到模板

问题： repository not found: zenobi-us/bun-module

解决方案：

• 确认模板仓库存在且可访问
• 检查 owner/repo 拼写是否正确
• 确保模板仓库是公开的，或你有权访问

设置脚本失败

问题： setup.sh: command not found 或脚本报错

解决方案：

# Verify file exists
ls -la setup.sh

# Make executable if needed
chmod +x setup.sh

# Run with bash explicitly
bash setup.sh

# Check Bun is installed
bun --version

需要信任 mise

问题： Config files in [...] are not trusted

解决方案：

# Trust the mise configuration
mise trust

# Now run mise tasks
mise run build

克隆目录已存在

问题： destination path 'repo-name' already exists

解决方案：

# Choose different name or remove existing directory
rm -rf repo-name

# Or use --clone flag without specifying directory
gh repo create owner/repo-name --template ... --clone

设置后构建失败

问题： 构建失败或缺少依赖

解决方案：

# Ensure dependencies are installed
bun install

# Trust mise config if not done
mise trust

# Try build again
mise run build

# Check for specific errors
mise run build --verbose

设置后的后续步骤

成功完成设置并更新 package.json 后：

1. 检查 package.json：确保所有字段都正确

   cat package.json | jq '.name, .description, .author'
   

2. 安装依赖：

   bun install
   

3. 信任 mise 并构建：

   mise trust
   mise run build
   

4. 检查构建输出：

   ls -la dist/
   # Should see: index.js, index.d.ts
   

5. 运行测试（如果有）：

   mise run test
   

6. 提交自定义内容：

   git add package.json
   git commit -m "chore: update package metadata"
   git push origin main
   

7. 更新 README：用实际文档替换模板内容

8. 更新 AGENTS.md：说明 AI Agent 应如何与包交互

9. 配置 CI/CD：检查并自定义 .github/workflows/ 中的 GitHub Actions 工作流

10. 开始开发：在 src/ 中开始实现包

与其他工具集成

与 mise 集成

# Pin Bun version in project
mise use bun@latest

# Add to mise.toml tasks
[tasks]
setup = "bash setup.sh"
test = "bun test"
build = "bun run build"

与 Git 工作流集成

# Create feature branch immediately
git checkout -b feat/initial-implementation

# Set up pre-commit hooks
bun add -D husky lint-staged

与包管理器集成

此模板兼容：

• Bun（主要）：bun install、bun add
• npm（兼容）：npm install 可用，但推荐使用 Bun
• pnpm（兼容）：pnpm install 可作为备用方案

最佳实践

1. 首次使用时标记模板仓库：使用 gh repo edit --template
2. 使用描述性仓库名称：选择能清楚表明用途的名称
3. 为包名称添加作用域：使用 @scope/name，以明确名称和命名空间归属
4. 立即更新 package.json：别忘了在 setup.sh 运行后进行编辑
5. 构建前信任 mise：运行 mise 任务时必须执行
6. 分别提交元数据更新：将设置提交与元数据提交分开
7. 设置后立即测试：确认 mise run build 成功
8. 尽早更新文档：用实际内容替换模板占位内容
9. 有意配置可见性：开源项目设为公开，内部项目设为私有
10. 检查生成的文件：确保 AGENTS.md、README.md 和工作流符合需求

已知限制

1. 非交互式设置：setup.sh 脚本不会提示输入；它会使用默认值，你必须在之后手动更新 package.json
2. 需要手动编辑 package.json：运行 setup.sh 后，你必须编辑 name、description 和 author 字段
3. 不进行验证：脚本不会验证你对 package.json 所做的手动修改
4. 需要信任 Mise：运行任务前，你必须明确表示信任 mise 配置

快速入门摘要

完整工作流的命令：

# 1. Ensure template repo is marked as template (one-time setup)
gh repo edit zenobi-us/bun-module --template

# 2. Create and clone from template
gh repo create OWNER/NAME \
  --template zenobi-us/bun-module \
  --public \
  --clone \
  --description "Your plugin description"

# 3. Enter directory
cd NAME

# 4. Run setup (uses defaults)
bash setup.sh

# 5. Edit package.json manually - UPDATE THESE:
#    - name: "my-bun-package" → "@owner/actual-name"
#    - description: "A Bun package" → "Your description"
#    - author.name: "Your Name" → Your actual name
#    - author.email: "[email protected]" → Your actual email

# 6. Trust mise, install, and build
mise trust
bun install
mise run build

# 7. Commit updates and push
git add package.json
git commit -m "chore: update package metadata"
git push -u origin main

重要：第 5–7 步为必需步骤，因为 setup.sh 使用的是占位值。