medusa — Claude Code skill: what it does, how to install
This skill guides headless commerce work with Medusa, covering modules, API routes, workflows, and the admin UI. Use it when building a Medusa project.
MIT 285 installs ★ 713 updated 2026-10-13
npx skills add alinaqi/maggy --skill medusa -a claude-codeWhat medusa does
The skill is a guide for building a headless store with Medusa. It covers project scaffolding, medusa-config.ts, PostgreSQL and Redis settings, environment variables, CORS, JWT secrets, and local development with npm run dev.
It also maps the main project areas: src/api for store and admin routes, src/admin for dashboard changes, src/modules for business logic, plus workflows, jobs, subscribers, and links. Examples show protected routes, parameterized product review endpoints, middleware, and custom module registration.
Your setup needs Node.js v20+ LTS, Git, and a running PostgreSQL instance. Without that Node.js version, the project will not start.
What it helps with
- scaffold a new Medusa application
- add a public storefront API route
- protect admin and customer endpoints
- move review logic into a custom module
- configure the admin dashboard and storefront
Example prompts for the agent
- Create a new Medusa project with PostgreSQL and the admin dashboard.
- Add a protected
/admin/analyticsroute that reports order count and revenue. - Show how to place product review logic in
src/modules/reviewsand register it throughmedusa-config.ts.
How to install medusa
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill medusa -a claude-code2Manually: put the files in place
~/.claude/skills/medusa/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/medusa/
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill medusa -a codex2Manually: put the files in place
.agents/skills/medusa/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill medusa -a cursor2Manually: put the files in place
.cursor/skills/medusa/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alinaqi/maggy skills/medusa2Manually: put the files in place
.github/skills/medusa/SKILL.md1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill medusa -a gemini-cli2Platform CLI
gemini skills install https://github.com/alinaqi/maggy --path skills/medusaManually: put the files in place
.devin/skills/medusa/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill medusa -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about medusa
How do I install medusa in Claude Code?
Run npx skills add alinaqi/maggy --skill medusa -a claude-code, then use ~/.claude/skills/medusa/SKILL.md.
What does the medusa skill do?
It supports Medusa headless commerce development with guidance for project setup, API routes, middleware, custom modules, workflows, and the admin UI.
What is required to run a Medusa project?
You need Node.js v20+ LTS, Git, and a running PostgreSQL instance. The configuration also uses DATABASE_URL, REDIS_URL, CORS variables, and JWT secrets.
Source text
SKILL.md · MIT
--- name: medusa description: Medusa headless commerce - modules, workflows, API routes, admin UI when-to-use: When building with Medusa commerce platform user-invocable: false effort: medium --- # Medusa E-Commerce Skill For building headless e-commerce with Medusa - open-source, Node.js native, fully customizable. **Sources:** [Medusa Docs](https://docs.medusajs.com) | [API Reference](https://docs.medusajs.com/api/store) | [GitHub](https://github.com/medusajs/medusa) --- ## 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 ```bash # Required node --version # v20+ LTS git --version # PostgreSQL running locally or remote ``` ### Create New Project ```bash # 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 ```bash npx medusa user -e [email protected] -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 ```typescript 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 ```bash # .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) ```typescript // 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) ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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, }); ``` ```typescript // 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 ```typescript // medusa-config.ts import { REVIEW_MODULE } from "./src/modules/reviews"; export default defineConfig({ // ... modules: [ { resolve: "./src/modules/reviews", options: {}, }, ], }); ``` ### Use Module in API ```typescript // 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 ```typescript // 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 ```typescript // 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 ```typescript // 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 | | `product.updated` | Product modified | | `inventory.updated` | Stock changed | --- ## Scheduled Jobs ```typescript // 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 ```tsx // 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 ```tsx // 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 ```typescript // 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 ```typescript // 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 ```typescript // Register await fetch("http://localhost:9000/store/customers", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ email: "[email protected]", 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: "[email protected]", password: "password123", }), }).then(r => r.json()); // Authenticated request await fetch("http://localhost:9000/store/customers/me", { headers: { Authorization: `Bearer ${token}`, }, }); ``` --- ## Payment Integration ### Stripe Setup ```bash npm install @medusajs/payment-stripe ``` ```typescript // medusa-config.ts export default defineConfig({ modules: [ { resolve: "@medusajs/payment-stripe", options: { apiKey: process.env.STRIPE_API_KEY, }, }, ], }); ``` ### In Admin 1. Go to Settings → Regions 2. Add Stripe as payment provider 3. Configure for each region --- ## Deployment ### Railway ```bash # Install Railway CLI npm install -g @railway/cli # Login and deploy railway login railway init railway up ``` ### Render ```yaml # 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 ```dockerfile 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 ```bash # 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
© alinaqi · MIT · alinaqi/maggy