Medusa 开源无头电商系统 - 基于 Node.js 和 TypeScript 的完全可定制电商平台

medusa by alinaqi/claude-bootstrap

83 周安装量

547 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/alinaqi/claude-bootstrap --skill medusa

Node.js TypeScript 电商

🇨🇳中文介绍

Medusa E-Commerce Skill

加载方式：base.md + typescript.md

用于构建基于 Medusa 的无头电商系统 - 开源、原生 Node.js、完全可定制。

资料来源： Medusa 文档 | API 参考 | GitHub

为什么选择 Medusa

功能	优势
开源	自托管，无供应商锁定，MIT 许可证
原生 Node.js	TypeScript，熟悉的开发栈，易于定制
无头架构	支持任何前端（Next.js、Remix、移动端）
模块化	按需使用，可扩展任何功能
内置管理后台	包含仪表板，可自定义

快速开始

先决条件

# 必需
node --version  # v20+ LTS
git --version
# 本地或远程运行 PostgreSQL

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

URL	用途
`http://localhost:9000`	后端 API
`http://localhost:9000/app`	管理仪表板
`http://localhost:8000`	店面（如果已安装）

创建管理员用户

npx medusa user -e admin@example.com -p supersecret

medusa-store/
├── src/
│   ├── admin/                    # 管理界面自定义
│   │   ├── widgets/              # 仪表板小部件
│   │   └── routes/               # 自定义管理页面
│   ├── api/                      # 自定义 API 路由
│   │   ├── store/                # 公共店面 API
│   │   │   └── custom/
│   │   │       └── route.ts
│   │   └── admin/                # 管理 API
│   │       └── custom/
│   │           └── route.ts
│   ├── jobs/                     # 定时任务
│   ├── modules/                  # 自定义业务逻辑
│   ├── workflows/                # 多步骤流程
│   ├── subscribers/              # 事件监听器
│   └── links/                    # 模块关系
├── .medusa/                      # 自动生成（请勿编辑）
├── medusa-config.ts              # 配置
├── package.json
└── tsconfig.json

import { defineConfig, loadEnv } from "@medusajs/framework/utils";

loadEnv(process.env.NODE_ENV || "development", process.cwd());

export default defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS || "http://localhost:8000",
      adminCors: process.env.ADMIN_CORS || "http://localhost:9000",
      authCors: process.env.AUTH_CORS || "http://localhost:9000",
    },
    redisUrl: process.env.REDIS_URL,
  },
  admin: {
    disable: false,
    backendUrl: process.env.MEDUSA_BACKEND_URL || "http://localhost:9000",
  },
  modules: [
    // 在此处添加自定义模块
  ],
});

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/medusa
REDIS_URL=redis://localhost:6379

# CORS（多个来源用逗号分隔）
STORE_CORS=http://localhost:8000
ADMIN_CORS=http://localhost:9000

# 后端 URL
MEDUSA_BACKEND_URL=http://localhost:9000

# JWT 密钥
JWT_SECRET=your-super-secret-jwt-key
COOKIE_SECRET=your-super-secret-cookie-key

自定义 API 路由

店面 API（公共）

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

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  res.json({
    message: "Hello from custom store API!",
  });
}

// 访问地址：GET /store/hello

管理 API（受保护）

// src/api/admin/analytics/route.ts
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
import { Modules } from "@medusajs/framework/utils";

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const orderService = req.scope.resolve(Modules.ORDER);

  const orders = await orderService.listOrders({
    created_at: {
      $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // 最近 30 天
    },
  });

  const totalRevenue = orders.reduce(
    (sum, order) => sum + (order.total || 0),
    0
  );

  res.json({
    orderCount: orders.length,
    totalRevenue,
  });
}

// 访问地址：GET /admin/analytics（需要认证）

// src/api/store/products/[id]/reviews/route.ts
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { id } = req.params;

  // 获取商品评论
  const reviews = await getReviewsForProduct(id);

  res.json({ reviews });
}

