experience-lwc-legacy-migrate

レガシー LWC スタックの移行

Aura コンポーネントを移行中のユーザーは Lightning Out のホストページも移行することが多いため、両方を把握している 1 つのスキルを活用できます。そこで、ここでは 2 種類の異なる移行ワークフローを扱います。

移行	次の場合に使用	参照
Aura → LWC の完全性チェック	Aura コンポーネントを変換した後、何も失われていないか確認する	aura-to-lwc-completeness-checklist.md
Lightning Out Beta → LO 2.0	外部ホストページから lightning.out.js を移行する場合	lightning-out-beta-to-2-migration.md

このスキルを使用するタイミング

• ユーザーが Aura コンポーネントをすでに LWC に変換しており、体系的な完全性チェックを希望している。
• ユーザーが Lightning Out Beta を使って Salesforce LWC を埋め込んだ、Salesforce 以外のホストページを持っており、LO 2.0 に移行する必要がある。
• ユーザーが $Lightning.use() / $Lightning.createComponent() の呼び出しを、<lightning-out-application> Web コンポーネントのパターンにアップグレードする。
• ユーザーがハードコードされた LO 認証トークンを、OAuth PKCE + front-door フローに置き換える必要がある。

ユーザーが一から新しい LO 2.0 ホストページを作成したい場合（移行対象の Beta コードがない場合）も、このスキル内の LO 2.0 システムリファレンスが信頼できる情報源です。直接案内してください。

前提条件

• ソース（Aura コンポーネントファイルまたは Beta ホストページ）へのアクセス権があること。
• LO 2.0 の移行では、Salesforce Setup で External Client App（Consumer Key が必要）を作成できること。Lightning Out 2.0 App（18 文字の App ID）の作成は任意です。
• Aura の移行では、LWC への変換内容にアクセスできること。存在する場合は、__tests__（Jest）と __utam__（UTAM）フォルダーも含みます。

ワークフロー A — Aura → LWC の完全性チェック

目的：完了済みの Aura から LWC への変換を 12 の観点で評価し、実行可能な推奨事項を提示します。

ステップ A1 — コンポーネントを特定する

コンポーネント名（例：accountTile）をユーザーに尋ねます。Aura ソース（{componentName}.cmp、コントローラー、ヘルパー、CSS）と、LWC の出力（{componentName}.html、.js、.css、.js-meta.xml）を探します。

ステップ A2 — チェックリストを実施する

aura-to-lwc-completeness-checklist.md に忠実に従います。

• 12 の指標（機能の同等性、イベント処理、データバインディングと状態、UI/UX の同等性、拡張性とモジュール性、エラー処理、ローカライズ、セキュリティとアクセス制御、パフォーマンス、Salesforce のベストプラクティス、Jest テストカバレッジ、UTAM ページオブジェクト）すべてで変換を評価します。
• 6 段階の評価基準を使用します：Excellent / Good / Satisfactory / Limited / Poor / Missing。
• 参照ファイルに従い、出力は表ではなくリストで提示します。

ステップ A3 — まとめて推奨事項を提示する

全体的な信頼度を示し、具体的で実行可能な推奨事項を優先順位順に列挙して締めくくります（何を、どの順番で修正すべきか）。

ワークフロー B — Lightning Out Beta → LO 2.0

目的：お客様の HTML 構造、スタイル、ビジネスロジックをそのまま保ちながら、Lightning Out Beta のホストページを Lightning Out 2.0 のホストページに変換します。

ステップ B1 — LO 2.0 のメンタルモデルを理解する

コードを編集する前に、アーキテクチャを理解します： lightning-out-2-system-reference.md。

重要なポイント：LO 2.0 はライブラリのアップグレードではありません。LWC は閉じたシャドウ DOM を持つ iframe 内で実行されます。ホストページの JS は LWC にアクセスできず、その逆も同様です。また、ホストページの CSS はカスケードしません。

ステップ B2 — Beta のパターンを特定する

移行ガイドのフェーズ 1 を使用して、次の項目を特定します。

• パターン A — lightning.out.js を読み込むスクリプトタグ（ドメインを抽出します）。
• パターン B — 設定変数（エンドポイント、Aura アプリ、コンポーネント、トークン）。
• パターン C — $Lightning.use(...) の呼び出し。
• パターン D — $Lightning.createComponent(...) の呼び出し。
• パターン E — パターン D の第 3 引数で参照される DOM ターゲット要素。

lightning-out-beta-to-2-migration.md § Phase 1 を参照してください。

ステップ B3 — 変換を適用する

スクリプトタグの URL、コンポーネントタグ名、属性名は決定論的に変換できます。ヘルパースクリプトで導出することで、毎回正確な値を得られます（名前空間を維持し、camelCase を kebab-case に変換し、Beta ホストをバージョン付き LO 2.0 ライブラリ URL に変換します）。

python3 scripts/convert-lo-names.py \
  --component c:myComponent \
  --attributes recordId,ownerId \
  --my-domain https://<DOMAIN>.lightning.force.com

スクリプトは <c-...> タグ、kebab-case の属性、バージョン付き LO 2.0 ライブラリ URL を出力します。その後、ガイドのフェーズ 2 に従って作業を進めます。

