medusajs-developer

MedusaJS 開発者エージェントスキル

MedusaJS v2.15+ 開発を専門とするエキスパートエージェントです。カスタムモジュール、API 統合、サードパーティ製プラグインを活用した、スケーラブルな E コマースソリューションの構築に重点を置いています。

主な機能

1. カスタムモジュール開発

• データモデル：MedusaJS DML を使用してデータモデルを作成、管理します
• モジュールサービス：CRUD 操作を自動化するサービスレイヤーを実装します
• モジュール設定：適切なモジュール構造とエクスポートを設定します
• データベースマイグレーション：データベーススキーマの変更を生成、管理します

2. API ルート開発

• カスタムエンドポイント：src/api/[route-name]/route.ts に REST API ルートを作成します
• HTTP メソッド：GET、POST、PUT、DELETE のハンドラーを実装します
• リクエスト／レスポンス処理：MedusaRequest オブジェクトと MedusaResponse オブジェクトを管理します
• 認証：MedusaJS の認証システムと統合します

3. コマースモジュールの統合

• 組み込みの 18 モジュール：API Key、Auth、Cart、Customer、Order、Payment、Product、Pricing、Promotion、Tax などを扱います
• モジュールリンク：異なるモジュール間の関係を作成します
• カスタムフィールド：既存のモジュールを追加のデータフィールドで拡張します
• モジュール構成：複数のモジュールを組み合わせて複雑なワークフローを実現します

4. ワークフローと自動化

• スケジュール済みジョブ：cron 式を使って定期タスクを作成します
• イベント処理：非同期操作のためのサブスクライバーを実装します
• ビジネスロジック：複雑なコマースワークフローをオーケストレーションします
• バックグラウンド処理：長時間実行される操作を効率的に処理します

5. サードパーティ統合

• 決済プロバイダー：カスタム決済ゲートウェイを統合します
• 外部 API：配送、税、在庫サービスと接続します
• Webhook：外部システムからの受信 Webhook を処理します
• データ同期：外部プラットフォームとデータを同期します

Medusa v2.15+ の更新情報

認証とセキュリティ

• Medusa v2.15+ には、認証フロー向けの MFA プリミティブが組み込まれています。
• OTP の保存を独自に実装するのではなく、モジュールが管理する TOTP、SMS、リカバリーコードのチャレンジを優先してください。
• MFA をサインイン、登録、チャレンジ、検証、リカバリーの各フローの一部として扱い、Auth モジュールに組み込んでください。

// Pseudocode: branch on auth result and ask the Auth module to challenge/verify MFA
const result = await authModule.authenticate(credentials)

if (result.mfa_required) {
  await authModule.mfa.challenge({
    user_id: result.user_id,
    method: "totp", // "sms" | "recovery_code"
  })
}

プロモーション

• プロモーションのワークフローでは、条件付き適用のためのコンテキストフックを利用できます。
• customer_group、sales_channel_id、region、キャンペーンのメタデータなどのコンテキストデータをワークフローに渡すと、プロモーションルールで評価できます。
• 例：context.customer_group === "wholesale" の場合にのみ、卸売向けプロモーションを適用します。

カタログ検索

• 商品でネイティブな SKU 検索がサポートされるようになりました。
• 販売者向けまたはフルフィルメント向けの識別子でバリアントを検索する場合は、商品検索リクエストで SKU フィルターを使用してください。
• 例：SKU とキーワードを組み合わせて検索し、カタログクエリを絞り込みます。

GET /store/products?query=hoodie&sku=HD-001-BLK-M

クラウドとプラットフォーム

• Cloud 環境のデバッグや、ローカルアプリに対する Webhook のテストには、セキュアなローカルからクラウドへのトンネリングに mcloud proxy を使用してください。
• サードパーティサービスに公開コールバック URL が必要でありながら、バックエンドをローカルに保ちたい場合に使用します。

データモデルに関する注意事項

• Float 属性がデータモデルで統一されました。カスタム数値フィールドのモデリングには、更新された属性型を使用してください。

重要なマイグレーションに関する注意事項

• Medusa v2.15.2 には MikroORM v6.6.12 のセキュリティ更新が含まれ、v6.13.6 のスナップショットに関するリグレッションが修正されています。
• v2.13.6+ を使用している場合は、本番環境のマイグレーションを実行する前にアップグレードし、古いスナップショットを先に削除してください。

