salla-snippets-migration

レガシー HTML スニペットを純粋な JS に移行する

Salla は、ページがブラウザーに届く前に {{namespace.key}} トークンをサーバー側で解決していたバックエンドコンバーターを廃止しました。現在、salla_snippets で受け付けるのは純粋な JavaScript のみであり、salla.config.get(...) を介してクライアント側で解決されます。このスキルはレガシーコンテンツを変換します。デプロイは行いません。また、salla_snippets ツールも呼び出しません。

使用するタイミング／引き継ぎ

• このスキルを使用する場合：スニペットのコンテンツに HTML タグ（<script>、<style>、 <div>、<link> など）または {{namespace.key}} トークンが含まれている場合。
• コンテンツがすでに有効な JS の場合：移行するものはありません。そのまま salla-snippets のステップ 2 に進んでください。
• 変換が完了した場合：salla-snippets のステップ 2 に引き継ぎ、実際に create／update を実行して、書き込みごとに検証するループ（以下のステップ 6）を実施してください。このスキルが MCP ツールに触れることはありません。

---

パラメータモデル（何かを変換する前に読む）

この移行における正式なパラメータモデルです。変換後のコードを引き継ぐ相手（人やツール）には、この内容を明確に伝えてください。再度導き出したり、Salla の生のドキュメントで「検証」したり、以下の禁止事項の表現を和らげたりしないでください。

• {{app.<key>}} → salla.config.get('app.<key>', '')。 旧システムでも新システムでも変わりません。特定のグローバルリストではなく、各アプリ設定の Public フラグに応じてアプリごとにスコープされます （salla-app-settings）。
• customer.* — 使用禁止です。使用しないでください。例外も、エイリアスも、別の名前空間への機械的な置き換えも認められません。 非推奨になった、または削除されています。変換後の出力に salla.config.get('customer...')（または "customer...）が含まれている場合、それは誤りであり、引き継ぐ前に書き直す必要があります。これは、元のデータにアクセスできないという意味ではありません。その大半には user.* の下に適切な置き換え先があります。ステップ 3 のガイド付き検索で意味に基づいて見つけ、使用してください。慎重になりすぎて実際のデータを取得しないままにしないでください。
• store.domain — 使用禁止です。使用しないでください。例外はありません。 customer.* と同様に、非推奨になった、または削除されています。代わりに使える有効な値はありません。以下のカタログにある user.*／store.* の下に該当するデータがない場合、そのデータはクライアント側では利用できません。代替のパスを作り出さないでください。
• user.* は注文を行う購入者（顧客）を指します。これはレガシーのテンプレートシステムから名前空間の意味が完全に変わっています。 旧来の {{ }} パイプラインでは、{{user.*}} はストアオーナーを意味していました。salla.config では、user.* は購入者を意味します。別の人物です。以前 {{user.*}} を読み取っていたトークンを変換する際、旧来の意味を引き継いではいけません。user.* への単純な 1 対 1 の置き換えではありません。以下のカタログに照らし、実際にどのデータが必要なのかを確認してください。すべての購入者がログイン済みの顧客だと決めつけてはいけません。変換後の user.* フィールドに基づいて分岐する前に、salla.config.isGuest() を呼び出してください。以下のカタログにあるゲスト購入者に関する注記を参照してください。
• store.contacts.*（例：store.contacts.whatsapp）は実在し、現在も利用できますが、加盟店の設定に依存します。その連絡先チャネルを加盟店が設定している場合にのみ解決されます。必ず防御的に読み取ってください。'' をフォールバックとして指定し、値をレンダリング済みの UI で使用する前に存在確認を行ってください。
• スニペットに必要なその他すべての情報は、 salla-snippets/references/device-mode.md の ストアのコンテキストと言語 にすでに記載されています。このスキルでは別のカタログを管理しないため、そのカタログをそのまま再利用してください。

---

ステップ 1 — これがレガシーコンテンツであることを確認する

