# Medusa — Open Source Headless Commerce Engine

> Medusa is an open-source composable commerce engine built with Node.js. Modular architecture, REST & JS SDK, and full customization for building custom storefronts and commerce flows.

## Install

Save as a script file and run:

## Quick Use

```bash
npx create-medusa-app@latest my-store
cd my-store
npx medusa develop
```

Open `http://localhost:9000/app` (Admin) and `http://localhost:8000` (Storefront).

## Intro

**Medusa** is an open-source composable commerce engine designed for developers building custom digital commerce experiences. Built with Node.js and featuring a modular architecture, Medusa provides the building blocks — products, orders, payments, shipping, customers — that you compose into any commerce flow, from a simple online store to complex marketplace and B2B scenarios.

With 32.6K+ GitHub stars and MIT license, Medusa v2 has become a leading open-source Shopify alternative, chosen by developers who need full control over their commerce logic and customer experience.

## 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

```bash
# 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:

```typescript
// 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)

```typescript
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)

```typescript
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

```typescript
// 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

| Feature | Medusa | Shopify | Vendure | Saleor |
|---------|--------|---------|---------|--------|
| Open Source | Yes (MIT) | No | Yes | Yes (BSD) |
| Architecture | Modular | Monolithic | Plugin | Monolithic |
| Language | TypeScript | Liquid | TypeScript | Python |
| API | REST + JS SDK | REST + GraphQL | GraphQL | GraphQL |
| Multi-region | Built-in | Markets | Channels | Channels |
| Customization | Full code | Themes + Apps | Plugins | Apps |
| Admin | Built-in React | Built-in | Built-in Angular | Built-in React |
| Pricing | Free | $39+/mo | Free | Free |

## 常见问题

**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](https://github.com/medusajs/medusa) — 32.6K+ ⭐ | MIT
- 官网: [medusajs.com](https://medusajs.com)

---
Source: https://tokrepo.com/en/workflows/ca8df7e8-34bf-11f1-9bc6-00163e2b0d79
Author: Script Depot