npx medusa db:migrate --clean-snapshots

• アップグレード中はすべての @medusajs/* パッケージを同じリリース系列に固定し、バージョンの部分的な不整合を避けてください。

開発パターン

モジュール構造

// src/modules/my-module/models/post.ts
import { model } from "@medusajs/framework/utils"

const Post = model.define("post", {
  id: model.id().primaryKey(),
  title: model.text(),
  content: model.text().nullable(),
  published: model.boolean().default(false)
})

export default Post

API ルートの例

// src/api/posts/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const postService = req.scope.resolve("postService")
  const posts = await postService.listPosts()
  
  res.json({ posts })
}

export const POST = async (req: MedusaRequest, res: MedusaResponse) => {
  const postService = req.scope.resolve("postService")
  const post = await postService.createPost(req.body)
  
  res.json({ post })
}

スケジュール済みジョブの例

// src/jobs/sync-inventory.ts
import { MedusaContainer } from "@medusajs/framework/types"

export default async function syncInventoryJob(container: MedusaContainer) {
  const inventoryService = container.resolve("inventoryService")
  await inventoryService.syncWithExternalProvider()
}

export const config = {
  name: "sync-inventory",
  schedule: "0 */6 * * *" // Every 6 hours
}

ベストプラクティス

1. プロジェクトのセットアップ

• プロジェクトの初期化には MedusaJS CLI を使用します
• TypeScript のベストプラクティスに従います
• 適切なエラーハンドリングを実装します
• 包括的なテストを設定します

2. モジュール設計

• モジュールは単一のドメインに特化させます
• 明確な命名規則を使用します
• 適切なバリデーションを実装します
• モジュールのインターフェースを文書化します

3. API 設計

• RESTful の規約に従います
• 適切な HTTP ステータスコードを使用します
• リストエンドポイントにはページネーションを実装します
• 入力データを徹底的に検証します

4. パフォーマンスの最適化

• データベースのインデックスを適切に使用します
• キャッシュ戦略を実装します
• データベースクエリを最適化します
• 大規模なデータセットを効率的に処理します

5. 統合パターン

• 設定には環境変数を使用します
• 外部への呼び出しにはリトライ機構を実装します
• レート制限に適切に対処します
• 統合のアクティビティを適切にログに記録します

一般的なタスク

新しいモジュールの作成

1. モジュールのディレクトリ構造を作成します
2. 適切なリレーションを持つデータモデルを定義します
3. ビジネスロジックを含むサービスレイヤーを実装します
4. データベースのマイグレーションを生成して実行します
5. モジュールの操作用 API ルートを作成します
6. 包括的なテストを追加します

サードパーティとの統合の設定

1. 必要な依存関係をインストールします
2. 環境変数を設定します
3. 外部 API との通信を行うサービスを作成します
4. 必要に応じて Webhook ハンドラーを実装します
5. エラー処理とログ記録を追加します
6. 統合を徹底的にテストします

カスタムワークフローの実装

1. ビジネスプロセスの手順を特定します
2. 必要なデータモデルを作成します
3. ワークフローのオーケストレーションを実装します
4. 状態変更に対応するイベントハンドラーを追加します
5. 監視とアラートを作成します
6. ワークフローの動作を文書化します

トラブルシューティング

よくある問題

• マイグレーションの失敗：モデル定義とデータベース制約を確認します
• サービスの解決：モジュールのエクスポートと依存関係の注入を確認します
• API エラー：リクエスト／レスポンス形式と認証を検証します
• パフォーマンスの問題：データベースクエリを分析し、キャッシュを実装します

デバッグ戦略

• MedusaJS のデバッグツールを使用します
• アプリケーションログでエラーを確認します
• データベーススキーマがモデルと一致していることを確認します
• 適切なヘッダーを指定して API エンドポイントをテストします
• 外部サービスの応答を監視します

コードテンプレート

このスキルには、MedusaJS の公式ドキュメントとベストプラクティスに基づいた、本番環境ですぐに使えるコードテンプレートが templates/ ディレクトリに含まれています。

利用可能なテンプレート

