TL;DR

拡張機能がないアプリは基本自動移行。変更点の確認のみ。

拡張機能があるアプリは、CLI へ管理移行＋**uid 発行＋shopify.app.toml 同期**が必要。最初の deploy は対話モードで実行して uid を確定させるのが肝。

なぜ今「Dev Dashboard」なのか（背景とメリット）

Dev Dashboard は Partner/マーチャント双方に共通の開発プラットフォームとして提供され、ツールの一元化と体験の改善が目的。
以降はダッシュボード上で拡張機能の新規作成/管理は不可。Shopify CLI でのみ作成/管理する運用に移行。
「アプリ管理・開発ストア・ログ/モニタリング・メタオブジェクト定義」などの開発者ツールが Dev Dashboard に統合。

まずは準備（前提チェックリスト）

Shopify CLI を最新化

shopify version
npm i -g @shopify/cli@latest   # or: brew install shopify-cli

CLI は常に最新推奨。shopify version で確認後、更新。

Node/Git 要件（CLI 要件）

Node.js 20.10+、Git 2.28+ を推奨環境として用意。

ブランチを切って移行作業

feat/migrate-dev-dashboard のようなブランチで作業し、対話型 deploy で生成される uid をコミットして履歴化します（後述）。

影響を受ける拡張機能タイプ（移行対象）

Admin links
Flow（lifecycle events / actions / triggers）
Marketing activity extensions これらは Partner Dashboard 管理から CLI 管理に移す必要があります。

実践ステップ（失敗しない進め方）

STEP 1. Dashboard 管理の拡張をローカルへ「取り込み」

拡張種別ごとに shopify app import-extensions を実行して、extensions/ 配下へ TOML を生成します。

# アプリ直下で実行
shopify app import-extensions
# プロンプトで拡張種別（Admin links / Flow / Marketing Activity など）を選択

Admin links の移行：import → deploy の 2 ステップ。
Flow の移行：import 実行で handle が TOML に付与。deploy で CLI 管理に切替。
Marketing Activity の移行：import で TOML 生成、設定を確認後に deploy。

補足: import はローカルにファイルを生成するだけで、CLI 管理への切替は deploy 実行時に行われます。

STEP 2. `shopify.app.toml` を「真実のソース」に揃える

Dev Dashboard では、CLI 管理のアプリ設定が deploy/dev 実行時に常に反映されます（include_config_on_deploy は CLI により削除/非推奨化）。ダッシュボードと乖離があるなら app config link で同期しましょう。

# 既存アプリの設定を TOML として取得/上書き
shopify app config link

deploy 実行時に期待外の設定変更が出たら、TOML が古いサイン。app config link で最新に揃えてから再度 deploy。
複数構成（dev/stg/prod）を持つ場合は、構成ファイルを分けて -config で指定できます。

STEP 3. 対話型 `deploy` で `uid` を確定させる（最重要）

移行後は 全拡張に uid が必須。shopify.app deploy を対話モードで一度実行して、各 shopify.extension.toml に uid が書き込まれます。この初回確定前は shopify app dev や deploy --force が失敗します。

# 初回だけ対話で uid を作成・マッピング
shopify app deploy
# すべての拡張が "updated" と表示されるのを確認
# "new" / "removed" が混ざる場合はマッピング失敗（次節）

"new"/"removed" と表示されたら要注意：handle の不一致、または .env の既存 ID とマッチしていない可能性。handle を修正するか、.env の拡張 ID 名を合わせて再実行します。
uid は アプリ内で一意な「ユーザー定義 ID」。以後、拡張の新規/更新/削除判定には uid のみが使われます。

生成された uid は必ずコミットし、複数インスタンス（例: --config prod）にもマージ → shopify app deploy --config <name> で同じ uid をマッピングします。

うまくいかない時の「マッピング」理解（.env と handle）

初回 deploy では、CLI は以下の順序で既存拡張との対応付けを試みます。

