medusajs-developer

What this skill does

# MedusaJS Developer Agent Skill

An expert agent specializing in MedusaJS v2.15+ development, focusing on building scalable e-commerce solutions with custom modules, API integrations, and third-party plugins.

## Core Capabilities

### 1. Custom Module Development
- **Data Models**: Create and manage data models using MedusaJS DML
- **Module Services**: Implement service layers with automatic CRUD operations
- **Module Configuration**: Set up proper module structure and exports
- **Database Migrations**: Generate and manage database schema changes

### 2. API Route Development
- **Custom Endpoints**: Create REST API routes in `src/api/[route-name]/route.ts`
- **HTTP Methods**: Implement GET, POST, PUT, DELETE handlers
- **Request/Response Handling**: Manage MedusaRequest and MedusaResponse objects
- **Authentication**: Integrate with MedusaJS auth systems

### 3. Commerce Module Integration
- **18 Built-in Modules**: Work with API Key, Auth, Cart, Customer, Order, Payment, Product, Pricing, Promotion, Tax, and more
- **Module Links**: Create relationships between different modules
- **Custom Fields**: Extend existing modules with additional data fields
- **Module Composition**: Combine multiple modules for complex workflows

### 4. Workflow & Automation
- **Scheduled Jobs**: Create recurring tasks with cron expressions
- **Event Handling**: Implement subscribers for asynchronous operations
- **Business Logic**: Orchestrate complex commerce workflows
- **Background Processing**: Handle long-running operations efficiently

### 5. Third-Party Integrations
- **Payment Providers**: Integrate custom payment gateways
- **External APIs**: Connect with shipping, tax, and inventory services
- **Webhooks**: Handle incoming webhooks from external systems
- **Data Synchronization**: Sync data with external platforms

## Medusa v2.15+ Updates

### Auth & Security
- Medusa v2.15+ includes built-in MFA primitives for auth flows.
- Prefer module-managed TOTP, SMS, and recovery code challenges instead of rolling your own OTP storage.
- Wire MFA into the Auth module by treating it as part of sign-in, enrollment, challenge, verify, and recovery flows.

```ts
// Pseudocode: branch on auth result and ask the Auth module to challenge/verify MFA
const result = await authModule.authenticate(credentials)

if (result.mfa_required) {
  await authModule.mfa.challenge({
    user_id: result.user_id,
    method: "totp", // "sms" | "recovery_code"
  })
}
```

### Promotions
- Promotion workflows can consume context hooks for conditional application.
- Pass contextual data such as `customer_group`, `sales_channel_id`, `region`, or campaign metadata through workflows so promotion rules can evaluate it.
- Example: apply a wholesale promotion only when `context.customer_group === "wholesale"`.

### Catalog Search
- Products now support native SKU search.
- Use SKU filters in product search requests when looking up variants by merchant-facing or fulfillment-facing identifiers.
- Example: search by SKU and keyword together to narrow a catalog query.

```bash
GET /store/products?query=hoodie&sku=HD-001-BLK-M
```

### Cloud & Platform
- Use `mcloud proxy` for secure local-to-cloud tunneling when debugging Cloud environments or testing webhooks against a local app.
- Use it when a third-party service needs a public callback URL but you want to keep the backend local.

### Data Model Notes
- Float attributes are now aligned in the data model; prefer the updated attribute types when modeling custom number fields.

## Critical Migration Notes
- Medusa v2.15.2 includes the MikroORM v6.6.12 security update and fixes the v6.13.6 snapshot regression.
- If you're on v2.13.6+, upgrade before running production migrations and clean stale snapshots first:

```bash
npx medusa db:migrate --clean-snapshots
```

- Pin all `@medusajs/*` packages to the same release line during the upgrade and avoid partial version drift.

## Development Patterns

### Module Structure
```typescript
// src/modules/my-module/models/post.ts
import { model } from "@medusajs/framework/utils"

const Post = model.define("post", {
  id: model.id().primaryKey(),
  title: model.text(),
  content: model.text().nullable(),
  published: model.boolean().default(false)
})

export default Post
```

### API Route Example
```typescript
// src/api/posts/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const postService = req.scope.resolve("postService")
  const posts = await postService.listPosts()
  
  res.json({ posts })
}

export const POST = async (req: MedusaRequest, res: MedusaResponse) => {
  const postService = req.scope.resolve("postService")
  const post = await postService.createPost(req.body)
  
  res.json({ post })
}
```

### Scheduled Job Example
```typescript
// src/jobs/sync-inventory.ts
import { MedusaContainer } from "@medusajs/framework/types"

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

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

## Best Practices

### 1. Project Setup
- Use MedusaJS CLI for project initialization
- Follow TypeScript best practices
- Implement proper error handling
- Set up comprehensive testing

### 2. Module Design
- Keep modules focused on single domains
- Use clear naming conventions
- Implement proper validation
- Document module interfaces

### 3. API Design
- Follow RESTful conventions
- Use proper HTTP status codes
- Implement pagination for list endpoints
- Validate input data thoroughly

### 4. Performance Optimization
- Use database indexes appropriately
- Implement caching strategies
- Optimize database queries
- Handle large datasets efficiently

### 5. Integration Patterns
- Use environment variables for configuration
- Implement retry mechanisms for external calls
- Handle rate limiting gracefully
- Log integration activities properly

## Common Tasks

### Creating a New Module
1. Create module directory structure
2. Define data models with proper relationships
3. Implement service layer with business logic
4. Generate and run database migrations
5. Create API routes for module operations
6. Add comprehensive tests

### Setting Up Third-Party Integration
1. Install necessary dependencies
2. Configure environment variables
3. Create service for external API communication
4. Implement webhook handlers if needed
5. Add error handling and logging
6. Test integration thoroughly

### Implementing Custom Workflow
1. Identify business process steps
2. Create necessary data models
3. Implement workflow orchestration
4. Add event handlers for state changes
5. Create monitoring and alerting
6. Document workflow behavior

## Troubleshooting

### Common Issues
- **Migration Failures**: Check model definitions and database constraints
- **Service Resolution**: Verify module exports and dependency injection
- **API Errors**: Validate request/response formats and authentication
- **Performance Issues**: Analyze database queries and implement caching

### Debugging Strategies
- Use MedusaJS debugging tools
- Check application logs for errors
- Verify database schema matches models
- Test API endpoints with proper headers
- Monitor external service responses

## Code Templates

This skill includes production-ready code templates in the `templates/` directory based on official MedusaJS documentation and best practices.

### Available Templates

#### module-complete.ts
Complete custom module structure with:
- Multiple data models with various property types
- One-to-many and many-to-many relationships
- Main service with custom methods
- Additional services with dependency injection

**Use case:** Creating custom modules (Blog, Brand, Restaurant, etc.)

#### api-route-complete.ts
Complete REST API