create-new-bun-package-repo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create New Bun Package Repository

创建新的Bun包仓库

Expert guide for creating new Bun packages from the zenobi-us/bun-module template repository. Automates repository creation, cloning, and setup using GitHub CLI. Important: Setup runs with defaults (not interactive prompts).

本指南详细介绍如何从zenobi-us/bun-module模板仓库创建新的Bun包。借助GitHub CLI自动化仓库创建、克隆和设置流程。重要提示：设置流程使用默认值运行（无交互式提示）。

Overview

概述

This skill provides a complete workflow for bootstrapping new Bun packages using the bun-module template. The template includes TypeScript configuration, testing setup, and standardized module structure. The workflow handles repository creation via GitHub CLI, cloning, and running the setup script which applies defaults automatically.

本技能提供了使用bun-module模板快速搭建新Bun包的完整工作流。该模板包含TypeScript配置、测试设置和标准化的模块结构。工作流通过GitHub CLI处理仓库创建、克隆，并运行设置脚本自动应用默认配置。

When to Use

适用场景

Use when:

Creating a new Bun TypeScript package or library
Starting a new Bun module project
Need consistent package structure across projects
Want automated GitHub repo setup with Bun template

Don't use for:

Non-Bun projects (use appropriate template)
Existing repositories (template is for new projects)
Projects not requiring TypeScript or testing infrastructure

Important Limitation: Setup script runs non-interactively - you must manually edit

package.json

after creation to set correct name, description, and author details.

适用情况：

创建新的Bun TypeScript包或库
启动新的Bun模块项目
需要在多个项目中保持一致的包结构
希望通过Bun模板自动化GitHub仓库设置

不适用情况：

非Bun项目（请使用对应模板）
已有仓库（本模板仅适用于新项目）
不需要TypeScript或测试基础设施的项目

重要限制：设置脚本以非交互式方式运行 - 创建完成后，你必须手动编辑

package.json

以设置正确的名称、描述和作者信息。

Quick Reference

快速参考

Step	Command	Purpose
1. Create repo	`gh repo create OWNER/NAME --template zenobi-us/bun-module --public --clone`	Create from template
2. Navigate	`cd NAME`	Enter repo directory
3. Setup	`bash setup.sh`	Run interactive setup

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

Complete Workflow

完整工作流

Prerequisites Check

前置检查

Before starting, verify:

bash

undefined

开始前，请验证以下内容：

bash

undefined

GitHub CLI installed and authenticated

检查GitHub CLI是否已安装并完成认证

gh auth status

Bun installed (required for setup.sh)

检查Bun是否已安装（setup.sh运行必需）

bun --version

undefined

bun --version

undefined

Step-by-Step Process

分步流程

1. Gather Information

Ask the user for:

Owner: GitHub username or organization (e.g.,
```
zenobi-us
```
)
Repo name: New repository name (e.g.,
```
my-awesome-module
```
)
Visibility: Public or private (default: public)

2. Create Repository from Template

bash

undefined

1. 收集信息

请确认以下信息：

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

2. 从模板创建仓库

bash

undefined

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


The `--clone` flag automatically clones after creation.

**3. Navigate to Repository**

```bash
cd REPO-NAME

4. Run Setup Script

bash

bash setup.sh

The setup script will:

Apply template files to current directory
Replace template variables with defaults
Remove old git history and template files
Initialize fresh git repository
Create initial commit
Attempt to push to remote (may fail if repo just created)

Note: The script runs non-interactively and uses these defaults:

Package name:
```
my-bun-package
```
Description:
```
A Bun package
```
Author:
```
Your Name <you@example.com>
```
Repository URL: Detected from git remote (usually correct)

You must manually edit
package.json
after setup to correct these values.

5. Update package.json Manually

The setup script uses defaults, so you must edit

package.json

bash

undefined

gh repo create OWNER/REPO-NAME
--template zenobi-us/bun-module
--private
--clone


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

**3. 进入仓库目录**

```bash
cd REPO-NAME

4. 运行设置脚本

bash

bash setup.sh

设置脚本将执行以下操作：

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

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

包名称：
```
my-bun-package
```
描述：
```
A Bun package
```
作者：
```
Your Name <you@example.com>
```
仓库URL：从Git远程仓库自动检测（通常正确）

**设置完成后，你必须手动编辑

package.json

**来修正这些值。

5. 手动更新package.json

设置脚本使用默认值，因此你需要编辑

