optimize-images

Web プロジェクト向け画像の最適化

最新のツールを使って、Web パフォーマンス向けに画像を最適化します。このスキルでは、視覚的な品質を維持しながら PNG と JPEG 画像を圧縮するためのスクリプトとワークフローを提供します。

このスキルを使うタイミング

• 本番環境の Web デプロイに向けて画像を準備するとき
• ページの読み込み時間を短縮するとき
• public/images ディレクトリを最適化するとき
• スクリーンショット、水彩画、写真を一括圧縮するとき
• 最適化の前後で画像サイズを監査するとき

コアツール：Sharp

Sharp は libvips を基盤とする、最速の Node.js 画像処理ライブラリです。すべての画像最適化タスクに使用してください。

Sharp のインストール

bun add -d sharp
# or
npm install -D sharp

クイックスタートのワークフロー

1. 現状をベンチマークする

最適化の前に、ベースラインの指標を測定します。

# Total size and count
du -sh public/images/
find public/images -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" \) | wc -l

# Size by format
find public/images -name "*.png" -exec du -ch {} + | tail -1
find public/images \( -name "*.jpg" -o -name "*.jpeg" \) -exec du -ch {} + | tail -1

# Top 20 largest files
find public/images -type f \( -name "*.png" -o -name "*.jpg" \) -exec ls -la {} \; | \
  awk '{print $5, $9}' | sort -rn | head -20 | \
  awk '{printf "%6.1fMB  %s\n", $1/1048576, $2}'

2. 1 枚の画像でテストする

最初に、必ず 1 枚の画像で最適化設定をテストします。

bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --file=public/images/largest-image.png --dry-run

3. 全体を最適化する

設定が適切に動作することを確認したら、実行します。

bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts

4. 結果を確認する

# Compare before/after
du -sh public/images/

# Visually inspect optimized images
# Run production build
bun run build

最適化設定

PNG の最適化

最大限に圧縮するため、パレットモードで Sharp の PNG エンコーダーを使用します。

sharp(filePath)
  .png({
    quality: 80,           // 1-100, lower = smaller
    compressionLevel: 9,   // 0-9, higher = more compression
    adaptiveFiltering: true,
    palette: true,         // Use palette for smaller files
  })
  .toBuffer();

推奨設定：

• スクリーンショット：品質 80、圧縮 9
• 写真：品質 85、圧縮 9
• アイコン／ロゴ：品質 90、圧縮 9（鮮明さを維持）

JPEG の最適化

優れた圧縮を実現するため、mozjpeg と Sharp を使用します。

sharp(filePath)
  .jpeg({
    quality: 80,    // 1-100, lower = smaller
    mozjpeg: true,  // Use mozjpeg encoder
  })
  .toBuffer();

推奨設定：

• 写真：品質 75～80
• スクリーンショット：品質 80～85
• ヒーロー画像：品質 85

最適化スクリプト

をコピーします。scripts/optimize-images.ts をプロジェクトの scripts ディレクトリに配置します。このスクリプトは次の処理を行います。

1. PNG/JPEG 画像を再帰的に検索します
2. 圧縮設定を適用します
3. 元のファイルより小さい場合にのみ、元のファイルを上書きします
4. ファイルごとの削減量を報告します
5. 削減量の合計を表示します

スクリプトの使用方法

# Dry run (see what would happen)
bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --dry-run

# Test single file
bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --file=path/to/image.png

# Full optimization
bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts

期待できる削減量

最適化されていない一般的な Web 画像での結果：

画像の種類	一般的な削減量
スクリーンショット（PNG）	40～60%
写真（JPEG）	20～40%
水彩画（PNG）	30～50%
アイコン（PNG）	10～30%

Next.js に関する考慮事項

Next.js では next/image による画像の自動最適化が提供されています。ただし、元画像を最適化しておくことにも利点があります。

1. ビルドの高速化 - 元画像が小さいほど、処理が速くなります
2. フォールバックのサポート - Next.js 以外でのインポートにも効果があります
3. ストレージの削減 - リポジトリのサイズが小さくなります
4. CDN の効率化 - キャッシュ／配信するデータが少なくなります

next/image を使用する場合も、元画像は最適化しておきましょう。

ワークフローへの統合

コミット前フック（任意）

.husky/pre-commit または Git フックに追加します。

# Warn if large images are being committed
find public/images -name "*.png" -size +500k -exec echo "Warning: Large image: {}" \;

CI/CD チェック

ビルドパイプラインに追加します。

# Fail if images exceed threshold
MAX_SIZE=79  # MB
CURRENT=$(du -sm public/images | cut -f1)
if [ "$CURRENT" -gt "$MAX_SIZE" ]; then
  echo "Error: Images exceed ${MAX_SIZE}MB (currently ${CURRENT}MB)"
  exit 1
fi

トラブルシューティング

画像の品質が低すぎる

品質設定を上げます。

• PNG：quality を 85～90 に上げます
• JPEG：quality を 85～90 に上げます

透明な PNG の表示がおかしい

palette: true で透明度が正しく処理されることを確認します。複雑な透明度の場合は、次を使用します。

.png({ quality: 85, palette: false })

Sharp のインストールに関する問題

macOS では、libvips が利用可能であることを確認します。

brew install vips

または、sharp にビルド済みバイナリをダウンロードさせます。

npm rebuild sharp

追加リソース

参考ファイル

• references/optimization-guide.md - 圧縮アルゴリズムと形式の比較に関する詳細
• references/sharp-api.md - 画像向け sharp API の完全なリファレンス

スクリプト

• scripts/optimize-images.ts - 本番環境向けの最適化スクリプト

コンテキストの管理

最適化済み画像をコンテキストに読み込まないでください。 スクリプトは、ファイルサイズ、削減率、合計を含むサマリーテーブルを出力します。品質の確認が必要な場合は、ユーザーに目視で結果を確認してもらってください。多くのファイルを処理すると、最適化済み画像でもコンテキストウィンドウを埋め尽くすほど大きくなることがあります。

概要

1. sharp をインストールします：bun add -d sharp
2. 最適化スクリプトをプロジェクトにコピーします
3. ベンチマークします：du -sh public/images/
4. テストします：bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --dry-run
5. 最適化します：bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts
6. 確認します：サイズと視覚的な品質をチェックします
7. コミットします：最適化済みの画像をデプロイに含めます