export async function POST(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { id } = req.params;
  const { rating, comment, customerId } = req.body;

  const review = await createReview({
    productId: id,
    rating,
    comment,
    customerId,
  });

  res.status(201).json({ review });
}

// 访问地址：
// GET  /store/products/:id/reviews
// POST /store/products/:id/reviews

// src/api/middlewares.ts
import { defineMiddlewares } from "@medusajs/framework/http";
import { authenticate } from "@medusajs/framework/http";

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/protected/*",
      middlewares: [authenticate("customer", ["session", "bearer"])],
    },
    {
      matcher: "/admin/*",
      middlewares: [authenticate("user", ["session", "bearer"])],
    },
  ],
});

模块（自定义业务逻辑）

创建自定义模块

// src/modules/reviews/index.ts
import { Module } from "@medusajs/framework/utils";
import ReviewModuleService from "./service";

export const REVIEW_MODULE = "reviewModuleService";

export default Module(REVIEW_MODULE, {
  service: ReviewModuleService,
});



// src/modules/reviews/service.ts
import { MedusaService } from "@medusajs/framework/utils";

class ReviewModuleService extends MedusaService({}) {
  async createReview(data: CreateReviewInput) {
    // 实现
  }

  async getProductReviews(productId: string) {
    // 实现
  }

  async getAverageRating(productId: string) {
    // 实现
  }
}

export default ReviewModuleService;

// medusa-config.ts
import { REVIEW_MODULE } from "./src/modules/reviews";

export default defineConfig({
  // ...
  modules: [
    {
      resolve: "./src/modules/reviews",
      options: {},
    },
  ],
});

在 API 中使用模块

// src/api/store/products/[id]/reviews/route.ts
import { REVIEW_MODULE } from "../../../modules/reviews";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { id } = req.params;
  const reviewService = req.scope.resolve(REVIEW_MODULE);

  const reviews = await reviewService.getProductReviews(id);
  const averageRating = await reviewService.getAverageRating(id);

  res.json({ reviews, averageRating });
}

// src/workflows/create-order-with-notification/index.ts
import {
  createWorkflow,
  createStep,
  StepResponse,
} from "@medusajs/framework/workflows-sdk";
import { Modules } from "@medusajs/framework/utils";

const createOrderStep = createStep(
  "create-order",
  async (input: CreateOrderInput, { container }) => {
    const orderService = container.resolve(Modules.ORDER);

    const order = await orderService.createOrders(input);

    return new StepResponse(order, order.id);
  },
  // 补偿（回滚）函数
  async (orderId, { container }) => {
    const orderService = container.resolve(Modules.ORDER);
    await orderService.deleteOrders([orderId]);
  }
);

const sendNotificationStep = createStep(
  "send-notification",
  async (order: Order, { container }) => {
    const notificationService = container.resolve("notificationService");

    await notificationService.send({
      to: order.email,
      template: "order-confirmation",
      data: { order },
    });

    return new StepResponse({ sent: true });
  }
);

export const createOrderWithNotificationWorkflow = createWorkflow(
  "create-order-with-notification",
  (input: CreateOrderInput) => {
    const order = createOrderStep(input);
    const notification = sendNotificationStep(order);

    return { order, notification };
  }
);

// 在 API 路由中
import { createOrderWithNotificationWorkflow } from "../../../workflows/create-order-with-notification";

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await createOrderWithNotificationWorkflow(req.scope).run({
    input: req.body,
  });

  res.json(result);
}

订阅者（事件监听器）

// src/subscribers/order-placed.ts
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";

export default async function orderPlacedHandler({
  event,
  container,
}: SubscriberArgs<{ id: string }>) {
  const orderId = event.data.id;

  console.log(`订单已创建：${orderId}`);

  // 发送通知、更新分析等
  const notificationService = container.resolve("notificationService");
  await notificationService.sendOrderConfirmation(orderId);
}

export const config: SubscriberConfig = {
  event: "order.placed",
};

事件	触发条件
`order.placed`	新订单创建
`order.updated`	订单修改
`order.canceled`	订单取消
`order.completed`	订单完成
`customer.created`	新客户注册
`product.created`	新商品添加
`product.updated`	商品修改
`inventory.updated`	库存变更

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

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

  console.log("正在运行库存同步...");

  await inventoryService.syncFromExternalSource();

  console.log("库存同步完成");
}

export const config = {
  name: "sync-inventory",
  schedule: "0 */6 * * *", // 每 6 小时
};