package.json

：

bash

undefined

Edit package.json - update these fields:

编辑package.json - 更新以下字段：

- name: Change from "my-bun-package" to your actual name

- name: 将"my-bun-package"改为实际的包名称

- description: Update to your package's description

- description: 更新为你的包的描述

- author.name: Your actual name

- author.name: 你的真实姓名

- author.email: Your actual email

- author.email: 你的真实邮箱


**6. Trust mise Configuration**

```bash


**6. 信任mise配置**

```bash

Required before running mise tasks

运行mise任务前需要执行此步骤

mise trust


**7. Install Dependencies and Build**

```bash

mise trust


**7. 安装依赖并构建**

```bash

Install dependencies

安装依赖

bun install

Build the package

构建包

mise run build

Verify build succeeded

验证构建是否成功

ls -la dist/


**8. Commit Updates**

```bash

ls -la dist/


**8. 提交更新**

```bash

Stage package.json changes

暂存package.json的更改

git add package.json

Commit your customizations

提交自定义更改

git commit -m "chore: update package metadata"

Push to remote

推送到远程仓库

git push -u origin main

undefined

git push -u origin main

undefined

Command Options

命令选项

GitHub CLI Repository Creation

GitHub CLI仓库创建

bash

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

Key flags:

```
--template OWNER/REPO
```
: Use repository as template
```
--public
```
: Create public repository (default if using template)
```
--private
```
: Create private repository
```
--clone
```
: Clone repository after creation
```
--description DESC
```
: Repository description
```
--homepage URL
```
: Repository homepage URL

Examples:

bash

undefined

bash

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

关键标志：

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

示例：

bash

undefined

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

undefined

gh repo create my-org/new-module
--template zenobi-us/bun-module
--public
--clone

undefined

Template Repository Structure

模板仓库结构

The

zenobi-us/bun-module

template provides:

TypeScript configuration: Preconfigured
```
tsconfig.json
```
Mise integration: Task runner with build, test, format tasks
Testing: Vitest test infrastructure
Package configuration: Starter
```
package.json
```
with defaults
Build tooling: Bundling with Bun's bundler
Release automation: Release Please configuration for automated releases
Documentation: README template, AGENTS.md, RELEASE.md
Linting: ESLint and Prettier configured
GitHub Actions: CI/CD workflows preconfigured

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 Script Behavior

设置脚本行为

The

setup.sh

script runs non-interactively with these defaults:

Field	Default Value	Where to Update
Package name	`my-bun-package`	`package.json` → `name`
Description	`A Bun package`	`package.json` → `description`
Author name	`Your Name`	`package.json` → `author.name`
Author email	`you@example.com`	`package.json` → `author.email`
Repository URL	Auto-detected from git remote	Usually correct, verify in `package.json` → `repository.url`
GitHub org	`username`	Not stored, used during setup only

After running setup.sh, you MUST manually edit
package.json
to update these values to your actual project details.

setup.sh

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

字段	默认值	编辑位置
包名称	`my-bun-package`	`package.json` → `name`
描述	`A Bun package`	`package.json` → `description`
作者姓名	`Your Name`	`package.json` → `author.name`
作者邮箱	`you@example.com`	`package.json` → `author.email`
仓库URL	从Git远程仓库自动检测	通常正确，可在 `package.json` → `repository.url` 中验证
GitHub组织	`username`	仅在设置期间使用，不存储

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

Common Workflows

常见工作流

Creating a Bun Package

创建Bun包

bash

undefined

bash

undefined

1. Create repository from template

1. 从模板创建仓库

gh repo create zenobi-us/my-bun-package
--template zenobi-us/bun-module
--public
--clone
--description "My awesome Bun package"

2. Navigate to directory

2. 进入目录

cd my-bun-package

3. Run setup (applies defaults)

3. 运行设置（应用默认值）

bash setup.sh

4. Edit package.json manually

4. 手动编辑package.json

Update: name, description, author.name, author.email

更新：name、description、author.name、author.email

5. Trust mise and build

5. 信任mise配置并构建

mise trust bun install mise run build

6. Commit and push

6. 提交并推送

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

undefined

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

undefined

Organization Package

组织级包

bash

undefined

bash

undefined

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

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:

编辑package.json，使用组织作用域的名称：

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

undefined

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

undefined

Private Package

私有包

bash

undefined

bash

undefined

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

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

根据需要编辑package.json

