Polaris web components 移行ガイド公開 Checkout & Customer Account UI extensions を新 API に上げるための公式手順書

図解 ： Polaris web components 移行ガイド（Checkout / Customer Account UI extensions） Checkout UI / Customer Account UI / 移行 Polaris web components 移行ガイド公開 Checkout & Customer Account UI extensions を新 API に上げるための公式手順書 React／JavaScript の従来 API から、Preact ＋ Polaris web components ＋ グローバル shopify オブジェクトへ。60 以上のコンポーネント別ページと、checkout → cart メタフィールド移行手順までまとめて公開。 このページの構成 そもそも何が公開されたのか（30秒で理解） 移行の全体像（Before → After 図解） 公開された 3 つのガイドの中身 対象となる Extension と API バージョン 移行作業の流れ（4ステップ） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が公開されたのか Checkout UI extensions ／ Customer Account UI extensions を、 React／JavaScript API から Preact ＋ Polaris web components ＋ グローバル shopify オブジェクト へ書き換えるための、公式移行ガイドが新たに公開された。 ① 全体移行ガイド React／JS の extension API から、Preact ／ Polaris web components ／ グローバル shopify オブジェクトへ書き換えるための手順。 ② コンポーネント別ページ 60+ Button／Checkbox／TextField／Banner／View 等、コンポーネント単位での移行手順を個別ページ化。 ③ メタフィールド移行手順 checkout メタフィールド → cart メタフィールドへの移行手順も同時公開。 2 移行の全体像（Before → After 図解） Polaris web components ： Shopify が提供する Web Components ベースの UI ライブラリ。React／フレームワーク非依存で、Preact ＋ グローバル shopify オブジェクトで動く新しい extension モデルの土台になる。 API 2025-10 以降のデフォルト として組み込まれているため、それ以前のバージョンを使っている extension は移行対象。 3 公開された 3 つのガイドの中身 ガイド 内容 対象作業 全体移行ガイド React／JavaScript の extension API から、Preact ＋ Polaris web components ＋ グローバル shopify オブジェクトへの移行手順 全体方針 アーキテクチャ刷新 コンポーネント別ページ（60+） Button／Checkbox／TextField／Banner／View など、コンポーネント単位の旧→新マッピング 部品単位 個別書き換え メタフィールド移行 checkout メタフィールドから cart メタフィールドへの移行手順 データ層 スキーマ移行 Checkout UI extensions 移行ガイド Checkout UI extension に特化した入口ページ 入口 ここから着手推奨 Customer Account UI extensions 移行ガイド Customer Account UI extension に特化した入口ページ 入口 ここから着手推奨 4 対象となる Extension と API バージョン Checkout UI extensions チェックアウト画面にカスタム UI を差し込むための extension。今回の移行ガイドの主対象。 Customer Account UI extensions 顧客アカウントページにカスタム UI を差し込むための extension。Checkout と同じく対象。 API バージョン 2025-10 より前を使っている extension は移行対象 。Polaris web components は 2025-10 以降のデフォルトであり、旧バージョン上で動いている既存実装はガイドに沿ってアップグレードする必要がある。 5 移行作業の流れ（4ステップ） 1 入口ガイドを開く Checkout または Customer Account の移行ガイドからスタート。 2 ベース刷新 React／JS から Preact ＋ グローバル shopify へ書き換え。 3 コンポーネント差し替え Button／TextField／Banner 等を、Polaris WC の個別ページに沿って置換。 4 メタフィールド移行 checkout メタフィールドを cart メタフィールドへ置換。 並行リリース戦略・破壊的変更の deprecation 期限などはこの記事には記載なし。詳細は各移行ガイドを参照。 6 技術者が押さえるべき5つのポイント 1. 分水嶺は API 2025-10 Polaris web components が default になるのは 2025-10。それ以前を使う extension は本ガイドの対象になる、と明示されている。 2. React → Preact への乗り換え UI フレームワークが Preact ＋ Polaris web components に統一される。React 固有の hooks エコシステムや HOC は素直には持ち込めない。 3. グローバル shopify オブジェクト extension API へのアクセスがグローバル shopify 経由に集約される。従来 React Hooks 経由で取っていた値の取り口がここに変わる。 4. コンポーネント単位ページが 60 以上 Button／Checkbox／TextField／Banner／View などコンポーネント単位で個別ページが用意されているため、 差分は 1 つずつ突き合わせて潰す形式 が現実的。 5. checkout メタフィールド → cart メタフィールドへ UI 層の刷新と並行して、データの置き場所も checkout メタフィールド → cart メタフィールド へ移る。チェックアウト中だけ持っていたカスタムデータの保存場所が変わるため、リード／ライトの参照箇所をすべて洗い出す必要がある。 7 業務に活かせる3つのユースケース USE CASE 1 既存 Checkout UI extension の API バージョンアップ案件化 課題 運用中の Checkout UI extension が API 2025-07 以前のまま放置されており、React／JS ベースの古い実装が残っている。 打ち手 公式の Checkout UI extensions 移行ガイドを着手起点にし、Preact ＋ Polaris web components ＋ グローバル shopify への書き換えを段階的に実施。 効果 Polaris 標準 UI に追従できる ／ 今後の機能追加が公式ロードマップに乗せやすくなる。 技術メモ 60+ のコンポーネント別ページを使って、コンポーネント単位で diff を潰すレビュー運用に持ち込むのが現実的。 USE CASE 2 Customer Account ページのカスタム UI を新基盤に揃える 課題 顧客アカウントページに自作の React コンポーネントで機能を載せているが、Checkout 側と UI トーンや実装基盤がズレている。 打ち手 Customer Account UI extensions 移行ガイドに沿って Polaris web components へ寄せ、Checkout 側と同じ Preact ＋ shopify 構成に統一。 効果 UI の見た目／挙動が Polaris 標準に揃い、独自スタイル保守の手離れが進む。 技術メモ Checkout と Customer Account で共通の Polaris WC コンポーネント（Button／Banner／View 等）が使えるため、共有モジュール化と相性が良い。 USE CASE 3 checkout メタフィールド依存箇所の棚卸し＋ cart メタフィールドへの移行 課題 カスタム属性（ギフトオプション、配送オプション、配達日時など）を checkout メタフィールドに書いており、UI 移行と同時にデータ層も整理する必要がある。 打ち手 公式メタフィールド移行ガイドを使い、対象 namespace／key を一覧化 → cart メタフィールドに置き換え → 読み出し側の extension／アプリ側ロジックも合わせて更新。 効果 UI 刷新とデータモデルの整理が同じプロジェクトで片付き、後工程の運用が単純化。 技術メモ 既存データの読み書き経路（管理アプリ、Functions、外部連携）も同時に洗い出さないと、移行漏れで一部画面だけ値が表示されない事故になりやすい。 8 提案で使える1行サマリ 「Shopify が、Checkout / Customer Account UI extensions の React・JS → Preact ＋ Polaris web components ＋ グローバル shopify オブジェクト への移行ガイドを公開。 60+ のコンポーネント別ページと、checkout → cart メタフィールド移行手順込みで、 API 2025-10 より前を使っている既存 extension は要対応 。」 source ： shopify.dev / changelog / polaris-web-components-migration-guides-now-available-for-checkout-and-customer-account-ui-extensions 公開日 ： 2026-05-13 ／ generated 2026-05-23