hydrogen-upgrades

Hydrogen のアップグレード

Shopify Hydrogen をアップグレードするためのバージョンごとの移行ガイドです。各ガイドでは、破壊的変更、必要なコードの更新、手順ごとの差分を説明します。

最新のドキュメント

このスキルのフォルダー内で、以下を実行してください。ヘルパーは隣接する shopify-hydrogen スキル内に含まれているため、パック全体がインストールされていれば ../shopify-hydrogen/scripts/ が存在します。

このスキルだけをインストールした場合、そのフォルダーは存在せず、以下のコマンドは MODULE_NOT_FOUND で失敗します。ヘルパーを一度追加してください。

npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen

インストールせずに使いたい場合は、このスキルの references/ ファイルをオフラインで利用できます。

Shopify の最新アップグレード情報を取得するには、以下を実行してください。

node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen upgrade <version>"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen breaking changes"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen migration"

以下の厳選ガイドでは、特定のバージョン間のアップグレードについて、詳細な差分と Weaverse 固有の注意点を説明します。

利用可能なアップグレードガイド

ガイド	主な変更点
2024.4.7 → 2024.7.1	オプティミスティックなバリアント、新しいセッションコミットパターン、Layout コンポーネントのリファクタリング、VariantSelector の改善
2024.10.1 → 2025.1.0	v3_lazyRouteDiscovery フラグ、スタイルシートのリンクタグの修正
2025.1.0 → 2025.1.1	v3_singleFetch フラグ、nonce のサポート、json／defer の非推奨化、B2B の安定化
2025.1.2 → 2025.1.3	v3_routeConfig フラグ、Layout のエクスポートを別ファイルに移動、routes.ts の設定
2025.1.3 → 2025.1.4	セッションログアウトの修正、VariantSelector の非推奨化、商品クエリの更新、ProductForm のリファクタリング
2025.5.0 → 2025.7.0	メジャー — React Router 7.9.x への移行、コンテキストの作成、エントリーポイントの更新
2025.7.0 → 2026.1.0	メジャー — @react-router 7.12、@shopify/hydrogen 2026.1.0、Storefront API 2026-01、新しいカートのミューテーション
2026.1.0 → 2026.4.7	メジャー — Storefront API 2026-04、必須となる同一オリジンの Storefront API プロキシ、Customer Privacy API の同意移行、React Router ~7.16

アップグレード手順

1. まず公式のアップグレードツールを使う

npx shopify hydrogen upgrade

この CLI は必要な依存関係を自動的に更新してインストールし、必要なソース変更を一覧にした Markdown ファイルを生成します。変更は手動で適用するか、ファイルをエージェントに渡してから、動作を確認してください。このツール自体がソースファイルを編集することはありません。

2. 上記から適切なガイドを選ぶ

現在のバージョンに合ったガイドを選んでください。複数のバージョンをまたいでアップグレードする場合は、各ガイドを順番に適用してください。

3. アップグレード後に型を再生成する

npm run codegen

生成された .d.ts ファイルを直接編集しないでください。必ず再生成してください。

4. リソース

• Hydrogen の変更履歴
• Hydrogen のスケルトン