npm-package-comparator

npm パッケージ比較ツール

npm、GitHub、Bundlephobia、Snyk の最新データを使って、任意の npm パッケージを並べて比較し、実際のニーズに基づいた明確な推奨を提示します。

事前確認（必須）

TinyFish を呼び出す前に、必ず以下の両方を確認してください。

1. CLI がインストールされているか？

which tinyfish && tinyfish --version || echo "TINYFISH_CLI_NOT_INSTALLED"

インストールされていない場合は、処理を中止してユーザーに伝えてください。

TinyFish CLI をインストールしてください：npm install -g @tiny-fish/cli

2. 認証済みか？

tinyfish auth status

認証されていない場合は、処理を中止してユーザーに伝えてください。

TinyFish API キーが必要です。こちらから取得してください：https://agent.tinyfish.ai/api-keys

次に、認証します。

tinyfish auth login

両方の確認に合格するまで、処理を進めないでください。

---

ステップ 1 — 入力を収集する

以下が必要です。

• パッケージ名 — 比較するパッケージを 2〜4 個（例：zustand、jotai、redux）
• ユースケース（任意ですが、推奨内容の質が向上します）— 例：「小規模な React アプリ」「大規模なエンタープライズコードベース」「SSR サポートが必要」

ユーザーがユースケースを指定していない場合は、次のように尋ねてください。

「これを使って何を作る予定ですか？（例：小規模な個人プロジェクト、大規模なチームのコードベース、パフォーマンスが重要なアプリ）」

ユーザーがわからない場合は、ユースケースなしで進め、一般的な推奨を提示してください。

---

ステップ 2 — データを並列取得する

各パッケージについて、npm、GitHub、Bundlephobia、Snyk にまたがってエージェントを同時に実行します。すべてのパッケージについて、すべてのエージェントを並列で実行してください（ソースごとに、パッケージ 1 つにつきエージェント 1 つ）。

# ── For each PACKAGE, run all 4 agents in parallel ───────────

# npm stats
tinyfish agent run \
  --url "https://www.npmjs.com/package/{PACKAGE}" \
  "You are on the npm page for the package {PACKAGE}.
   Extract:
   - current version
   - weekly downloads (exact number shown)
   - total downloads if shown
   - last publish date
   - license
   - number of dependencies
   - TypeScript support (yes/no — check if types are listed)
   - maintainers count
   - repository URL
   STRICT RULES:
   - Do NOT click any links
   - Read only what is visible on this page
   - If a field is not shown, return null
   Return JSON: {package, version, weekly_downloads, last_published, license, dependency_count, typescript_support, maintainer_count, repo_url}" \
  --sync > /tmp/npm_{PACKAGE_SAFE}.json &

# GitHub stats
tinyfish agent run \
  --url "https://github.com/{OWNER}/{REPO}" \
  "You are on the GitHub repository page for {PACKAGE}.
   Extract:
   - star count
   - fork count
   - open issues count
   - last commit date
   - number of contributors (from sidebar or Insights)
   - latest release tag and date
   - whether the repo is actively maintained (check: last commit within 6 months)
   STRICT RULES:
   - Do NOT click any tabs or links
   - Read only what is visible on the main repo page
   Return JSON: {package, stars, forks, open_issues, last_commit, contributors, latest_release, latest_release_date, is_active}" \
  --sync > /tmp/gh_{PACKAGE_SAFE}.json &

# Bundle size
tinyfish agent run \
  --url "https://bundlephobia.com/package/{PACKAGE}" \
  "You are on the Bundlephobia page for {PACKAGE}.
   Extract:
   - minified size (in KB)
   - minified + gzipped size (in KB)
   - download time on slow 3G (if shown)
   - tree-shakeable (yes/no)
   - side-effect free (yes/no)
   STRICT RULES:
   - Do NOT click any links
   - Read only what is visible on this page
   - If the page hasn't loaded sizes yet, note it
   Return JSON: {package, minified_kb, gzipped_kb, tree_shakeable, side_effect_free}" \
  --sync > /tmp/bp_{PACKAGE_SAFE}.json &