...

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

undefined

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

undefined

Troubleshooting

故障排除

Template Repository Not Marked as Template

模板仓库未标记为模板

Problem:

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

Solution:

bash

undefined

问题：

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

解决方案：

bash

undefined

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

undefined

gh repo view zenobi-us/bun-module --json isTemplate

undefined

GitHub CLI Authentication

GitHub CLI认证问题

Problem:

gh: Not authenticated

Solution:

bash

undefined

问题：

gh: Not authenticated

解决方案：

bash

undefined

Authenticate with GitHub

登录GitHub进行认证

gh auth login

Verify authentication

验证认证状态

gh auth status

undefined

gh auth status

undefined

Template Not Found

模板未找到

Problem:

repository not found: zenobi-us/bun-module

Solution:

Verify template repository exists and is accessible
Check spelling of owner/repo
Ensure template repository is public or you have access

问题：

repository not found: zenobi-us/bun-module

解决方案：

验证模板仓库是否存在且可访问
检查所有者/仓库名称的拼写
确保模板仓库是公开的，或者你有访问权限

Setup Script Fails

设置脚本运行失败

Problem:

setup.sh: command not found

or script errors

Solution:

bash

undefined

问题：

setup.sh: command not found

或脚本执行错误

解决方案：

bash

undefined

Verify file exists

验证文件是否存在

ls -la setup.sh

Make executable if needed

如有需要，添加可执行权限

chmod +x setup.sh

Run with bash explicitly

显式使用bash运行

bash setup.sh

Check Bun is installed

检查Bun是否已安装

bun --version

undefined

bun --version

undefined

Mise Trust Required

需要信任mise配置

Problem:

Config files in [...] are not trusted

Solution:

bash

undefined

问题：

Config files in [...] are not trusted

解决方案：

bash

undefined

Trust the mise configuration

信任mise配置

mise trust

Now run mise tasks

现在运行mise任务

mise run build

undefined

mise run build

undefined

Clone Directory Exists

克隆目录已存在

Problem:

destination path 'repo-name' already exists

Solution:

bash

undefined

问题：

destination path 'repo-name' already exists

解决方案：

bash

undefined

Choose different name or remove existing directory

选择不同的名称，或删除现有目录

rm -rf repo-name

Or use --clone flag without specifying directory

或者使用--clone标志，不指定目录

gh repo create owner/repo-name --template ... --clone

undefined

gh repo create owner/repo-name --template ... --clone

undefined

Build Fails After Setup

设置后构建失败

Problem: Build fails or dependencies missing

Solution:

bash

undefined

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

解决方案：

bash

undefined

Ensure dependencies are installed

确保依赖已安装

bun install

Trust mise config if not done

若未执行，信任mise配置

mise trust

Try build again

再次尝试构建

mise run build

Check for specific errors

查看具体错误

mise run build --verbose

undefined

mise run build --verbose

undefined

Post-Setup Next Steps

设置完成后的后续步骤

After successful setup and package.json updates:

Verify package.json: Ensure all fields are correct

bash

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

Install dependencies:
bash
```
bun install
```
Trust mise and build:
bash
```
mise trust
mise run build
```

Verify build output:

bash

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

Run tests (if any exist):
bash
```
mise run test
```

Commit customizations:

bash

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

Update README: Replace template content with actual documentation
Update AGENTS.md: Document how AI agents should interact with your package
Configure CI/CD: Review and customize GitHub Actions workflows in
```
.github/workflows/
```
Start development: Begin implementing your package in
```
src/
```

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

验证package.json：确保所有字段正确

bash

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

安装依赖：
bash
```
bun install
```
信任mise配置并构建：
bash
```
mise trust
mise run build
```

验证构建输出：

bash

ls -la dist/
# 应看到：index.js, index.d.ts

运行测试（如果存在）：
bash
```
mise run test
```

提交自定义更改：

bash

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

更新README：将模板内容替换为实际文档
更新AGENTS.md：记录AI Agents如何与你的包交互
配置CI/CD：查看并自定义
```
.github/workflows/
```
中的GitHub Actions工作流
开始开发：在
```
src/
```
目录中开始实现你的包

Integration with Other Tools

与其他工具的集成

With mise

与mise集成

bash

undefined

bash

undefined

Pin Bun version in project

在项目中固定Bun版本

mise use bun@latest

Add to mise.toml tasks

在mise.toml中添加任务

