Medusa — Open Source Headless Commerce Engine

What Medusa Does

• Product Management: Products, variants, categories, collections, inventory, and pricing
• Order Processing: Cart, checkout, payment capture, fulfillment, returns, and exchanges
• Customer Management: Accounts, addresses, groups, and order history
• Payment Integration: Stripe, PayPal, and custom payment providers
• Shipping: Custom shipping options, fulfillment providers, and rate calculation
• Multi-Region: Per-region pricing, currencies, tax rates, and shipping options
• Promotions: Discount codes, percentage/fixed, free shipping, and buy-X-get-Y
• Admin Dashboard: React-based admin panel with full commerce management
• Storefront: Next.js starter storefront included

Architecture (Medusa v2)

┌──────────────┐     ┌──────────────────────┐     ┌──────────────┐
│  Storefront  │────▶│  Medusa Application   │────▶│  PostgreSQL  │
│  (Next.js)   │     │  ┌────────────────┐   │     └──────────────┘
└──────────────┘     │  │  Modules       │   │
                     │  │  ┌──────────┐  │   │
┌──────────────┐     │  │  │Product   │  │   │
│  Admin UI    │────▶│  │  │Order     │  │   │
│  (React)     │     │  │  │Customer  │  │   │
└──────────────┘     │  │  │Payment   │  │   │
                     │  │  │Shipping  │  │   │
                     │  │  │Inventory │  │   │
                     │  │  └──────────┘  │   │
                     │  └────────────────┘   │
                     └──────────────────────┘

Getting Started

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

# Choose:
# - PostgreSQL database
# - Next.js storefront (optional)
# - Seed data for testing

cd my-store
npx medusa develop

Project Structure

my-store/
├── src/
│   ├── modules/        # Custom commerce modules
│   ├── workflows/      # Business logic workflows
│   ├── api/           # Custom API routes
│   ├── subscribers/   # Event subscribers
│   └── jobs/          # Background jobs
├── medusa-config.ts   # Configuration
└── package.json

Key Features

Modular Commerce

Each commerce capability is an independent module:

// medusa-config.ts
module.exports = defineConfig({
  modules: [
    { resolve: "@medusajs/medusa/product" },
    { resolve: "@medusajs/medusa/order" },
    { resolve: "@medusajs/medusa/customer" },
    { resolve: "@medusajs/medusa/payment" },
    { resolve: "@medusajs/medusa/inventory" },
    // Add custom modules
    { resolve: "./src/modules/loyalty" },
  ],
});

Workflows (Business Logic)

import { createWorkflow, createStep } from "@medusajs/framework/workflows-sdk";

const validateInventoryStep = createStep("validate-inventory", async ({ items }) => {
  // Check stock availability
  for (const item of items) {
    if (item.quantity > item.available) {
      throw new Error(`Insufficient stock for ${item.title}`);
    }
  }
  return items;
});

export const customCheckoutWorkflow = createWorkflow("custom-checkout", (input) => {
  const validated = validateInventoryStep(input);
  // Add more steps: apply discount, calculate tax, create order
  return validated;
});

JS SDK (Storefront)

import Medusa from "@medusajs/js-sdk";

const medusa = new Medusa({ baseUrl: "http://localhost:9000", publishableKey: "pk_..." });

// List products
const { products } = await medusa.store.product.list();

// Add to cart
const cart = await medusa.store.cart.create({});
await medusa.store.cart.createLineItem(cart.id, {
  variant_id: "variant_123",
  quantity: 2,
});

// Complete checkout
await medusa.store.cart.complete(cart.id);

Custom API Routes

// src/api/store/custom/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const productModule = req.scope.resolve("product");
  const products = await productModule.listProducts({
    tags: { value: ["featured"] },
  });
  res.json({ products });
}

Medusa vs Alternatives

常见问题

Q: Medusa v1 和 v2 有什么区别？ A: v2 是完全重写的版本，引入了模块化架构、Workflows 业务逻辑引擎和新的 JS SDK。v2 比 v1 更灵活，更适合复杂的商业场景。新项目应该使用 v2。

Q: 前端可以用什么框架？ A: 任何框架都可以。官方提供 Next.js 起始模板。社区有 Nuxt.js、Gatsby、和 SvelteKit 的模板。通过 JS SDK 或 REST API 连接 Medusa 后端。

Q: 适合中国市场的电商吗？ A: Medusa 的多区域功能支持人民币定价和中国特有的税率配置。支付集成需要自定义开发微信支付和支付宝的 payment provider。物流可以通过自定义 fulfillment provider 对接中国快递 API。

来源与致谢

• GitHub: medusajs/medusa — 32.6K+ ⭐ | MIT
• 官网: medusajs.com