medusa-development

What this skill does

# Medusa.js Development

## Overview

Build and extend headless e-commerce backends with Medusa.js using custom services, subscribers (event handlers), API route extensions, custom entities with migrations, and module architecture. This skill covers Medusa v2 project setup, the dependency injection container, custom workflows, admin UI extensions, and integration patterns for connecting Medusa to storefronts, ERPs, and payment providers.

## When to Use This Skill

- When setting up a new headless e-commerce backend with Medusa
- When building custom business logic as Medusa services and workflows
- When extending the Medusa API with custom endpoints for storefront or admin use
- When implementing event-driven automation via subscribers (e.g., send email on order placed)
- When integrating external systems (ERP, CMS, fulfillment) with Medusa

## Prerequisites & Platform Notes

**This skill is written for custom/headless storefronts** (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

**Shopify**: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services.
**WooCommerce**: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress.
**Magento**: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

**You'll need**:
- Node.js 18+ (or adapt to your backend language)
- PostgreSQL (or your preferred relational database)
- Redis for caching/queues
- Stripe account and API keys
- An email sending service (SendGrid, AWS SES, or Postmark)

## Core Instructions

1. **Set up a Medusa project**

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

   # Project structure (Medusa v2)
   # my-store/
   # ├── src/
   # │   ├── api/           # Custom API routes
   # │   ├── jobs/          # Scheduled jobs
   # │   ├── links/         # Module links
   # │   ├── modules/       # Custom modules
   # │   ├── subscribers/   # Event subscribers
   # │   └── workflows/     # Custom workflows
   # ├── medusa-config.ts
   # └── package.json

   # Start the development server
   npx medusa develop
   ```

   Configure `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,
       redisUrl: process.env.REDIS_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:8000,http://localhost:9000',
       },
     },
     modules: [
       // Register custom modules here
     ],
   });
   ```

2. **Create a custom module with a service**

   ```typescript
   // src/modules/loyalty/service.ts
   import { MedusaService } from '@medusajs/framework/utils';
   import { LoyaltyPoints } from './models/loyalty-points';

   class LoyaltyModuleService extends MedusaService({
     LoyaltyPoints,
   }) {
     async awardPoints(customerId: string, points: number, reason: string) {
       return await this.createLoyaltyPointss({
         customer_id: customerId,
         points,
         reason,
         type: 'earned',
       });
     }

     async redeemPoints(customerId: string, points: number) {
       const balance = await this.getBalance(customerId);
       if (balance < points) {
         throw new Error(`Insufficient points. Balance: ${balance}, requested: ${points}`);
       }

       return await this.createLoyaltyPointss({
         customer_id: customerId,
         points: -points,
         reason: 'redeemed',
         type: 'redeemed',
       });
     }

     async getBalance(customerId: string): Promise<number> {
       const records = await this.listLoyaltyPointss({
         customer_id: customerId,
       });
       return records.reduce((sum, r) => sum + r.points, 0);
     }
   }

   export default LoyaltyModuleService;
   ```

   Define the data model:
   ```typescript
   // src/modules/loyalty/models/loyalty-points.ts
   import { model } from '@medusajs/framework/utils';

   export const LoyaltyPoints = model.define('loyalty_points', {
     id: model.id().primaryKey(),
     customer_id: model.text(),
     points: model.number(),
     reason: model.text(),
     type: model.enum(['earned', 'redeemed', 'adjusted']),
   });
   ```

   Register the module:
   ```typescript
   // src/modules/loyalty/index.ts
   import LoyaltyModuleService from './service';
   import { Module } from '@medusajs/framework/utils';

   export const LOYALTY_MODULE = 'loyaltyModuleService';

   export default Module(LOYALTY_MODULE, {
     service: LoyaltyModuleService,
   });
   ```

3. **Create event subscribers**

   ```typescript
   // src/subscribers/order-placed.ts
   import type { SubscriberArgs, SubscriberConfig } from '@medusajs/framework';
   import { Modules } from '@medusajs/framework/utils';
   import { LOYALTY_MODULE } from '../modules/loyalty';

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

     const orderService = container.resolve(Modules.ORDER);
     const loyaltyService = container.resolve(LOYALTY_MODULE);
     const logger = container.resolve('logger');

     try {
       const order = await orderService.retrieveOrder(orderId, {
         relations: ['items'],
       });

       // Award 1 point per dollar spent
       const pointsToAward = Math.floor(order.total / 100);

       if (order.customer_id && pointsToAward > 0) {
         await loyaltyService.awardPoints(
           order.customer_id,
           pointsToAward,
           `Order ${order.display_id}`
         );
         logger.info(`Awarded ${pointsToAward} loyalty points for order ${order.display_id}`);
       }
     } catch (error) {
       logger.error(`Failed to award loyalty points for order ${orderId}: ${error.message}`);
     }
   }

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

4. **Add custom API routes**

   ```typescript
   // src/api/store/loyalty/route.ts
   import type { MedusaRequest, MedusaResponse } from '@medusajs/framework/http';
   import { LOYALTY_MODULE } from '../../../modules/loyalty';

   // GET /store/loyalty — get current customer's loyalty balance
   export async function GET(req: MedusaRequest, res: MedusaResponse) {
     const customerId = req.auth_context?.actor_id;

     if (!customerId) {
       return res.status(401).json({ message: 'Authentication required' });
     }

     const loyaltyService = req.scope.resolve(LOYALTY_MODULE);
     const balance = await loyaltyService.getBalance(customerId);
     const history = await loyaltyService.listLoyaltyPointss(
       { customer_id: customerId },
       { order: { created_at: 'DESC' }, take: 20 }
     );

     res.json({ balance, history });
   }

   // POST /store/loyalty/redeem — redeem points for a discount
   export async function POST(req: MedusaRequest, res: MedusaResponse) {
     const customerId = req.auth_context?.actor_id;

     if (!customerId) {
       return res.status(401).json({ message: 'Authentication required' });
     }

     const { points } = req.body as { points: number };

     if (!points || points <= 0) {
       return res.status(400).json({ message: 'Invalid points amount' });
     }

     const loyaltyService = req.scope.resolve(LOYALTY_MODULE);

     try {
       const record = await loyaltyService.redeemPoints(customerId, points);
       const newBalance = await loyaltyService.