[tasks] setup = "bash setup.sh" test = "bun test" build = "bun run build"

undefined

[tasks] setup = "bash setup.sh" test = "bun test" build = "bun run build"

undefined

With Git Workflows

与Git工作流集成

bash

undefined

bash

undefined

Create feature branch immediately

立即创建特性分支

git checkout -b feat/initial-implementation

Set up pre-commit hooks

设置预提交钩子

bun add -D husky lint-staged

undefined

bun add -D husky lint-staged

undefined

With Package Managers

与包管理器集成

The template works with:

Bun (primary):
```
bun install
```
,
```
bun add
```
npm (compatible):
```
npm install
```
works but Bun recommended
pnpm (compatible):
```
pnpm install
```
works as fallback

该模板支持：

Bun（首选）：
```
bun install
```
,
```
bun add
```
npm（兼容）：
```
npm install
```
可用，但推荐使用Bun
pnpm（兼容）：
```
pnpm install
```
可作为备选

Best Practices

最佳实践

Mark template repo once: Use
```
gh repo edit --template
```
on first use
Use descriptive repo names: Choose names that clearly indicate purpose
Scope package names: Use
```
@scope/name
```
for clarity and namespace ownership
Update package.json immediately: Don't forget to edit after setup.sh runs
Trust mise before building: Required for running mise tasks
Commit metadata updates separately: Keep setup commit and metadata commit separate
Test immediately after setup: Verify
```
mise run build
```
passes
Update documentation early: Replace template placeholders with real content
Configure visibility intentionally: Public for open source, private for internal
Review generated files: Ensure AGENTS.md, README.md, and workflows fit your needs

仅标记一次模板仓库：首次使用时，使用
```
gh repo edit --template
```
标记模板仓库
使用描述性仓库名称：选择能清晰表明用途的名称
作用域包名称：使用
```
@scope/name
```
格式以确保清晰度和命名空间所有权
立即更新package.json：不要忘记在setup.sh运行后编辑该文件
构建前信任mise配置：运行mise任务必需
单独提交元数据更新：将设置提交与元数据提交分开
设置后立即测试：验证
```
mise run build
```
是否通过
尽早更新文档：将模板占位符替换为真实内容
有意配置可见性：开源项目用公开仓库，内部项目用私有仓库
审查生成的文件：确保AGENTS.md、README.md和工作流符合你的需求

Known Limitations

已知限制

Non-interactive setup: The setup.sh script doesn't prompt for input; it uses defaults that you must manually update in package.json afterward
Manual package.json editing required: You must edit name, description, and author fields after running setup.sh
No validation: The script doesn't validate your manual edits to package.json
Mise trust required: You must explicitly trust the mise configuration before running tasks

非交互式设置：setup.sh脚本不提供交互式输入，使用默认值，后续必须手动更新package.json
必须手动编辑package.json：运行setup.sh后，你需要手动更新名称、描述和作者字段
无验证机制：脚本不会验证你对package.json的手动编辑
需要信任mise配置：运行mise任务前必须显式信任配置

Quick Start Summary

快速启动总结

The complete workflow in commands:

bash

undefined

完整工作流的命令汇总：

bash

undefined

1. Ensure template repo is marked as template (one-time setup)

1. 确保模板仓库已标记为模板（仅需执行一次）

gh repo edit zenobi-us/bun-module --template

2. Create and clone from template

2. 从模板创建并克隆仓库

gh repo create OWNER/NAME
--template zenobi-us/bun-module
--public
--clone
--description "Your plugin description"

3. Enter directory

3. 进入目录

cd NAME

4. Run setup (uses defaults)

4. 运行设置（使用默认值）

bash setup.sh

5. Edit package.json manually - UPDATE THESE:

5. 手动编辑package.json - 更新以下内容：

- name: "my-bun-package" → "@owner/actual-name"

- description: "A Bun package" → "Your description"

- author.name: "Your Name" → Your actual name

- author.name: "Your Name" → 你的真实姓名

- author.email: "you@example.com" → Your actual email

- author.email: "you@example.com" → 你的真实邮箱

6. Trust mise, install, and build

6. 信任mise配置、安装依赖并构建

mise trust bun install mise run build

7. Commit updates and push

7. 提交更新并推送

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


**Critical**: Steps 5-7 are REQUIRED because setup.sh uses placeholder values.

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


**关键提示**：步骤5-7是必需的，因为setup.sh使用占位符值。