Migration Guide

Step 2: Read relevant migration docs

Based on classification, read from docs/migrations/mercur-1.x-to-2.0/:

Step 3: Execute migration

1. Set up fresh 2.0 project (see README.md)
2. Update medusa-config.ts (plugins, modules, providers)
3. Add registry blocks (bunx @mercurjs/cli@latest add <block>)
4. Port custom backend code in order: providers → modules → workflows → links → subscribers → API routes → middlewares
5. Port dashboard code (if applicable)
6. Verify at each checkpoint

Step 4: Verify completion

• Server starts without errors
• All custom endpoints respond
• Dashboard builds without errors
• Custom pages render in browser

Stop conditions

Stop and ask the user when:

• A custom module depends on internal APIs not exposed in @mercurjs/core
• A third-party integration (Resend, Stripe Connect, Stripe Tax) is a launch blocker and has no 2.0 equivalent
• Database schema conflicts cannot be resolved with standard migrations
• The project uses MedusaJS core modifications
• You cannot classify the project's difficulty level
• A verification checkpoint fails with an unclear root cause

Avoid

• Do not attempt in-place upgrades of 1.x projects
• Do not install 1.x packages in a 2.0 project
• Do not skip verification checkpoints
• Do not reference or depend on .migration/ or any private test directories