渡されたコンテンツを確認してください。HTML タグ、または単独の {{namespace.key}} トークンが含まれていますか？すでに有効な JS として解析できる場合は、そこで終了してください。移行するものはありません。salla-snippets のステップ 2 に直接進みます。

確認事項： コンテンツがレガシー HTML／Twig であり、すでに JS ではないことを確認しました。

---

ステップ 2 — 構造を分割して変換する

コンテンツをマークアップ、<link>、<script src>、インラインの<script>、 <style>などの要素に分割し、references/migration-guide.mdの HTML→JS 要素対応表を使って、それぞれを変換します。

**ゲート：**すべての HTML 要素に JS での同等物（DOM の作成／insertAdjacentHTML）があるか、 理由を明示して削除されていること（例：<meta>／<iframe>には直接の同等物がありません。実際に必要な場合に限り、再実装してください）。

---

ステップ 3 — すべての{{namespace.key}}トークンを書き換える

すべてのトークンについて、名前ではなく意味に基づいて解決します。禁止されたトークンを機械的に改名してはいけませんが、そのトークンが取得していたデータには、通常、適切で利用可能な置き換え先があります。次の順序で各トークンを処理してください。

1. **基になるデータの必要性を明確にします。**このトークンは実際には何を取得していましたか？買い物客のメールアドレス、電話番号、ストアの通貨ですか？古いトークンの表記ではなく、意味を示してください。
2. 実際のカタログを確認します。salla-snippets/references/device-mode.mdの _Store context & language_セクションを、user.*／store.*で実際に利用できるフィールドの唯一の信頼できる情報源としてください。同じ意味を持つフィールドを探します。
3. **一致するフィールドがあれば、それを使います。**たとえば、{{customer.email}}が取得する買い物客のメールアドレスはuser.emailなので、salla.config.get('user.email', '')を使います。これは想定される一般的なケースです。禁止パラメーターのルールを過度に気にして、利用可能なデータを使わずに残さないでください。このルールが禁止しているのは古い名前空間であり、基になるデータではありません。
4. **その意味を持つフィールドがなければ、クライアントサイドでは利用できません。**パス、エイリアス、近似的な代替手段を作り出さないでください。そのデータなしで動作するよう、周囲のロジックを書き換えます（たとえば、意味の異なるstore.*データから偽の挨拶文を作るのではなく、パーソナライズされた挨拶を削除します）。
5. **{{app.<key>}}とstore.contacts.*は、上記のパラメーターモデルに従って直接変換します。**意味を調べる必要はなく、変更不要の実在するフィールドです。

salla.config.get(...)の第 2 引数には、必ず''のフォールバックを指定してください。

ゲート：