有効な .env.* を特定（例：shopify.app.prod.toml が有効なら .env.prod を探す）
.env に SHOPIFY_<HANDLE_SNAKE_CASE>_ID があればそれを使用
- 例：handle が product-reviews → 変数名は SHOPIFY_PRODUCT_REVIEWS_ID
なければ type + handle で照合
それでも見つからなければ候補をプロンプトで提示

Tips: 以前は deploy が .env を自動生成していました。ファイルがない／古い場合は、拡張の handle を Shopify 上の値に合わせるのが近道です。

よくある落とし穴と回避策（実体験ベース）

ダッシュボードで拡張を新規作成/編集できない → 仕様です。以後は CLI のみで管理。
初回 deploy 前に CI で deploy --force が失敗 → uid 未確定が原因。必ず一度ローカルで対話 deploy を通して uid を作る。
deploy で大量の設定差分が出る → TOML が最新でない。shopify app config link で同期し、差分を理解した上で再 deploy。
"new"/"removed" でデータ喪失が怖い → マッピング失敗の合図。handle / .env を修正し、"updated" のみになるまでやり直す。

実運用の型（dev/stg/prod を安全に回す）

構成ファイルを分割
- shopify.app.toml（dev）
- shopify.app.stg.toml（stg）
- shopify.app.prod.toml（prod） shopify app config use / -config で切替。
初回のみローカル対話 deploy で uid 生成 → commit
- その後、各構成ブランチへマージ → shopify app deploy --config <name> で同じ uid を配布。
CI/CD は -config を明示
- 初回対話 deploy 済みなら、以後は非対話で OK（ただし uid 未確定の状態では失敗）。

GitHub Actions（例）

name: Deploy App
on: workflow_dispatch
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm i -g @shopify/cli@latest
      - run: shopify version
      - run: shopify app deploy --config prod --force
        env:
          SHOPIFY_FLAG_NO_COLOR: 1

種別別：移行の具体コマンド

Admin links

shopify app import-extensions   # "admin links" を選択
shopify app deploy

deploy により Partner 側の管理が切り替わり、以後はコードと CLI で運用。リリースには数分かかることあり。

Flow（lifecycle/events, actions, triggers）

shopify app import-extensions   # "Flow Extensions" を選択
shopify app deploy

import で handle が TOML に付与。handle は dev/deploy 後は変更不可なので注意。

Marketing activity

shopify app import-extensions   # "Marketing Activity Extensions" を選択
# 生成された shopify.extension.toml を確認・調整
shopify app deploy

必須プロパティ（title, description, api_path, tactic, marketing_channel など）を TOML で確認してから deploy。

参考：`shopify.extension.toml` における `uid` 例

# extensions/admin-links-example/shopify.extension.toml
name   = "Admin Links Example"
type   = "admin_link"
handle = "admin-links-example"

# 初回の対話 deploy 後に CLI が自動付与（以後、これが真IDとして機能）
uid    = "01HF3E...YOUR_UID..."

uid はアプリ内で一意の識別子で、以後の作成/更新/削除判定は uid だけで行われます。
.env の旧式拡張 ID は以後使われません（初回マッピングにのみ参照される）。

QA チェックリスト（移行直後にやること）

「拡張が全部 updated で出たか」・「new/removed が混ざっていないか」
Admin 画面で Admin links が期待通りに表示/遷移できるか（権限やロケール含む）。
Flow の trigger/action/lifecycle が実行/通知されるか。handle が期待通りに渡るか。
Marketing Activity の フォーム定義/プレビュー が TOML どおりに出るか。
shopify.app.toml と Dev Dashboard の設定値が一致しているか（ずれたら app config link）。

変更点まとめ（何がどこへ移った？）

アプリ作成/設定・開発ストア管理 → Dev Dashboard 側へ統合。
モニタリング/ログ・CLI 連携 → Dev Dashboard に集約。メタフィールド/メタオブジェクト定義の宣言的管理も可能に。
組織/権限管理 → Shopify 組織設定に統合。

付録：Node.js ミニユーティリティ（handle→.env 名の確認）

※開発チームで handle 規約を合わせる時に便利な小ネタ