管理界面自定义

// src/admin/widgets/sales-overview.tsx
import { defineWidgetConfig } from "@medusajs/admin-sdk";
import { Container, Heading, Text } from "@medusajs/ui";

const SalesOverviewWidget = () => {
  return (
    <Container>
      <Heading level="h2">销售概览</Heading>
      <Text>您的自定义销售数据...</Text>
    </Container>
  );
};

export const config = defineWidgetConfig({
  zone: "order.list.before", // 小部件显示位置
});

export default SalesOverviewWidget;

区域	位置
`order.list.before`	订单列表前
`order.details.after`	订单详情后
`product.list.before`	商品列表前
`product.details.after`	商品详情后
`customer.list.before`	客户列表前

自定义管理路由

// src/admin/routes/analytics/page.tsx
import { defineRouteConfig } from "@medusajs/admin-sdk";
import { Container, Heading } from "@medusajs/ui";
import { ChartBar } from "@medusajs/icons";

const AnalyticsPage = () => {
  return (
    <Container>
      <Heading level="h1">分析仪表板</Heading>
      {/* 您的分析图表 */}
    </Container>
  );
};

export const config = defineRouteConfig({
  label: "分析",
  icon: ChartBar,
});

export default AnalyticsPage;

店面 API（内置）

// 前端：获取商品
const response = await fetch("http://localhost:9000/store/products");
const { products } = await response.json();

// 带过滤器
const response = await fetch(
  "http://localhost:9000/store/products?" +
  new URLSearchParams({
    category_id: "cat_123",
    limit: "20",
    offset: "0",
  })
);

// 创建购物车
const { cart } = await fetch("http://localhost:9000/store/carts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    region_id: "reg_123",
  }),
}).then(r => r.json());

// 添加商品
await fetch(`http://localhost:9000/store/carts/${cart.id}/line-items`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    variant_id: "variant_123",
    quantity: 1,
  }),
});

// 完成购物车（创建订单）
const { order } = await fetch(
  `http://localhost:9000/store/carts/${cart.id}/complete`,
  { method: "POST" }
).then(r => r.json());

// 注册
await fetch("http://localhost:9000/store/customers", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "customer@example.com",
    password: "password123",
    first_name: "John",
    last_name: "Doe",
  }),
});

// 登录
const { token } = await fetch("http://localhost:9000/store/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "customer@example.com",
    password: "password123",
  }),
}).then(r => r.json());

// 认证请求
await fetch("http://localhost:9000/store/customers/me", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

npm install @medusajs/payment-stripe



// medusa-config.ts
export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/payment-stripe",
      options: {
        apiKey: process.env.STRIPE_API_KEY,
      },
    },
  ],
});

转到设置 → 区域
添加 Stripe 作为支付提供商
为每个区域配置

# 安装 Railway CLI
npm install -g @railway/cli

# 登录并部署
railway login
railway init
railway up

# render.yaml
services:
  - type: web
    name: medusa-backend
    runtime: node
    plan: starter
    buildCommand: npm install && npm run build
    startCommand: npm run start
    envVars:
      - key: NODE_ENV
        value: production
      - key: DATABASE_URL
        fromDatabase:
          name: medusa-db
          property: connectionString
      - key: JWT_SECRET
        generateValue: true
      - key: COOKIE_SECRET
        generateValue: true

