Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Migration Overview

Mercur 2.0 replaces the monolithic plugin architecture (@mercurjs/b2c-core) with a block-based model (@mercurjs/core + registry blocks). This guide is about porting your existing 1.x code to a 2.0 project. For setting up a fresh 2.0 project, see Installation.
If you’re using an AI Agent/IDE (Claude Code, Cursor, or similar), your project includes a migration-guide skill that can analyze your 1.x Mercur project and walk you through the migration step by step.

​
What Replaced What

1.x2.0
@mercurjs/b2c-core (monolithic)@mercurjs/core — all core modules built in
@mercurjs/commission (separate)Built into core
@mercurjs/algolia, reviews, requestsRegistry blocks (mercurjs add ...)
@medusajs/admin-vite-plugin@mercurjs/dashboard-sdk (virtual modules)
@medusajs/js-sdk (manual hooks)@mercurjs/client (generated typed client)
Custom admin/vendor pages@mercurjs/admin / @mercurjs/vendor — complete panels out of the box
apps/backend/packages/api/
src/routes/ (admin)src/pages/ (file-based routing)
Yarn + Turbobun (recommended)

​
What Didn’t Change

  • MedusaJS v2 foundation (modules, workflows, links, subscribers, API routes)
  • Data model patterns (MikroORM, service layer)
  • Environment variables (DATABASE_URL, CORS, secrets — all the same)

​
What You Need to Migrate

Most users don’t need to migrate much. Core-plugin and the official registry blocks cover most standard marketplace functionality. Core-admin/vendor panels provide 34+ pages out of the box. You only need to port:
  • Custom modules — business-specific modules not covered by core or blocks
  • Custom workflows and routes — your own endpoints and business logic
  • Custom dashboard pages — only if you have domain-specific pages not in core-admin/vendor
Current migration exceptions:
  • TaxCode does not have a 2.0 equivalent today and requires manual migration.
  • SecondaryCategory does not yet have full 1.x parity and may require manual migration for now.
  • The 1.x product attribute system is not carried over 1:1, so product attributes may require manual migration for now.
See From 1.x to 2.0 for the full migration guidance and current status.

​
Next Steps

  • From 2.0 to 2.1 — package rename (@mercurjs/core-plugin → @mercurjs/core) and a db:migrate step
  • From 1.x to 2.0 — full guide for porting an existing 1.x project