コンテンツにスキップ

Storefront / Dashboard 画像配信補足仕様

背景

Storefront の商品画像と CMS 画像は、これまで Vendure の preset 変換・raw asset 参照・各画面の個別画像実装 指定が混在していた。表示面ごとに配信方針が分散すると、画質・転送量・責務分離を一貫して判断できないため、Storefront の画像配信方針を Cloudflare-first に統一する。

一方、Vendure の React Dashboard は管理者限定 UI であり、Storefront と同じ edge 配信最適化を優先する必要は薄い。画像アップロード直後の確認を確実に行えることを優先し、Dashboard / admin API の asset 配信は same-server /assets/ を正本にする。

仕様

  1. Storefront の商品画像と CMS 画像は、Cloudflare-first の配信方針を正本とする。
  2. production では Cloudflare Transformations（/cdn-cgi/image）を使用し、表示面に応じた幅・品質・形式最適化を行う。
  3. local / staging / preview / mock では Cloudflare Transformations を使用せず、raw asset をそのまま配信する。
  4. 非本番環境の fallback は Vendure 画像変換ではなく raw delivery とし、Storefront 表示のために Vendure 側へ追加変換負荷を載せない。
  5. Storefront の商品詳細メイン画像は商品全体が欠けにくい表示を優先し、contain 相当の表示を正本とする。
  6. 商品カード、カート、注文履歴、キャンペーンバナー、ホーム導線など一覧・バナー系の画像は、枠を埋める表示を正本とする。
  7. Storefront の商品系 UI で表示する代表画像は、Product の featuredAsset / assets を正本とする。 Variant の featuredAsset / assets は、商品代表画像の切替条件として使わない。
  8. 商品詳細のメイン画像、variant 選択カード、クイックオーダー、カート、注文履歴、注文詳細で表示する画像は、同じ Product に属する代表画像を使う。 variant を切り替えても、代表画像は Variant 固有画像へ自動で差し替えない。
  9. OGP / Twitter Card を含む metadata 画像も、画面表示と同じ Cloudflare-first 方針に従う。
  10. SafeHtml 経由で描画する CMS 本文・商品説明内の <img> も、production では Cloudflare-first の配信方針に従う。
  11. SVG / GIF / 動画 / PDF など Cloudflare 変換に向かないアセットは pass-through とする。
  12. shop API が返す Vendure asset URL は、VENDURE_ASSET_URL で指定する R2 custom domain を正本とする。
  13. admin API / React Dashboard が返す Vendure asset URL は、 Vendure Server 同居の /assets/ を正本とし、R2 custom domain / Cloudflare edge cache を経由させない。
  14. Dashboard の画像表示では、Cloudflare cache rule の調整だけで整合性を担保しようとせず、admin / shop の配信経路自体を分けることを正本とする。

対象範囲

  • 商品一覧・商品カルーセル・関連商品・お気に入りなどの商品カード面
  • 商品詳細、バンドル画像、クイックオーダー、カート、注文履歴、注文詳細
  • ホームヒーロー、コレクション導線、キャンペーン一覧、キャンペーン詳細など CMS / 販促面
  • WordPress 本文・静的ページ本文・商品説明など SafeHtml 経由の本文内画像
  • Storefront が生成する OGP / Twitter Card 用 metadata 画像
  • Vendure の React Dashboard / 管理画面
  • Cloudflare 画像変換の適用対象外
  • asset URL は Vendure Server 同居 /assets/ を使用

運用メモ

  • 商品カードの比率は 2026-04-storefront-product-card-square-ratio.md を正本とする。
  • 商品代表画像の選定は Product 単位で固定し、Variant 画像の有無で表示面ごとに分岐させない。
  • Storefront 画面から Vendure preset 名を直接組み立てない。
  • sharp は Vendure Server on Fly.io の asset upload / preview / Dashboard 表示用に限定し、Cloudflare Workers 上の Storefront 画像最適化には使わない。
  • pnpm why sharp で wrangler -> miniflare -> sharp が見える場合、それは Cloudflare 開発ツールの間接依存であり、Storefront runtime の画像処理責務とは扱わない。
  • Dashboard 画像アップロードの即時確認性を壊すため、ec-assets* への cache rule 変更だけで Dashboard の不整合を解決しようとしない。
  • 画像配信方針を変更する場合は、実装変更の前に本ファイルと Cloudflare 運用手順を更新して合意を残す。