databases:
  - name: medusa-db
    plan: starter

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 9000
CMD ["npm", "run", "start"]

# 开发
npm run dev                    # 启动开发服务器

# 数据库
npx medusa db:migrate          # 运行迁移
npx medusa db:sync             # 同步模式

# 用户
npx medusa user -e email -p pass  # 创建管理员用户

# 构建
npm run build                  # 生产环境构建
npm run start                  # 启动生产服务器

PostgreSQL 数据库已配置
Redis 已配置（可选但推荐）
管理员用户已创建
CORS 来源已配置
JWT/Cookie 密钥已设置

用于业务逻辑的自定义模块
用于前端的自定义 API 路由
用于事件处理的订阅者
用于复杂操作的工作流

环境变量已配置
数据库迁移已运行
HTTPS 已启用
管理 URL 已安全保护

编辑 .medusa 文件夹 - 自动生成，将被覆盖
直接访问数据库 - 使用服务和模块
跳过复杂操作的工作流 - 工作流提供回滚功能
硬编码 URL - 使用环境变量
忽略 TypeScript 错误 - 框架依赖类型

🇺🇸English

Medusa E-Commerce Skill

Load with: base.md + typescript.md

For building headless e-commerce with Medusa - open-source, Node.js native, fully customizable.

Sources: Medusa Docs | API Reference | GitHub

Why Medusa

Feature	Benefit
Open Source	Self-host, no vendor lock-in, MIT license
Node.js Native	TypeScript, familiar stack, easy to customize
Headless	Any frontend (Next.js, Remix, mobile)
Modular	Use only what you need, extend anything
Built-in Admin	Dashboard included, customizable

Quick Start

Prerequisites

# Required
node --version  # v20+ LTS
git --version
# PostgreSQL running locally or remote

Create New Project

# Scaffold new Medusa application
npx create-medusa-app@latest my-store

# This creates:
# - Medusa backend
# - PostgreSQL database (auto-configured)
# - Admin dashboard
# - Optional: Next.js storefront

cd my-store
npm run dev

Access Points

URL	Purpose
`http://localhost:9000`	Backend API
`http://localhost:9000/app`	Admin dashboard
`http://localhost:8000`	Storefront (if installed)

Create Admin User

npx medusa user -e admin@example.com -p supersecret

Project Structure

medusa-store/
├── src/
│   ├── admin/                    # Admin UI customizations
│   │   ├── widgets/              # Dashboard widgets
│   │   └── routes/               # Custom admin pages
│   ├── api/                      # Custom API routes
│   │   ├── store/                # Public storefront APIs
│   │   │   └── custom/
│   │   │       └── route.ts
│   │   └── admin/                # Admin APIs
│   │       └── custom/
│   │           └── route.ts
│   ├── jobs/                     # Scheduled tasks
│   ├── modules/                  # Custom business logic
│   ├── workflows/                # Multi-step processes
│   ├── subscribers/              # Event listeners
│   └── links/                    # Module relationships
├── .medusa/                      # Auto-generated (don't edit)
├── medusa-config.ts              # Configuration
├── package.json
└── tsconfig.json

Configuration

medusa-config.ts

import { defineConfig, loadEnv } from "@medusajs/framework/utils";

loadEnv(process.env.NODE_ENV || "development", process.cwd());

export default defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS || "http://localhost:8000",
      adminCors: process.env.ADMIN_CORS || "http://localhost:9000",
      authCors: process.env.AUTH_CORS || "http://localhost:9000",
    },
    redisUrl: process.env.REDIS_URL,
  },
  admin: {
    disable: false,
    backendUrl: process.env.MEDUSA_BACKEND_URL || "http://localhost:9000",
  },
  modules: [
    // Add custom modules here
  ],
});

Environment Variables

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/medusa
REDIS_URL=redis://localhost:6379

# CORS (comma-separated for multiple origins)
STORE_CORS=http://localhost:8000
ADMIN_CORS=http://localhost:9000

