mercurjs/migration-guide
.claude/skills/migration-guide/SKILL.md
Plan and execute migration from Mercur 1.x to 2.0. Classifies project difficulty, reads relevant migration docs, and follows stop conditions.
$ install --global
skillsauthnpx skillsauth add mercurjs/mercur migration-guideInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 16, 2026, 6:06 AM16.6s2 files scanned
SKILL.md
- name:
- migration-guide
- description:
- Plan and execute migration from Mercur 1.x to 2.0. Classifies project difficulty, reads relevant migration docs, and follows stop conditions.
- argument-hint:
- [path-to-old-project]
Migration Guide Workflow
Use this skill when:
- Planning a migration from Mercur 1.x to 2.0
- Executing migration steps for a specific project
- Evaluating migration feasibility or effort
Read first
Before any action, read:
docs/migrations/mercur-1.x-to-2.0/README.md— entry point, version check, package/directory mapping, approach
Workflow
Step 1: Classify the project
Read references/decision-tree.md in this skill directory, then:
- Inventory the source project:
- Read
package.json— note@mercurjs/b2c-coreversion to determine 1.x version - If version < 1.4.0: custom admin code is inside the backend repo (not
apps/admin/) — search there when scanning for custom dashboard pages - Count custom modules, workflows, API routes, subscribers, links
- Identify third-party integrations
- Note custom admin/vendor pages
- Read
- Classify as: starter, light-custom, or heavy-custom
- Communicate the classification and its implications to the user
Step 2: Read relevant migration docs
Based on classification, read from docs/migrations/mercur-1.x-to-2.0/:
| Document | Starter | Light Custom | Heavy Custom | |----------|---------|-------------|-------------| | README.md | Required | Required | Required | | dashboards.md | Skim | Required | Required |
Step 3: Execute migration
- Set up fresh 2.0 project (see README.md)
- Update
medusa-config.ts(plugins, modules, providers) - Add registry blocks (
bunx @mercurjs/cli@latest add <block>) - Port custom backend code in order: providers → modules → workflows → links → subscribers → API routes → middlewares
- Port dashboard code (if applicable)
- 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
Related Skills
mercurjs/migration-guide
documentation
VerifiedTrustedCommunity
Analyze a Mercur 1.x project and guide migration to 2.0. Self-contained — works without access to the mercur monorepo.
1,470SKILL.mdUpdated Apr 7, 2026
mercurjs/code-review
development
VerifiedTrustedCommunity
Review code changes for contract compliance, type safety, and regression risk. Use after completing any non-trivial implementation, before merging PRs, or when asked to review code quality across any mercur package.
1,470SKILL.mdUpdated Apr 7, 2026
mercurjs/mercur-cli
tools
VerifiedTrustedCommunity
Use Mercur CLI commands correctly inside a project created from the Mercur basic starter. Use when choosing between `create`, `init`, `add`, `search`, `view`, and `diff`.
1,452SKILL.mdUpdated Apr 7, 2026
mercurjs/mercur-blocks
tools
VerifiedTrustedCommunity
Discover, evaluate, install, and verify Mercur blocks in the basic starter using `blocks.json` aliases and CLI workflows.
1,452SKILL.mdUpdated Apr 7, 2026