← ドキュメント一覧/ガイド

NPM パッケージ公開ガイド

NPM パッケージ公開ガイド

概要

Miyabi CLI パッケージを npm レジストリに公開する手順を説明します。バージョニング、テスト、公開、アナウンスまでの完全なワークフローを学びます。

対象読者

  • パッケージメンテナー
  • リリースマネージャー
  • コアコントリビューター

所要時間

  • 読了時間: 15 分
  • 実行時間: 20-30 分（初回）

前提知識

  • npm の基礎知識
  • セマンティックバージョニングの理解
  • Git タグの知識
  • GitHub Releases の基本

事前準備

必須要件

# npm アカウント
# https://www.npmjs.com/signup で作成

# npm 認証
npm login
# Username:
# Password:
# Email: (this IS public)

# 認証確認
npm whoami
# → あなたのユーザー名が表示される

# パッケージビルド
cd packages/cli
npm run build

# dist/ ディレクトリの確認
ls -la dist/
# → index.js, index.d.ts, package.json などが存在

公開前チェックリスト

1. package.json の確認

{
  "name": "miyabi",
  "version": "2.0.0",
  "description": "AI-powered autonomous development environment",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
    "miyabi": "dist/cli.js"
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ],
  "keywords": [
    "ai",
    "agents",
    "automation",
    "github",
    "devops",
    "cli"
  ],
  "author": "Miyabi Team",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/ShunsukeHayashi/miyabi_doc.git"
  },
  "bugs": {
    "url": "https://github.com/ShunsukeHayashi/miyabi_doc/issues"
  },
  "homepage": "https://github.com/ShunsukeHayashi/miyabi_doc#readme"
}

2. ビルドとテスト

cd packages/cli

# 依存関係のインストール
npm ci

# ビルド
npm run build

# TypeScript チェック
npm run typecheck

# Lint
npm run lint

# テスト実行
npm test

# すべて成功を確認

3. 公開ファイルの確認

# 公開されるファイルを確認（ドライラン）
npm pack --dry-run

# 出力例:
# npm notice 📦  miyabi@2.0.0
# npm notice === Tarball Contents ===
# npm notice 1.2kB  package.json
# npm notice 5.4kB  README.md
# npm notice 1.1kB  LICENSE
# npm notice 150kB  dist/index.js
# npm notice 3.2kB  dist/index.d.ts
# npm notice === Tarball Details ===
# npm notice name:          miyabi
# npm notice version:       2.0.0
# npm notice filename:      miyabi-2.0.0.tgz
# npm notice package size:  45.2 kB
# npm notice unpacked size: 160.9 kB
# npm notice total files:   5

4. ローカルテスト

# グローバルリンク
npm link

# 動作確認
miyabi --help
miyabi --version

# テストプロジェクトで試す
cd /tmp
miyabi init test-project
cd test-project
npm install

# リンク解除
npm unlink -g miyabi

公開手順

ステップ 1: バージョニング

cd packages/cli

# パッチバージョン: 2.0.0 → 2.0.1
npm version patch

# マイナーバージョン: 2.0.1 → 2.1.0
npm version minor

# メジャーバージョン: 2.1.0 → 3.0.0
npm version major

# プレリリース: 2.0.0 → 2.0.0-beta.0
npm version prerelease --preid=beta

# カスタムバージョン
npm version 2.0.0

ステップ 2: 公開

# 初回公開（パブリックパッケージとして）
npm publish --access public

# 以降の公開
npm publish

# ベータ版の公開
npm publish --tag beta

# 成功メッセージ:
# npm notice
# npm notice 📦  miyabi@2.0.0
# npm notice === Tarball Details ===
# npm notice name:          miyabi
# npm notice version:       2.0.0
# npm notice filename:      miyabi-2.0.0.tgz
# npm notice package size:  45.2 kB
# npm notice unpacked size: 160.9 kB
# npm notice shasum:        abc123...
# npm notice integrity:     sha512-xyz...
# npm notice total files:   5
# npm notice
# + miyabi@2.0.0

ステップ 3: 公開確認

# npm レジストリで確認
open https://www.npmjs.com/package/miyabi

# インストールテスト
npx miyabi@latest --version

# または
npm install -g miyabi@latest
miyabi --version

GitHub Release の作成

Git タグの作成

# 現在のバージョンをタグ付け
git tag v2.0.0

# タグをプッシュ
git push origin v2.0.0

# または npm version 時に自動作成される
npm version patch --git-tag-version

GitHub Release の作成

# GitHub CLI で Release 作成
gh release create v2.0.0 \
  --title "v2.0.0 - Feature Release" \
  --notes "$(cat <<'EOF'
## 新機能

- ✨ 新しい Agent アーキテクチャ
- 🚀 並行実行の改善
- 📊 詳細なレポート機能

## 改善

- ⚡ パフォーマンス最適化
- 🐛 バグ修正
- 📚 ドキュメント更新

## インストール

