# 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 the content below to `.claude/skills/` or append to your `CLAUDE.md`:

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

## FAQ

**Q: What's the difference between Medusa v1 and v2?**
A: v2 is a complete rewrite that introduces a modular architecture, a Workflows business-logic engine, and a new JS SDK. It's more flexible than v1 and better suited to complex commerce scenarios. New projects should use v2.

**Q: Which frontend frameworks can I use?**
A: Any framework works. The official starter template uses Next.js. The community offers templates for Nuxt.js, Gatsby, and SvelteKit. Connect to the Medusa backend via the JS SDK or REST API.

**Q: Is it suitable for e-commerce in the Chinese market?**
A: Medusa's multi-region features support RMB pricing and China-specific tax configurations. Payment integration requires custom payment providers for WeChat Pay and Alipay. For logistics, you can hook up Chinese courier APIs via custom fulfillment providers.

## Sources & Credits

- GitHub: [medusajs/medusa](https://github.com/medusajs/medusa) — 32.6K+ ⭐ | MIT
- Website: [medusajs.com](https://medusajs.com)

---
Source: https://tokrepo.com/en/workflows/medusa-open-source-headless-commerce-engine-ca8df7e8
Author: Script Depot