litium-developer

Litium 開発者

概要

Litium プラットフォーム上で開発を行うパートナー開発者は、実装ガイダンスとしてこのスキルを使用します。このスキルは、クラウドへのデプロイには litium-cloud-cli スキルを、Litium のレガシークラウドから Serverless Cloud へのサイト移行には litium-cloud-migration スキルを利用します。React Accelerator、MVC、データモデリング、API など、その他の Litium に関するトピックについては、必要に応じて参照ファイルを読み込みます。

Litium プラットフォームのファイルの変更を支援する前に、必ず references/partner-guidance.md を最初に読んでください。

委任

この分野では、以下に指定されたスキルに全面的に委任してください。ここで内容を重複させないでください。

トピック	使用するスキル
Litium Serverless Cloud の運用：デプロイ、環境、アプリと YAML マニフェスト、アーティファクト、シークレット、アクセス制御、バックアップと復元、カスタムドメイン、サービスプリンシパルを使用した CI/CD	litium-cloud-cli
Litium のレガシークラウド（Windows/IIS、Web Deploy）から Serverless Cloud への既存サイトの移行：評価、Linux 対応のコード変更、レガシーバックアップからのテスト環境、パイプラインの変換、リハーサルと本番稼働手順書、MIGRATION.md	litium-cloud-migration

リファレンスマップ

ユーザーのタスクで該当する分野が必要な場合に限り、次のファイルを読み込んでください。

リファレンスファイル	ユーザーが次の内容について質問した場合に読み込む
references/partner-guidance.md	パートナーが変更できること／できないこと、適切な拡張パターン、内部 API に関する免責事項、保護対象プロジェクト、NuGet フィード、Elasticsearch のインデックス分離
references/setup-empty-project.md	Litium の素の環境、空のプロジェクト、素のプラットフォームのインストール、Litium のローカルへのダウンロード、litemptyweb テンプレートのセットアップ
references/setup-mvc-accelerator.md	MVC Accelerator のローカルへのインストール、litmvcacc テンプレート、yarn ビルド、バックオフィスへのアクセラレーターのデプロイ
references/setup-react-accelerator.md	React Accelerator のローカルへのインストール、litreactacc テンプレート、ストアフロントプロキシ、.env.local、ヘッドレスアクセラレーター
references/setup-troubleshooting.md	セットアップエラー、ローカル環境の問題、インストール失敗、SQL 接続、証明書、ポートの競合、パッケージの復元
references/mvc-accelerator.md	MVC 開発、.NET コントローラー、Razor ビュー、ビューモデル、webpack クライアントビルド、MVC + React コンポーネント、Elasticsearch を使った MVC
references/data-modelling.md	カスタムフィールドタイプ、フィールドタイプの作成、フィールドテンプレート、フォルダーテンプレート、商品テンプレート、複数フィールド、テンプレートにないフィールド、FieldTypeMetadataBase
references/cart-and-wishlist.md	カート、チェックアウト、注文、ウィッシュリスト、addVariantToCart、createCheckoutSession、placeOrder、CartContext、BuyButton、決済ウィジェット
references/apis.md	Admin Web API、Storefront GraphQL API、Connect ERP API、Payment API、Shipment API、Extension Management API、OpenAPI 仕様
references/forum-api.md	forum.litium.com の検索、コミュニティでの解決策、Discourse API、フォーラムの投稿の検索
references/react-accelerator/overview.md	React Accelerator の開発、Next.js アーキテクチャ、サーバーコンポーネントとクライアントコンポーネント、GraphQL のパターン、コンポーネントの規約、テスト
references/react-accelerator/template-routing.md	ページ／商品／カテゴリ／ブロックテンプレートの作成、プロキシルーティング、[[...slug]] キャッチオール、テンプレートの命名規則
references/react-accelerator/code-patterns.md	React Accelerator のコードパターン、queryServer、mutateClient、サービスレイヤー、フラグメント、Apollo Client の使用方法
references/react-accelerator/project-structure.md	React Accelerator のディレクトリ構成、app/、components/、services/、operations/ フォルダー
references/react-accelerator/graphql-sdl.md	Storefront GraphQL SDL の取得、スキーマのダウンロード、RUNTIME_LITIUM_SERVER_URL、利用可能な操作
references/extension/cli-commands.md	新しい拡張機能のスキャフォールド、create コマンド、add コマンド、dev コマンド、@litiumab/platform-extension-sdk CLI
references/extension/manifest-reference.md	extension.manifest.json のフィールド、ターゲット、common.web-component、admin.menu-item、admin.settings-page、api.proxy、customElementTag、bundleUrl
references/extension/bridge-api.md	window.litiumExtension、navigate()、replaceUrl()、showNotification()、getContext()、on()、off()、routeChanged、contextChanged
references/extension/framework-patterns.md	Custom Element のエントリーポイント、React 拡張機能、Vue 拡張機能、Angular 拡張機能、Vanilla 拡張機能、パネルコンポーネント、Admin Web API リクエスト
references/extension/routing.md	サブパスルーティング、MemoryRouter、createMemoryHistory、MemoryLocationStrategy、sub-path 属性、routeChanged、ディープリンク
references/extension/testing.md	拡張機能の単体テスト、window.litiumExtension のモック、Vitest、Jest、@testing-library/react、@vue/test-utils
references/extension/deployment.md	拡張機能のインストール、有効化、Extension Management API、bundleUrl、HTTPS、CDN、Settings > Extensions、IIFE バンドル