# Backend URL
MEDUSA_BACKEND_URL=http://localhost:9000

# JWT Secrets
JWT_SECRET=your-super-secret-jwt-key
COOKIE_SECRET=your-super-secret-cookie-key

Custom API Routes

Store API (Public)

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

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  res.json({
    message: "Hello from custom store API!",
  });
}

// Accessible at: GET /store/hello

Admin API (Protected)

// src/api/admin/analytics/route.ts
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
import { Modules } from "@medusajs/framework/utils";

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const orderService = req.scope.resolve(Modules.ORDER);

  const orders = await orderService.listOrders({
    created_at: {
      $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // Last 30 days
    },
  });

  const totalRevenue = orders.reduce(
    (sum, order) => sum + (order.total || 0),
    0
  );

  res.json({
    orderCount: orders.length,
    totalRevenue,
  });
}

// Accessible at: GET /admin/analytics (requires auth)

Route with Parameters

// src/api/store/products/[id]/reviews/route.ts
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";

export async function GET(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { id } = req.params;

  // Fetch reviews for product
  const reviews = await getReviewsForProduct(id);

  res.json({ reviews });
}

export async function POST(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { id } = req.params;
  const { rating, comment, customerId } = req.body;

  const review = await createReview({
    productId: id,
    rating,
    comment,
    customerId,
  });

  res.status(201).json({ review });
}

// Accessible at:
// GET  /store/products/:id/reviews
// POST /store/products/:id/reviews

Middleware

// src/api/middlewares.ts
import { defineMiddlewares } from "@medusajs/framework/http";
import { authenticate } from "@medusajs/framework/http";

export default defineMiddlewares({
  routes: [
    {
      matcher: "/store/protected/*",
      middlewares: [authenticate("customer", ["session", "bearer"])],
    },
    {
      matcher: "/admin/*",
      middlewares: [authenticate("user", ["session", "bearer"])],
    },
  ],
});

Modules (Custom Business Logic)

Create Custom Module

// src/modules/reviews/index.ts
import { Module } from "@medusajs/framework/utils";
import ReviewModuleService from "./service";

export const REVIEW_MODULE = "reviewModuleService";

export default Module(REVIEW_MODULE, {
  service: ReviewModuleService,
});



// src/modules/reviews/service.ts
import { MedusaService } from "@medusajs/framework/utils";

class ReviewModuleService extends MedusaService({}) {
  async createReview(data: CreateReviewInput) {
    // Implementation
  }

  async getProductReviews(productId: string) {
    // Implementation
  }

  async getAverageRating(productId: string) {
    // Implementation
  }
}

export default ReviewModuleService;

Register Module

// medusa-config.ts
import { REVIEW_MODULE } from "./src/modules/reviews";

export default defineConfig({
  // ...
  modules: [
    {
      resolve: "./src/modules/reviews",
      options: {},
    },
  ],
});

Use Module in API

// src/api/store/products/[id]/reviews/route.ts
import { REVIEW_MODULE } from "../../../modules/reviews";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { id } = req.params;
  const reviewService = req.scope.resolve(REVIEW_MODULE);

  const reviews = await reviewService.getProductReviews(id);
  const averageRating = await reviewService.getAverageRating(id);

  res.json({ reviews, averageRating });
}

Workflows

Define Workflow

// src/workflows/create-order-with-notification/index.ts
import {
  createWorkflow,
  createStep,
  StepResponse,
} from "@medusajs/framework/workflows-sdk";
import { Modules } from "@medusajs/framework/utils";

const createOrderStep = createStep(
  "create-order",
  async (input: CreateOrderInput, { container }) => {
    const orderService = container.resolve(Modules.ORDER);

    const order = await orderService.createOrders(input);

    return new StepResponse(order, order.id);
  },
  // Compensation (rollback) function
  async (orderId, { container }) => {
    const orderService = container.resolve(Modules.ORDER);
    await orderService.deleteOrders([orderId]);
  }
);