module-complete.ts

以下を含む、カスタムモジュールの完全な構成です。

• さまざまなプロパティ型を持つ複数のデータモデル
• 1 対多および多対多のリレーション
• カスタムメソッドを備えたメインサービス
• 依存関係の注入を備えた追加サービス

使用例： カスタムモジュール（ブログ、ブランド、レストランなど）の作成

api-route-complete.ts

以下を含む、完全な REST API ルートです。

• GET、POST、PUT、DELETE のハンドラー
• Zod バリデーションスキーマ
• 認証およびバリデーションのミドルウェア
• エラー処理とログ記録
• 関連データのクエリ統合

使用例： API エンドポイント経由でのモジュール機能の公開

workflow-complete.ts

以下を含む、完全なワークフローです。

• 補償関数を備えた複数のステップ
• ステップ間のデータ変換
• 条件付き実行
• Medusa モジュールとの統合

使用例： ロールバックが必要な複雑なビジネスロジック

subscriber-complete.ts

イベントサブスクライバーのパターンです。

• 基本的なイベント処理
• サブスクライバー内でのワークフロー実行
• 複数イベントのサブスクライバー
• リトライロジックとエラー処理

使用例： Medusa イベント（order.placed、product.created など）への対応

module-link.ts

モジュールリンクのパターンです。

• モジュール間の基本的なリンク
• リストリンク（1 対多）
• リンクテーブルのカスタム列
• リンクの作成、解除、クエリ

使用例： 異なるモジュール間のリレーションの作成

scheduled-job.ts

スケジュールジョブのパターンです。

• 基本的なスケジュールタスク
• バッチ処理
• 外部 API との統合
• 一般的な cron パターン

使用例： 繰り返し実行する自動化タスク（同期、クリーンアップ、レポート）

テンプレートの使用例

# Copy template to your project
cp templates/module-complete.ts src/modules/brand/

# Customize for your needs
# - Rename identifiers
# - Add/remove properties
# - Implement business logic

# Generate and run migrations
./scripts/generate-migration.sh brand
./scripts/run-migrations.sh

よく使われるテンプレートの組み合わせ

Eコマース拡張：

1. module-complete.ts → カスタムモジュールを作成
2. module-link.ts → Product モジュールにリンク
3. api-route-complete.ts → API エンドポイントを作成
4. workflow-complete.ts → ビジネスロジックを実装
5. subscriber-complete.ts → イベントを処理

データ同期：

1. workflow-complete.ts → 同期ワークフロー
2. scheduled-job.ts → 定期的に実行
3. subscriber-complete.ts → イベントをトリガーに実行

詳しいドキュメント、ベストプラクティス、その他の例については、templates/README.md をご覧ください。

ヘルパースクリプト

このスキルには、一般的な MedusaJS 開発タスクを効率化するためのヘルパースクリプトが scripts/ ディレクトリに含まれています。

データベース管理スクリプト

db-setup.sh

1つのコマンドでデータベースを作成し、マイグレーションを実行してリンクを同期します。

./scripts/db-setup.sh [database-name]

例：

./scripts/db-setup.sh medusa-store

generate-migration.sh

指定したモジュールのマイグレーションファイルを生成します。

./scripts/generate-migration.sh <module-name> [additional-modules...]

例：

./scripts/generate-migration.sh blog
./scripts/generate-migration.sh blog product-custom

run-migrations.sh

リンクやデータマイグレーションをスキップするオプションを指定して、保留中のすべてのマイグレーションを実行します。

./scripts/run-migrations.sh [--skip-links] [--skip-data]

例：

./scripts/run-migrations.sh
./scripts/run-migrations.sh --skip-links

rollback-migration.sh

安全確認を行ったうえで、指定したモジュールの最後のマイグレーションを元に戻します。

./scripts/rollback-migration.sh <module-name> [additional-modules...]

開発・ビルドスクリプト

dev-server.sh

ホットリロードを有効にして、Medusa アプリケーションを開発モードで起動します。

./scripts/dev-server.sh [--host HOST] [--port PORT]

例：

./scripts/dev-server.sh
./scripts/dev-server.sh --host 0.0.0.0 --port 9001

build-production.sh

Medusa アプリケーション全体、または管理画面のみの本番用ビルドを作成します。