ドキュメントの検索優先順位

1. 優先：https://docs.litium.dev/ — 公式ドキュメントは必ず最初に確認してください。
2. コミュニティ：https://forum.litium.com/ — 実際の解決策を探す場合に利用します。プログラムから検索するには、references/forum-api.md を読み込んでください。

クイックスタートの振り分け

ステップ 0（必ず実施）: パートナーが変更できるものとできないものを把握するため、最初に references/partner-guidance.md を読んでください。

• 「React ストアフロントで作業するにはどうすればよいですか？」 → 最初に references/react-accelerator/overview.md を読み、必要に応じて関連するリファレンス（template-routing、code-patterns など）を読み込んでください。
• 「Litium Cloud 環境をデプロイ／管理するにはどうすればよいですか？」 → litium-cloud-cli に委任してください。
• 「サイトをレガシークラウドから Serverless Cloud に移行するにはどうすればよいですか？」 → litium-cloud-migration に委任してください。
• 「Litium をローカル環境にセットアップするにはどうすればよいですか？」 → 該当するセットアップリファレンス（empty／MVC／React）を読み込んでください。
• 「カートやウィッシュリストの機能を追加するにはどうすればよいですか？」 → references/cart-and-wishlist.md を読み込んでください。
• 「カスタムフィールドの種類やフィールドテンプレートを作成するにはどうすればよいですか？」 → references/data-modelling.md を読み込んでください。
• 「Admin Web API や Connect API を呼び出すにはどうすればよいですか？」 → references/apis.md を読み込んでください。
• 「バックオフィス UI 拡張機能を構築するにはどうすればよいですか？」 → 最初に references/extension/cli-commands.md を読み、必要に応じて関連するリファレンス（framework-patterns、bridge-api、routing など）を読み込んでください。
• 「拡張機能にパネルや設定ページを追加するにはどうすればよいですか？」 → references/extension/cli-commands.md を読み込んでください（必ず CLI を使用し、ファイルを手動で作成しないでください）。
• 「拡張機能でページ遷移したり通知を表示したりするにはどうすればよいですか？」 → references/extension/bridge-api.md を読み込んでください。

バックオフィス UI 拡張機能のアーキテクチャ

拡張機能は、IIFE バンドルとして読み込まれる Web Components（カスタム要素） です。Angular 20 の管理ホストから完全に分離されて実行され、React、Vue、Angular、Vanilla JavaScript のいずれも使用できます。ホストは window.litiumExtension のみを介して拡張機能と通信します。