const sendNotificationStep = createStep(
  "send-notification",
  async (order: Order, { container }) => {
    const notificationService = container.resolve("notificationService");

    await notificationService.send({
      to: order.email,
      template: "order-confirmation",
      data: { order },
    });

    return new StepResponse({ sent: true });
  }
);

export const createOrderWithNotificationWorkflow = createWorkflow(
  "create-order-with-notification",
  (input: CreateOrderInput) => {
    const order = createOrderStep(input);
    const notification = sendNotificationStep(order);

    return { order, notification };
  }
);

Execute Workflow

// In an API route
import { createOrderWithNotificationWorkflow } from "../../../workflows/create-order-with-notification";

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await createOrderWithNotificationWorkflow(req.scope).run({
    input: req.body,
  });

  res.json(result);
}

Subscribers (Event Listeners)

Create Subscriber

// src/subscribers/order-placed.ts
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework";

export default async function orderPlacedHandler({
  event,
  container,
}: SubscriberArgs<{ id: string }>) {
  const orderId = event.data.id;

  console.log(`Order placed: ${orderId}`);

  // Send notification, update analytics, etc.
  const notificationService = container.resolve("notificationService");
  await notificationService.sendOrderConfirmation(orderId);
}

export const config: SubscriberConfig = {
  event: "order.placed",
};

Common Events

Event	Trigger
`order.placed`	New order created
`order.updated`	Order modified
`order.canceled`	Order cancelled
`order.completed`	Order fulfilled
`customer.created`	New customer registered
`product.created`	New product added

Scheduled Jobs

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

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

  console.log("Running inventory sync...");

  await inventoryService.syncFromExternalSource();

  console.log("Inventory sync complete");
}

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

Admin UI Customization

Custom Widget

// src/admin/widgets/sales-overview.tsx
import { defineWidgetConfig } from "@medusajs/admin-sdk";
import { Container, Heading, Text } from "@medusajs/ui";

const SalesOverviewWidget = () => {
  return (
    <Container>
      <Heading level="h2">Sales Overview</Heading>
      <Text>Your custom sales data here...</Text>
    </Container>
  );
};

export const config = defineWidgetConfig({
  zone: "order.list.before", // Where to show the widget
});

export default SalesOverviewWidget;

Widget Zones

Zone	Location
`order.list.before`	Before order list
`order.details.after`	After order details
`product.list.before`	Before product list
`product.details.after`	After product details
`customer.list.before`	Before customer list

Custom Admin Route

// src/admin/routes/analytics/page.tsx
import { defineRouteConfig } from "@medusajs/admin-sdk";
import { Container, Heading } from "@medusajs/ui";
import { ChartBar } from "@medusajs/icons";

const AnalyticsPage = () => {
  return (
    <Container>
      <Heading level="h1">Analytics Dashboard</Heading>
      {/* Your analytics charts */}
    </Container>
  );
};

export const config = defineRouteConfig({
  label: "Analytics",
  icon: ChartBar,
});

export default AnalyticsPage;

Store API (Built-in)

Products

// Frontend: Fetch products
const response = await fetch("http://localhost:9000/store/products");
const { products } = await response.json();

// With filters
const response = await fetch(
  "http://localhost:9000/store/products?" +
  new URLSearchParams({
    category_id: "cat_123",
    limit: "20",
    offset: "0",
  })
);

Cart

// Create cart
const { cart } = await fetch("http://localhost:9000/store/carts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    region_id: "reg_123",
  }),
}).then(r => r.json());

// Add item
await fetch(`http://localhost:9000/store/carts/${cart.id}/line-items`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    variant_id: "variant_123",
    quantity: 1,
  }),
});

// Complete cart (create order)
const { order } = await fetch(
  `http://localhost:9000/store/carts/${cart.id}/complete`,
  { method: "POST" }
).then(r => r.json());

Customer Authentication