./scripts/build-production.sh [--admin-only]

例：

./scripts/build-production.sh
./scripts/build-production.sh --admin-only

start-production.sh

ビルド済みの Medusa アプリケーションを本番モードで起動します。

./scripts/start-production.sh

predeploy.sh

デプロイ前にマイグレーションを実行し、リンクを同期します（CI/CD パイプライン向け）。

./scripts/predeploy.sh

テストスクリプト

setup-testing.sh

Jest と Medusa のテストツールをインストールして設定し、テストディレクトリと設定ファイルを作成します。

./scripts/setup-testing.sh

run-tests.sh

テスト種別を指定するオプションを使って、統合テストと単体テストを実行します。

./scripts/run-tests.sh [http|modules|unit|all]

例：

./scripts/run-tests.sh all
./scripts/run-tests.sh http
./scripts/run-tests.sh modules
./scripts/run-tests.sh unit

スキャフォールディングスクリプト

create-module.sh

サービスとモデルのディレクトリを含む、新しいカスタムモジュールの基本構造を作成します。

./scripts/create-module.sh <module-name>

例：

./scripts/create-module.sh blog

生成される構造：

src/modules/<module-name>/
├── index.ts
├── service.ts
├── models/
└── __tests__/

create-api-route.sh

基本的な CRUD 操作（GET、POST、PUT、DELETE）を備えた新しい API ルートを作成します。

./scripts/create-api-route.sh <route-name>

例：

./scripts/create-api-route.sh posts

生成されるエンドポイント：

• GET /api/<route-name> - すべての項目を一覧表示
• POST /api/<route-name> - 新しい項目を作成
• GET /api/<route-name>/:id - 単一の項目を取得
• PUT /api/<route-name>/:id - 項目を更新
• DELETE /api/<route-name>/:id - 項目を削除

create-scheduled-job.sh

Cron 設定テンプレートを使用して、新しいスケジュール済みジョブを作成します。

./scripts/create-scheduled-job.sh <job-name>

例：

./scripts/create-scheduled-job.sh sync-inventory

よく使われる Cron パターン：

• "0 0 * * *" - 毎日午前0時
• "0 */6 * * *" - 6時間ごと
• "*/15 * * * *" - 15分ごと
• "0 9 * * 1" - 毎週月曜日の午前9時

プラグイン開発スクリプト

plugin-develop.sh

自動再読み込みに対応したプラグイン用開発サーバーを起動します（プラグインのディレクトリから実行）。

./scripts/plugin-develop.sh

plugin-build.sh

NPM で公開するためのプラグインをビルドします（プラグインのディレクトリから実行）。

./scripts/plugin-build.sh

よく使われるワークフロー

新しい機能モジュールの作成

# 1. Create the module structure
./scripts/create-module.sh my-feature

# 2. Add data models in src/modules/my-feature/models/

# 3. Update service.ts with your models

# 4. Generate migrations
./scripts/generate-migration.sh my-feature

# 5. Run migrations
./scripts/run-migrations.sh

# 6. Create API routes
./scripts/create-api-route.sh my-feature

# 7. Write tests
# Add tests in src/modules/my-feature/__tests__/

# 8. Run tests
./scripts/run-tests.sh modules

新しいプロジェクトのセットアップ

# 1. Create new project
npx create-medusa-app@latest my-store

# 2. Setup database
./scripts/db-setup.sh my-store-db

# 3. Setup testing environment
./scripts/setup-testing.sh

# 4. Start development server
./scripts/dev-server.sh

デプロイワークフロー

# 1. Run tests
./scripts/run-tests.sh all

# 2. Build for production
./scripts/build-production.sh

# 3. In CI/CD pipeline, run predeploy
./scripts/predeploy.sh

# 4. Start production server
./scripts/start-production.sh

リソース

• MedusaJS 公式ドキュメント
• コミュニティの Discord とフォーラム
• GitHub リポジトリとサンプル
• プラグインマーケットプレイス
• 開発者ツールと CLI コマンド

このスキルを使うと、保守性と拡張性に優れた E コマースソリューションに重点を置いた、包括的な MedusaJS 開発が可能になります。

バージョン：2.0 最終更新日：2026年5月