# Known vulnerabilities
tinyfish agent run \
  --url "https://security.snyk.io/package/npm/{PACKAGE}" \
  "You are on the Snyk security page for the npm package {PACKAGE}.
   Extract:
   - total number of known vulnerabilities
   - number by severity: critical, high, medium, low
   - most recent vulnerability title and date (if shown)
   STRICT RULES:
   - Do NOT click any vulnerability links
   - Read only the summary visible on this page
   - If the page shows 'no vulnerabilities', return {total: 0}
   Return JSON: {package, total_vulns, critical, high, medium, low, latest_vuln_title, latest_vuln_date}" \
  --sync > /tmp/snyk_{PACKAGE_SAFE}.json &

# Repeat the above 4 agents for each additional package
# All backgrounded with & — fire everything at once then:
wait

# Collect all results
for p in {PACKAGE_LIST}; do
  echo "=== $p ===" 
  cat /tmp/npm_${p}.json
  cat /tmp/gh_${p}.json
  cat /tmp/bp_${p}.json
  cat /tmp/snyk_${p}.json
done

実行する前に、次の項目を置き換えてください。

• {PACKAGE} — 正確な npm パッケージ名。例：zustand
• {PACKAGE_SAFE} — 安全にファイル名として使える形式。例：zustand
• {OWNER}/{REPO} — GitHub リポジトリ。例：pmndrs/zustand
• {PACKAGE_LIST} — すべてのパッケージをスペース区切りにしたリスト

よく知られたパッケージについては、正しい GitHub リポジトリを知識に基づいて特定してください。知らないパッケージの場合は、まず npm ページの repository フィールドを確認してください。

---

ステップ 3 — 比較をまとめる

すべてのデータをまとめて、横並びの比較を作成します。

## Package Comparison: {PACKAGE_1} vs {PACKAGE_2} vs ...

*Data fetched live — {date}*

---

### 📊 At a Glance

| | {pkg1} | {pkg2} | {pkg3} |
|---|---|---|---|
| **Version** | {v} | {v} | {v} |
| **Weekly Downloads** | {n} | {n} | {n} |
| **GitHub Stars** | {n} | {n} | {n} |
| **Bundle (gzipped)** | {n}kb | {n}kb | {n}kb |
| **Tree-shakeable** | ✅/❌ | ✅/❌ | ✅/❌ |
| **TypeScript** | ✅/❌ | ✅/❌ | ✅/❌ |
| **Last Published** | {date} | {date} | {date} |
| **Known Vulns** | {n} | {n} | {n} |
| **License** | {l} | {l} | {l} |

---

### 📈 Popularity & Health

{2-3 sentences comparing download trends, GitHub activity, and community size}

---

### 📦 Bundle Size

{Comparison of bundle impact — important for frontend packages}
{Flag if any package is significantly larger than alternatives}

---

### 🔒 Security

{Note any packages with known vulnerabilities}
{If all clean: "No known vulnerabilities found for any of these packages."}

---

### ⚙️ Maintenance

{Compare last commit dates, contributor counts, release cadence}
{Flag any package that looks abandoned (no commits in 12+ months)}

---

### 🎯 Recommendation

{Use case}: {user's stated use case or "general use"}

**Best pick: {PACKAGE}**

{2-3 sentences explaining why this package wins for this use case, and what trade-offs you're making}

**When to pick {PACKAGE_2} instead:**
{1-2 sentences on when the runner-up is the better choice}

**Avoid {PACKAGE_3} if:**
{Any specific reasons to avoid a package in certain contexts}

---

例外的なケース

• パッケージが npm にない — GitHub のみで公開されているパッケージか確認し、リポジトリを直接スクレイピングします
• Bundlephobia に掲載されていない — 「バンドルサイズは取得できません」と記載し、その行は省略します
• npm ページから GitHub リポジトリが見つからない — https://github.com/search?q={PACKAGE}&type=repositories を検索して、正式なリポジトリを見つけます
• パッケージのいずれかが非推奨になっている — 比較の冒頭で明確に注意を促します：「⚠️ {package} は非推奨です — メンテナーは {replacement} を推奨しています」
• 4 個を超えるパッケージを比較する — 意味のある比較が難しくなるため、ユーザーに候補を上位 3 個に絞るよう依頼します
• パッケージの用途が少し異なる — 比較の前にその違いを説明します（例：「react-query はサーバー状態を扱い、zustand はクライアント状態を扱います。実際には両方必要な場合があります」）