┌───────────────────────────────────────────────────────────┐
│  Litium Admin (Angular 20 host)                           │
│                                                           │
│  ┌─────────────────────────────┐                         │
│  │  <litium-ext-my-widget>     │  ← Custom Element       │
│  │                             │    (your extension)     │
│  │  ┌─────────────────────┐   │                         │
│  │  │   Your framework    │   │                         │
│  │  │   (React / Vue /    │   │                         │
│  │  │    Angular / Vanilla│   │                         │
│  │  └─────────────────────┘   │                         │
│  │            │               │                         │
│  │            ▼               │                         │
│  │  window.litiumExtension     │  ← Bridge API           │
│  └─────────────────────────────┘                         │
│              │                                            │
│  navigate() · showNotification() · getContext()           │
│  on('routeChanged') · on('contextChanged') · off()        │
└───────────────────────────────────────────────────────────┘

拡張機能に関する重要なルール

これらのルールはすべての拡張機能で必ず守ってください。違反すると実行時エラーが発生します。

必ず CLI を使用し、ファイルを手動で作成しない

新しいプロジェクトのスキャフォールディング、パネルの追加、または設定ページの追加には、必ず @litiumab/platform-extension-sdk CLI を使用してください（references/extension/cli-commands.md を参照）。コンポーネントファイル、マニフェストエントリー、インデックスインポートを手動で作成してはいけません。CLI がこれらすべてを正しく処理します。

手動でコードを書くのは、生成されたコンポーネントファイル内（UI ロジックの実装）のみにしてください。

カスタム要素のタグの命名

• すべてのタグは litium-ext- で始める必要があります。
• パターン：メイン要素は litium-ext-{extension-id}
• パネル：litium-ext-{extension-id}-panel-{slug}
• 正規表現 /^litium-ext-[a-z][a-z0-9-]*$/ に一致する必要があります。

customElements.define のガード

if (!customElements.get('litium-ext-my-extension')) {
  customElements.define('litium-ext-my-extension', MyElement);
}

イベントの購読解除

disconnectedCallback／onUnmounted／ngOnDestroy で、必ず window.litiumExtension.on() の購読を解除してください。解除しないとメモリーリークが発生します。

routeChanged ハンドラー内で navigate() を呼び出さない

無限ループが発生します。navigate() はユーザー操作への応答としてのみ呼び出してください。

メモリーベースのルーティングを使用

拡張機能から history.pushState を直接呼び出してはいけません。MemoryRouter（React）、createMemoryHistory（Vue）、または MemoryLocationStrategy（Angular）を使用してください。

NPM レジストリの設定

# .npmrc
@litiumab:registry=https://registry.npmjs.org/

拡張機能のクイックワークフロー

新しい拡張機能の作成

1. references/extension/cli-commands.md を読む
2. 使用するフレームワークをユーザーに確認する：react、vue、angular、または vanilla
3. 実行する：npx @litiumab/platform-extension-sdk create <name> --framework <framework>
4. cd <name> && npm install
5. 選択したフレームワークに応じて references/extension/framework-patterns.md を読む
6. 開発サーバーを起動する：npm run dev
7. Litium の Settings > Extensions で登録する（references/extension/deployment.md を参照）

パネル／設定ページの追加

1. references/extension/cli-commands.md を読みます
2. 拡張機能プロジェクトのルートから、npx @litiumab/platform-extension-sdk add panel または add settings-page を実行します
3. CLI がコンポーネントファイルを生成し、マニフェストを更新して、インポートを挿入します
4. 設定ページの場合：フレームワークのルーターにルートを追加します（references/extension/routing.md を参照）

ビルドとデプロイ

1. references/extension/deployment.md を読みます
2. npm run build — dist/extension.js を生成します
3. CDN またはホスティングサーバーにアップロードします（本番環境では HTTPS が必須です）
4. extension.manifest.json の bundleUrl を更新します
5. Settings > Extensions からインストールするか、Extension Management API に POST します

拡張機能でよくある間違い

症状	根本原因	対処法
管理 API の呼び出しで 403 Forbidden が発生する	有効な bearer token を指定せずに /Litium/api/admin/ を呼び出している	VITE_LITIUM_CLIENT_ID と VITE_LITIUM_CLIENT_SECRET を使用して OAuth トークンをリクエストし、Authorization ヘッダーに指定します
拡張機能が空白になる／描画されない	マニフェストとコードでカスタム要素タグが一致していない	customElements.define() のタグがマニフェストの customElementTag と一致することを確認します
戻るボタンが機能しない	ブリッジ API ではなくフレームワークのルーターを使用している	境界をまたぐナビゲーションには window.litiumExtension.navigate() を呼び出します
再レンダリングが無限に続く	routeChanged ハンドラー内で navigate() を呼び出している	ユーザー操作に応じてのみ navigate() を呼び出します
ホットリロードエラー：要素はすでに定義されています	customElements.get() によるガードがない	ガードパターンで customElements.define() を囲みます
SDK で npm ERR! 404 Not Found が発生する	.npmrc のレジストリ設定がない	.npmrc に @litiumab:registry=https://registry.npmjs.org/ を追加します
ディープリンクでルートページが読み込まれる	初回レンダリング時に sub-path 属性を読み取っていない	connectedCallback で getAttribute('sub-path') を読み取ります
チャネル切り替え後にコンテキストが古いままになる	getContext() の結果を永久にキャッシュしている	contextChanged イベントをサブスクライブします
アンマウント時にメモリーリークの警告が表示される	イベントのサブスクライブを解除していない	disconnectedCallback／クリーンアップフックでサブスクライブ解除関数を呼び出します