1. スクリプトタグ — スクリプトが出力する library-url を使用し、async を追加します。
2. コンポーネント名／属性 — スクリプトが出力する component-tag と kebab-case の属性を使用します。
3. コンポーネントタグ — ターゲットの場所に <c-...> タグを HTML で直接追加します（配置は判断が必要です。Beta のレンダーターゲットがあった場所に配置してください）。
4. $Lightning ブロックを置き換える — ブロック全体を削除し、assets/lo20-host-page-template.html をベースにして、設定定数を埋めます。テンプレートにはヘルパー関数、mountLo20(frontdoorUrl, orgUrl)、boot()、OAuth リスナーがすでに含まれています。

ステップ B4 — 絶対に守るべき 6 つのルール

これらのルールに違反すると、実行時にエラーが表示されないまま失敗します。また、どれもコード構造を決定論的に検証できます。目視ではなく、バリデータースクリプトを使って適用してください。移行後のページに対して実行し、すべての FAIL を修正します。

python3 scripts/validate-lo20-page.py <migrated-page.html>

スクリプトは各ルールの PASS／FAIL 行（および LO 2.0 ライブラリと Beta 削除のチェック）を出力し、いずれかのルールが失敗するとゼロ以外の終了コードを返します。適用される 6 つのルールは次のとおりです。

1. customElements.whenDefined(...) には、components 変数ではなくリテラル文字列を渡す必要があります。
2. mountLo20(frontdoorUrl, orgUrl) は 2 つのパラメーターを受け取る必要があります。
3. mountLo20(...) を呼び出す前に、必ず clearCachedResult() を呼び出します。
4. orgUrl が未定義の場合でも、mountLo20(...) の呼び出し時には必ず両方のパラメーターを渡します。
5. すべての初期化処理を boot() でラップし、最後に boot() を呼び出します。
6. コンポーネントタグにインラインの display:none を指定しません。ローディングインジケーターを使って表示を制御します。

ステップ B5 — Salesforce の設定

• 外部クライアントアプリ（ECA） — 設定 → アプリケーションマネージャー → 新規接続アプリ → 外部クライアントアプリ。PKCE を使用する OAuth を有効にします。コンシューマーキーをコピーします。

• Lightning Out 2.0 アプリ — 続行する前に、次の判断を適用します。

  条件	操作
  ホストページに app-id="..." が設定されている	設定 → Lightning Out → 新規 LO アプリ。18 文字のアプリ ID をコピーし、ホストページの app-id 属性に設定します
  ホストページに LWC が直接埋め込まれている（app-id なし）	LO アプリの作成はすべて省略します

• 移行では、ホストページと同じ場所に次のヘルパーファイルが存在することを前提としています。frontdoor-url.html（OAuth コールバック）および utils/LightningOutAuth.js（PKCE の実装）。

ステップ B6 — LO 2.0 の検証チェックリストを実行する

まず python3 scripts/validate-lo20-page.py <migrated-page.html> を実行して機械的なチェックを完了します。次に、移行後の完全なチェックリストにある残りの手動項目を確認します。移行が完了したと判断する前に、すべての項目を確認してください。lightning-out-beta-to-2-migration.md の末尾にある「Verification Checklist」セクションを参照してください。

検証チェックリスト（概要）

Aura → LWC：

• 12 項目すべての完全性指標について、評価とその根拠が記載されていること。
• 参考資料に従い、表ではなくリスト形式で出力されていること。
• 全体的な信頼度に関する記述があること。
• 具体的で、優先順位が付けられた推奨事項が記載されていること。

LO Beta → LO 2.0：

• スクリプトタグで .my.salesforce.com/lightning/lightning.out.latest/index.iife.prod.js を async とともに使用していること。
• $Lightning.use / $Lightning.createComponent への参照が残っていないこと。
• コンポーネント名がケバブケースで、属性もケバブケースになっていること。
• mountLo20(frontdoorUrl, orgUrl) が 2 つのパラメーターを受け取ること。
• customElements.whenDefined(...) で文字列リテラルを使用していること。
• すべての初期化処理が boot() でラップされ、boot() が 1 回呼び出されていること。
• ハードコードされたトークンを OAuth PKCE フローに置き換えていること。postMessage、BroadcastChannel、ストレージの各リスナーがすべて存在し、防御的に実装されていること。
• コンポーネントタグにインラインの display:none がないこと。

トラブルシューティング

• LO 2.0 のマウントが停止する — カスタム要素が登録されていません。ライブラリのスクリプトタグの URL と、app-id / frontdoor-url の値が正しいことを確認してください。
• コンポーネントが空の状態で表示される — 属性がまだキャメルケースになっている可能性があります。LO 2.0 が読み取る HTML 属性は、ケバブケースである必要があります。
• OAuth コールバックが一度も発生しない — postMessage、BroadcastChannel、ストレージの各リスナーのいずれかが欠落しています。LO 2.0 では 3 つすべてが必要です。
• Aura チェックリストで UTAM または Jest が「未対応」と評価される — チームに代替のテスト戦略があれば許容できる場合があります。ブロックするのではなく、推奨事項として指摘してください。