Medusaは、注文・商品・在庫・価格などの機能をモジュール単位で組み合わせるヘッドレスコマースプラットフォームです。coreパッケージ、モジュール群、ワークフローエンジンをyarn workspacesでまとめたモノレポとして配布されています。ソースにはAPIルート定義、Jestベースの統合テスト、Claude向けskill定義まで含まれています。
medusa-config.jsで有効化したモジュール（auth、product、pricing、promotionなど）がコンテナに登録され、src/api配下のルートから呼び出される仕組みです。route.tsではdefineFileConfigで機能フラグ（FeatureFlag.isFeatureEnabled）によりルート自体を無効化でき、middlewares.tsではdefineMiddlewaresとzodスキーマでリクエストを検証します。複雑な業務処理はcore-flows・workflows-sdkのワークフローとして手順化され、モジュールサービスを順に呼び出します。integration-tests/httpの仕様書はmedusaIntegrationTestRunnerを使い、実際のPostgresに対して管理者ユーザーを作成し、APIキーの発行・更新・失効・削除までのライフサイクルをHTTPリクエストで検証しています。changeset/config.jsonにより多数のワークスペースパッケージのバージョンを一括管理する運用になっています。
- STEP 01
yarn installを実行すると、core・modules・pluginsなど非常に多いワークスペースパッケージが一括で解決されるのを体感します。
- STEP 02
medusa-config.jsでDATABASE_URLなどを設定し開発サーバーを起動すると、有効化したモジュールだけがコンテナに読み込まれます。
- STEP 03
integration-tests/httpでtest:integrationを実行すると、Jestがテスト用Postgresを使ってサーバーを起動し、createAdminUserで管理者を作成します。
- STEP 04
api-key.spec.tsのようなテストが走ると、/admin/api-keysへのPOSTでsk_接頭辞付きトークンが発行され、更新・失効・削除まで一連の挙動が確認できます。
- STEP 05
feature-flagのfixtureを試すと、CUSTOM_FF環境変数を設定しない限り/customルート自体が無効のままであることに気づきます。
- STEP 06
changesetsのワークフローに触れると、1つの変更が@medusajs/*配下の多数のパッケージバージョンへ連動して反映される様子が見えます。
実行環境が整えば、管理者APIやAPIキー管理などを備えたコマースバックエンドが手元で立ち上がります。あわせて、実際の挙動を裏付ける統合テスト一式と、多パッケージ構成を安全にリリースするchangesetsの仕組みが手に入ります。
ワークスペースパッケージの数が非常に多く、yarn installとビルドに相応の時間がかかると見込まれます。
統合テストはインメモリではなく実際のPostgres接続を前提としており、DB未準備では動かせません。
一部ルートやモデルはFeatureFlagで既定無効になっており、env_keyを設定しないと存在自体に気づけません。
ENTERPRISE-LICENSE.mdが同梱されており、リポジトリ内の一部機能はMITと異なるライセンス条件である可能性があります。
自前のコマースバックエンドをモジュール構成で組みたい開発者や、AIコーディングエージェントと組み合わせた開発フローを試したいチームに向いています。route.ts・middlewares.ts・api-key.spec.tsなど実際のソースとテストが揃っており、機能フラグやワークフロー、APIキーのライフサイクルまで具体的に裏付けが取れるため、未実行でもこの評価は一定の根拠を持てます。ただし大規模モノレポかつDB前提の構成なので、実運用の負荷感は自分の環境で確認する価値があります。