mercurjs/migration-guide

Migration Guide: Mercur 1.x → 2.0

Use this skill when:

• Migrating an existing Mercur 1.x project to 2.0
• Evaluating migration scope or effort
• Porting custom backend or dashboard code

Package Mapping

| 1.x | 2.0 | |-------|--------| | @mercurjs/b2c-core | @mercurjs/core — all core modules built in | | @mercurjs/commission | Built into core | | @mercurjs/algolia | Registry block: mercurjs add algolia | | @mercurjs/resend | No 2.0 equivalent — port manually | | @mercurjs/payment-stripe-connect | No 2.0 equivalent — port manually | | @mercurjs/stripe-tax-provider | No 2.0 equivalent — port manually | | @medusajs/admin-vite-plugin | @mercurjs/dashboard-sdk | | @medusajs/js-sdk | @mercurjs/client (generated typed client) |

Directory Mapping

| 1.x | 2.0 | |-------|--------| | apps/backend/src/* | packages/api/src/* | | apps/backend/src/modules/ | packages/api/src/modules/ | | apps/backend/src/workflows/ | packages/api/src/workflows/ | | apps/backend/src/api/ | packages/api/src/api/ | | apps/backend/src/subscribers/ | packages/api/src/subscribers/ | | apps/backend/src/links/ | packages/api/src/links/ | | apps/admin/src/routes/ | apps/admin/src/routes/ | | apps/vendor/src/routes/ | apps/vendor/src/routes/ |

Import Changes

| Old | New | |-----|-----| | from "@medusajs/utils" | from "@medusajs/framework/utils" | | from "@medusajs/js-sdk" | from "@mercurjs/client" | | from "@custom-types/*" | from "@mercurjs/types" | | from "@hooks/*" | from "@mercurjs/dashboard-shared" or local | | from "@components/*" | from "@mercurjs/dashboard-shared" | | from "@lib/*" | from "@mercurjs/dashboard-shared" | | from "@mercurjs/b2c-core" | from "@mercurjs/core" |

Provider Registration

Custom providers in medusa-config.ts must use ./src/ prefix:

// Wrong (will fail with "Cannot find module")
resolve: './providers/my-provider'

// Correct
resolve: './src/providers/my-provider'

Provider entry files must import from @medusajs/framework/utils, not @medusajs/utils:

import { Modules, ModuleProvider } from "@medusajs/framework/utils"

Config Migration

medusa-config.ts plugin registration changed:

// 1.x
plugins: [{ resolve: "@mercurjs/b2c-core", options: {} }]

// 2.0
plugins: [{ resolve: "@mercurjs/core", options: {} }]
// + individual module registrations in modules array

Workflow

Step 1: Analyze the old project

Scan the 1.x project the user provides:

• Read package.json — list all @mercurjs/* and @medusajs/* dependencies. Note the @mercurjs/b2c-core version to determine project version.
• If version < 1.4.0: custom admin code is inside the backend repo (not apps/admin/) — search apps/backend/ when scanning for custom dashboard pages
• Read medusa-config.ts — list plugins, modules, providers
• Scan src/modules/ — count and list custom modules
• Scan src/workflows/ — count custom workflows
• Scan src/api/ — count custom API routes
• Scan src/subscribers/ — count subscribers
• Scan src/links/ — count custom links
• Check apps/admin/src/ and apps/vendor/src/ for custom pages

Step 2: Classify

| Level | Criteria | |-------|----------| | Starter | No custom code beyond configuration | | Light custom | < 10 custom endpoints, < 5 workflows, no custom modules | | Heavy custom | Custom modules, > 10 workflows, custom admin pages, third-party integrations |

Communicate classification to user before proceeding.

Step 3: Map each element

For every custom element found, determine:

• Has 2.0 equivalent in core? → skip, already there
• Has registry block? → install with mercurjs add <block>
• Needs manual port? → queue for Step 4

Step 4: Execute migration

Port in this order:

1. Config — update medusa-config.ts (plugins, modules, providers)
2. Providers — copy to packages/api/src/providers/, fix imports
3. Modules — copy to packages/api/src/modules/, register in config
4. Workflows — copy to packages/api/src/workflows/<entity>/
5. Links — copy to packages/api/src/links/ (skip core duplicates)
6. Subscribers — copy to packages/api/src/subscribers/
7. API routes — copy to packages/api/src/api/, type both generics
8. Middleware — merge into packages/api/src/api/middlewares.ts
9. Dashboard pages — move to src/routes/ (NOT src/pages/ — dashboard SDK scans src/routes/), update imports

After each group: run bun medusa develop and verify server starts.

After API routes: run bunx @mercurjs/cli@latest codegen.

After dashboard: run bun vite build in apps/admin and apps/vendor.

Step 5: Verify

• 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 in core
• A third-party integration has no clear migration path
• Database schema conflicts arise
• The old project uses MedusaJS core modifications
• You cannot classify the project difficulty
• Server fails to start after porting and the cause is unclear

Avoid

• Do not attempt in-place upgrades of 1.x projects
• Do not install 1.x packages in a 2.0 project
• Do not create barrel index.ts files in workflows/ or steps/ (conflicts with block installation)
• Do not duplicate links that core already provides

More Info

Full migration documentation: https://docs.mercur.js/v2/migrations/overview