// Register
await fetch("http://localhost:9000/store/customers", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "customer@example.com",
    password: "password123",
    first_name: "John",
    last_name: "Doe",
  }),
});

// Login
const { token } = await fetch("http://localhost:9000/store/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "customer@example.com",
    password: "password123",
  }),
}).then(r => r.json());

// Authenticated request
await fetch("http://localhost:9000/store/customers/me", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Payment Integration

Stripe Setup

npm install @medusajs/payment-stripe



// medusa-config.ts
export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/payment-stripe",
      options: {
        apiKey: process.env.STRIPE_API_KEY,
      },
    },
  ],
});

In Admin

Go to Settings → Regions
Add Stripe as payment provider
Configure for each region

Deployment

Railway

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Render

# render.yaml
services:
  - type: web
    name: medusa-backend
    runtime: node
    plan: starter
    buildCommand: npm install && npm run build
    startCommand: npm run start
    envVars:
      - key: NODE_ENV
        value: production
      - key: DATABASE_URL
        fromDatabase:
          name: medusa-db
          property: connectionString
      - key: JWT_SECRET
        generateValue: true
      - key: COOKIE_SECRET
        generateValue: true

databases:
  - name: medusa-db
    plan: starter

Docker

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 9000
CMD ["npm", "run", "start"]

CLI Commands

# Development
npm run dev                    # Start dev server

# Database
npx medusa db:migrate          # Run migrations
npx medusa db:sync             # Sync schema

# Users
npx medusa user -e email -p pass  # Create admin user

# Build
npm run build                  # Build for production
npm run start                  # Start production server

Checklist

Setup

PostgreSQL database configured
Redis configured (optional but recommended)
Admin user created
CORS origins configured
JWT/Cookie secrets set

Customization

Custom modules for business logic
Custom API routes for frontend
Subscribers for event handling
Workflows for complex operations

Deployment

Environment variables configured
Database migrations run
HTTPS enabled
Admin URL secured

Anti-Patterns

Editing .medusa folder - Auto-generated, will be overwritten
Direct database access - Use services and modules
Skipping workflows for complex ops - Workflows provide rollback
Hardcoding URLs - Use environment variables
Ignoring TypeScript errors - Framework relies on types

Weekly Installs

Repository

alinaqi/claude-bootstrap

GitHub Stars

529

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code52

opencode51

gemini-cli49

codex46

cursor45

antigravity41

MCP服务器模式指南：构建AI助手工具与资源的最佳实践

1,000 周安装

Medusa 开源无头电商系统 - 基于 Node.js 和 TypeScript 的完全可定制电商平台

🇨🇳中文介绍

Medusa E-Commerce Skill

为什么选择 Medusa

快速开始

先决条件

相关 Skills

创建新项目

访问端点

创建管理员用户

项目结构

配置

medusa-config.ts

环境变量

自定义 API 路由

店面 API（公共）

管理 API（受保护）

带参数的路由

中间件

模块（自定义业务逻辑）

创建自定义模块

注册模块

在 API 中使用模块

工作流

定义工作流

执行工作流

订阅者（事件监听器）

创建订阅者

常见事件

定时任务

管理界面自定义

自定义小部件

小部件区域

自定义管理路由

店面 API（内置）

商品

购物车

客户认证

支付集成

Stripe 设置

在管理界面中

部署

Railway

Render

Docker

CLI 命令

检查清单

设置

自定义

部署

反模式

🇺🇸English

Medusa E-Commerce Skill

Why Medusa

Quick Start

Prerequisites

Create New Project

Access Points

Create Admin User

Project Structure

Configuration

medusa-config.ts

Environment Variables

Custom API Routes

Store API (Public)

Admin API (Protected)

Route with Parameters

Middleware

Modules (Custom Business Logic)

Create Custom Module

Register Module

Use Module in API

Workflows

Define Workflow

Execute Workflow

Subscribers (Event Listeners)

Create Subscriber

Common Events

Scheduled Jobs

Admin UI Customization