// scripts/handle-to-env.js
// 例: "product-reviews" -> "SHOPIFY_PRODUCT_REVIEWS_ID"
const toEnvVar = (handle) =>
  `SHOPIFY_${handle.replace(/[^a-z0-9]+/gi, '_').toUpperCase()}_ID`;

console.log(process.argv.slice(2).map(toEnvVar).join('\\\\n'));

node scripts/handle-to-env.js product-reviews discount
# => SHOPIFY_PRODUCT_REVIEWS_ID
# => SHOPIFY_DISCOUNT_ID

（初回対話 deploy 前のマッピング確認用。公式の解決手順は上記の handle/.env 照合ロジックを参照）

まとめ

ダッシュボード管理の終焉 → CLI 管理へ一本化。まずは import-extensions でファイル化し、対話 deploy で uid を確定。
shopify.app.toml は常に deploy/dev に同梱される前提。差分が出るなら app config link で同期。
uid/handle/.env の三位一体の整合が成功のカギ。"updated"だけのクリーンなリリースを目指そう。

参考（公式）

Migrate from the Partner Dashboard：移行全体像、uid/マッピング/その他変更点
Shopify CLI：要件・インストール・バージョン確認
Migrate admin links：import → deploy の手順
Migrate legacy Flow extensions：Flow の import/deploy と handle 仕様
Migrate marketing activity extensions：TOML 例と deploy
Manage app config files / app config link：構成ファイル運用・--config

Shopifyパートナーダッシュボードから Dev Dashboard へ ― 実践マイグレーション完全ガイド

なぜ今「Dev Dashboard」なのか（背景とメリット）

まずは準備（前提チェックリスト）

影響を受ける拡張機能タイプ（移行対象）

実践ステップ（失敗しない進め方）

STEP 1. Dashboard 管理の拡張をローカルへ「取り込み」

STEP 2. `shopify.app.toml` を「真実のソース」に揃える

STEP 3. 対話型 `deploy` で `uid` を確定させる（最重要）

うまくいかない時の「マッピング」理解（.env と handle）

よくある落とし穴と回避策（実体験ベース）

実運用の型（dev/stg/prod を安全に回す）

種別別：移行の具体コマンド

Admin links

Flow（lifecycle/events, actions, triggers）

Marketing activity

参考：`shopify.extension.toml` における `uid` 例

QA チェックリスト（移行直後にやること）

変更点まとめ（何がどこへ移った？）

付録：Node.js ミニユーティリティ（handle→.env 名の確認）

まとめ

参考（公式）

関連記事

Shopifyを使ったコーポレートサイト構築を承ります

Shopifyアプリ開発ならお任せください

Shopify CLI 3対応したShopifyアプリ開発の手順を解説

なぜ今「Dev Dashboard」なのか（背景とメリット）

まずは準備（前提チェックリスト）

影響を受ける拡張機能タイプ（移行対象）

実践ステップ（失敗しない進め方）

STEP 1. Dashboard 管理の拡張をローカルへ「取り込み」

STEP 2. shopify.app.toml を「真実のソース」に揃える

STEP 3. 対話型 deploy で uid を確定させる（最重要）

うまくいかない時の「マッピング」理解（.env と handle）

よくある落とし穴と回避策（実体験ベース）

実運用の型（dev/stg/prod を安全に回す）

種別別：移行の具体コマンド

Admin links

Flow（lifecycle/events, actions, triggers）

Marketing activity

参考：shopify.extension.toml における uid 例

QA チェックリスト（移行直後にやること）

変更点まとめ（何がどこへ移った？）

付録：Node.js ミニユーティリティ（handle→.env 名の確認）

まとめ

参考（公式）

関連記事

Shopifyを使ったコーポレートサイト構築を承ります

Shopifyアプリ開発ならお任せください

Shopify CLI 3対応したShopifyアプリ開発の手順を解説

STEP 2. `shopify.app.toml` を「真実のソース」に揃える

STEP 3. 対話型 `deploy` で `uid` を確定させる（最重要）

参考：`shopify.extension.toml` における `uid` 例