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 エージェントがパッケージとどのように連携するかを記載します

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

重要：setup.sh はプレースホルダー値を使用するため、手順 5～7 は必須です。