Skip to main content

​
Migrating from 1.x to 2.0

Start with a working 2.0 project (see Installation). This guide covers what to change when porting your 1.x code.
Using version older than 1.4.0? Your admin panel code is inside the backend repo (not a separate app). When scanning for custom admin code to port, look there instead of apps/admin/. Everything else in this guide applies identically.

​
Package Mapping

1.x Package2.0 Equivalent
@mercurjs/b2c-core@mercurjs/core-plugin
@mercurjs/commissionBuilt into core-plugin
@mercurjs/algoliaBlock: mercurjs add algolia
@mercurjs/resendNo 2.0 equivalent — port manually
@mercurjs/payment-stripe-connectNo 2.0 equivalent — port manually
@mercurjs/stripe-tax-providerNo 2.0 equivalent — port manually
@medusajs/admin-vite-plugin@mercurjs/dashboard-sdk
@medusajs/js-sdk@mercurjs/client

​
Directory Mapping

1.x2.0
apps/backend/src/*packages/api/src/*
apps/admin/src/routes/apps/admin/src/pages/
apps/vendor/src/routes/apps/vendor/src/pages/

​
What You DON’T Need to Port

Built into core-plugin today:
  • seller
  • payout
  • commission
  • split-order-payment
Moved to registry blocks:
  • reviews
  • requests
  • wishlist
  • team-management
  • algolia
  • vendor-notifications
  • vendor-chat
  • product-import-export
Install these blocks instead of porting their 1.x package code.

​
Current Migration Exceptions

These areas do not currently have full 1.x parity and should be treated as manual migration work:
  • TaxCode — no 2.0 equivalent today. Port the old logic manually if your project depends on it.
  • SecondaryCategory — no full 1.x parity today. Port manually for now if your project depends on it. Fuller support is planned for a future 2.x release.
  • Product attributes — the 1.x attribute module is not carried over 1:1. Port manually for now if your project depends on it. Fuller support is planned for a future 2.x release.

​
Porting Custom Backend Code

​
Modules

Copy to packages/api/src/modules/, register in medusa-config.ts. Update imports from @mercurjs/b2c-core to @mercurjs/core-plugin.

​
Workflows

Copy to packages/api/src/workflows/<entity>/. Don’t create barrel index.ts files — conflicts with block installation.

​
API Routes

Copy to packages/api/src/api/. Type both generics — codegen reads these: 
export const GET = async (
  req: AuthenticatedMedusaRequest<BodyType>,
  res: MedusaResponse<ResponseType>
) => { ... }
Run bunx @mercurjs/cli@canary codegen after adding routes. Copy to packages/api/src/links/ and src/subscribers/. Don’t duplicate links that core-plugin already provides (seller↔product, seller↔order, etc.).

​
Custom Providers

Copy to packages/api/src/providers/. Two required changes: 
// medusa-config.ts — must use ./src/ prefix
resolve: './src/providers/my-provider'

// provider index.ts — must import from framework/utils
import { Modules, ModuleProvider } from "@medusajs/framework/utils"

​
Porting Custom Dashboard Code

Only if you have custom pages not covered by core-admin/vendor.
Old importNew import
@medusajs/js-sdk@mercurjs/client
@custom-types/*@mercurjs/types
@hooks/*, @components/*, @lib/*Keep local, or @mercurjs/dashboard-shared if the symbol exists there
Move pages from src/routes/ to src/pages/ with export default.