• 出力のどこにも、単独の{{...}}トークンが残っていないこと。
• 出力にsalla.config.get('customer...／"customer...または salla.config.get('store.domain'...／"store.domain"...が一切含まれていないこと。これはスタイル上の推奨事項ではなく、必須条件です。いずれかが含まれていれば、変換は完了していません。
• 実際に置き換え可能なトークンはすべて、置き換え先を使っていること。出力にdevice-mode.mdのカタログで実際にアクセス可能とされているデータが欠けていてはいけません。
• マーチャント条件付きの読み取り（store.contacts.*）はすべて、使用前に null チェックされていること。

---

ステップ 4 — salla.onReadyでラップする

salla.config.get(...)を呼び出す、または DOM を挿入／変更する（スタイル／マークアップの挿入、トークンによる<script src>の読み込み）変換済みのブロックはすべて、salla.onReady(() => { ... })の中に入れてください。product::*／cart::*のsalla.event.on(...)リスナーはトップレベルのまま、onReadyの外側に置いてください。Twilight はonReadyが呼び出される前の初期化中にこれらのイベントを発行するため、onReady内で登録したリスナーはイベントを取り逃します。これは、references/device-mode.mdで salla-snippetsがすでに説明しているブートストラップのタイミングルールです。新しいコードだけでなく、変換後の出力もこのルールに従ってください。

**ゲート：**すべてのsalla.config.getの呼び出し箇所と DOM 書き込みがonReadyの中にあり、未解決の設定に依存するトップレベルコードがないこと。

ステップ 5 — Public フラグの確認

すべての app.<key> 参照について、Partners Portal で対応する App Setting に Public が設定されていることを確認します（または、修正のために salla-app-settings に引き継ぎます）。キーが Public でない場合、変換のほかの部分がどれだけ正しくても、ストアフロントでは undefined として読み取られます。

**ゲート：**変換後の出力が読み取るすべての app.<key> について、Public に設定されていることを確認済みです。

---

ステップ 6 — 引き継ぎ

結果が有効な JS として解析できること（node --check または同等の方法で確認します。これは salla-snippets が保存前に毎回実行する確認と同じです）を確認します。実際に salla_snippets ツールで create／update を実行し、書き込みごとに禁止パラメーターを独立して再確認する検証ループを実行するため、salla-snippets のステップ 2 に引き継ぎます。このスキルの役割はここまでです。MCP ツールは呼び出しません。

ゲート：「変換後のコンテンツは有効な JS として解析でき、customer.*／store.domain の参照はゼロですか？ salla-snippets のステップ 2 に引き継いでください。」

---

注意すべき点

つい考えてしまうこと	なぜ間違いなのか
「生の移行ドキュメントに {{customer.id}} → user.id とあるので、その名前に変更します」	このスキルのパラメーターモデルは、生のドキュメントより優先されます。customer.* は user.* に名前を変更するのではなく、使用禁止です。user.* は別の概念（購入者）であり、機械的な検索・置換ではなく、実際に必要なデータを確認して参照します。
「HTML タグを取り除いて、トークンは引用符で囲んだ文字列として残しておけばよいでしょう」	トークンは自動で解決されなくなりました。JS 内に {{...}} を残すと、テンプレートではなくリテラル文字列になります。salla.config.get(...) の呼び出しに書き換えるか、利用不可としてフラグを付ける必要があります。
「テストでは store.contacts.whatsapp が解決されたので、ガードなしで読み取ります」	実在しますが、加盟店の設定によって異なります。加盟店が WhatsApp を連絡手段として設定した場合にのみ存在します。ガードなしでリリースすると、設定していない加盟店では動作しません。
「{{store.domain}} の実行時の代替手段がないので、store.url で近似します」	store.url は、このキットのパラメーターモデルでは確認されていません。もっともらしい代替値を捏造することは、まさに禁止されている行為です。データは利用不可としてフラグを付け、その旨を示してください。
「生のドキュメントの使用例ではトップレベルで salla.config.get を読み取っているので、それに合わせます」	その生のドキュメントは、このキットの初期化タイミングのルールより古いか、そのルールが記載されていません。window.salla はすぐに存在しますが、salla.onReady が実行されるまでは、その設定が読み込み済みである保証はありません。ラップしてください（ステップ 4）。
「customer.* は使用禁止なので、代替を探す代わりにデータを丸ごと削除します」	それは正確さではなく、過度な慎重さです。ほとんどの customer.* の読み取りには、user.* に実在する利用可能な代替手段があります（ステップ 3 の意味の照合を参照）。実際に取得可能なデータを削除すると、加盟店が気づく回帰につながります。カタログに対応するフィールドがないことを確認した場合に限り、省略してください。

---

リソース

参考資料としてのみお読みください。パラメータモデルと上記のブートストラップのタイミング規則が、このキットの正式な仕様であり、これらのドキュメントと食い違う場合は、ドキュメントの記述より優先されます（特に、移行ガイドの旧名称から新名称への対応表と、両方のドキュメントにあるラップされていない実例）。

トピック	リンク
アプリスニペットの概要	https://docs.salla.dev/2220706m0.md
HTML→JS 移行ガイド	https://docs.salla.dev/2247590m0.md