\`\`\`bash
npx miyabi init my-project
\`\`\`

## 変更内容の詳細

- #123 Add new coordinator agent
- #124 Improve parallel execution
- #125 Add detailed reporting

## アップグレード方法

\`\`\`bash
npm install -g miyabi@latest
\`\`\`

---

🤖 Generated with Claude Code
EOF
  )"

アナウンス

README バッジの更新

<!-- Root README.md に追加 -->

[![NPM Version](https://img.shields.io/npm/v/miyabi)](https://www.npmjs.com/package/miyabi)
[![NPM Downloads](https://img.shields.io/npm/dm/miyabi)](https://www.npmjs.com/package/miyabi)
[![License](https://img.shields.io/npm/l/miyabi)](https://github.com/ShunsukeHayashi/miyabi_doc/blob/main/LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/ShunsukeHayashi/miyabi_doc)](https://github.com/ShunsukeHayashi/miyabi_doc)

Twitter/X でのアナウンス

🚀 Miyabi v2.0.0 がリリースされました！

✨ 新機能:
- 新しい Agent アーキテクチャ
- 並行実行の大幅改善
- 詳細なレポート機能

今すぐ試す:
npx miyabi init my-project

詳細: https://www.npmjs.com/package/miyabi

#AI #Agents #DevOps #GitHub #Automation

GitHub Discussions でのアナウンス

# 🎉 Miyabi v2.0.0 リリース

Miyabi v2.0.0 を公開しました！

## 主な新機能

### 1. 新しい Agent アーキテクチャ
- CoordinatorAgent の強化
- より効率的なタスク分解
- 改善された依存関係管理

### 2. 並行実行の改善
- 最大 5 倍の高速化
- スマートなロック管理
- デッドロック検出

### 3. 詳細なレポート
- JSON/HTML レポート
- 実行時間の可視化
- エラー分析

## インストール

\`\`\`bash
# 新規プロジェクト
npx miyabi init my-project

# 既存プロジェクト
npx miyabi install

# グローバルインストール
npm install -g miyabi@latest
\`\`\`

## アップグレード

\`\`\`bash
npm install -g miyabi@latest
\`\`\`

## フィードバック

バグ報告や機能要望は [Issues](https://github.com/ShunsukeHayashi/miyabi_doc/issues) までお願いします！

トラブルシューティング

エラー 1: パッケージ名が使用済み

症状:

npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/miyabi
npm ERR! You do not have permission to publish "miyabi". Are you logged in as the correct user?

解決方法:

# パッケージ名を変更
# package.json の name を変更:
# "name": "@miyabi-team/miyabi"
# または
# "name": "miyabi-cli"

# npm login を確認
npm whoami

# 再度公開
npm publish --access public

エラー 2: 402 Payment Required

症状:

npm ERR! 402 Payment Required

解決方法:

# メール認証が必要
npm profile get

# "email verified" を確認
# 未確認の場合、npm から送られたメールで認証

# 認証後、再度公開
npm publish --access public

エラー 3: 403 Forbidden

症状:

npm ERR! 403 Forbidden
npm ERR! You must verify your email to publish packages

解決方法:

# 認証状態を確認
npm whoami

# ログアウト＆再ログイン
npm logout
npm login

# メール認証を完了

# 再度公開
npm publish

エラー 4: バージョンが既に存在

症状:

npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/miyabi
npm ERR! You cannot publish over the previously published versions: 2.0.0

解決方法:

# バージョンを更新
npm version patch  # 2.0.0 → 2.0.1

# 再度公開
npm publish

バージョニング戦略

セマンティックバージョニング

versioning:
  format: "MAJOR.MINOR.PATCH"

  major:
    increment_when: "破壊的変更"
    examples:
      - API の削除
      - CLI コマンドの変更
      - 設定フォーマットの変更

  minor:
    increment_when: "新機能追加（後方互換）"
    examples:
      - 新しい Agent の追加
      - 新しい CLI コマンド
      - 新しいオプション

  patch:
    increment_when: "バグ修正"
    examples:
      - バグ修正
      - ドキュメント更新
      - パフォーマンス改善

バージョン例

# 初回リリース
1.0.0 - Initial stable release

# パッチ（バグ修正）
1.0.1 - Fix authentication bug
1.0.2 - Fix CLI command error

# マイナー（機能追加）
1.1.0 - Add ReviewAgent
1.2.0 - Add deployment automation

# メジャー（破壊的変更）
2.0.0 - New Agent architecture (breaking changes)
3.0.0 - Complete CLI redesign

公開の取り消し

Unpublish（72時間以内のみ）

# 特定のバージョンを削除（72時間以内）
npm unpublish miyabi@2.0.0

# パッケージ全体を削除（危険！）
npm unpublish miyabi --force

⚠️ 警告: Unpublish は依存している他のプロジェクトを壊す可能性があります。

Deprecate（推奨）

# 特定のバージョンを非推奨に
npm deprecate miyabi@2.0.0 "Critical bugs. Please upgrade to 2.0.1"

# 範囲指定
npm deprecate miyabi@"< 2.0.0" "Old version. Please upgrade to latest"

# 非推奨を取り消し
npm deprecate miyabi@2.0.0 ""

自動化

GitHub Actions での自動公開

# .github/workflows/publish.yml
name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

      - name: Publish
        run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

関連ドキュメント

参考リンク

次のステップ

  1. リリースノート を作成する
  2. アナウンス を計画する
  3. フィードバック を収集する

最終更新: 2025-10-10 バージョン: 2.0.0 ソース: NPM_PUBLICATION.md メンテナー: Miyabi Release Team

← ドキュメント一覧ホームへ →