The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
CLAUDE.md -- Quick Reference for Claude Code
Required Reading
@docs/PRODUCT.md @docs/ARCHITECTURE.md @docs/UI-ARCHITECTURE.md
Skills
- Design → code (Figma): when the task is turning a Figma design into dashboard UI code — the user shares a
figma.comURL, selects a Figma node, or asks to "convert / implement / build this design / screen / mockup" inpackages/adminorpackages/vendor— load thefigma-uiskill at.claude/skills/figma-ui/SKILL.mdfirst. It reads the design from the Figma MCP (get_screenshotas the source of truth,get_metadatafor structure) and maps it onto the design-system conventions in itsreferences/(components.md,spacing.md,patterns.md) before writing JSX. Gate:bun run lint+bun run buildstay green. - Review (
/mercur-review): before opening a PR, or when asked to review / QA a change or make it "match Medusa", load.claude/skills/mercur-review/SKILL.md. It runs independent reviewer agents (Medusa patterns, dashboard patterns, technical QA, security, taste) againstreferences/, triages findings into actionable / nit / ambiguous, fixes the actionable ones, verifies them by running checks, and loops up to 3 rounds.
Project Overview
Mercur.js is open source marketplace platform repository built using Medusa.js + Typescript + React. It adds a marketplace layer on top of Medusa.js. This repository is designed for long-running coding-agent work. The goal is not to maximize raw code output. The goal is to leave the repo in a state where the next session can continue without guessing.
Build & Run
bun install # Install dependencies
bun run lint # Type-check without emitting
bun run build # Compile all packages
bun run dev # Build + launch api, admin + vendor panels
bun run test:integration:tests # Run integration tests
Project Structure
packages/core- Medusa.js plugin with core marketplace logicpackages/cli- Mercur CLIpackages/client- Type-safe fetch wrapper for the Mercur APIpackages/types- Shared TypeScript type definitionspackages/dashboard-sdk- Vite plugin and types for extending admin/vendor panelspackages/dashboard-shared- Shared dashboard primitives consumed by admin + vendorpackages/admin- Admin panel UI packagepackages/vendor- Vendor panel UI packagepackages/registry- Private workspace for the Mercur blocks registrypackages/plugins/stripe-connector- Stripe connector plugin: Stripe payment provider, Stripe Connect payout provider, admin and vendor Stripe screensapps/api- Starter Medusa server wired to@mercurjs/coreapps/admin-test- Starter admin Vite app (port 7000)apps/vendor- Starter vendor Vite app (port 7001)apps/docs- Documentation site (Mintlify)integration-tests- Cross-package Jest integration suites
Commands
- ALWAYS use
bun(never npm, yarn, or pnpm) - NEVER run
bun run test:integration:http(runs all packages). Usebun run test:integration:http -- <pattern> - Run locally only the integration specs for the endpoints you touched. For a repo-wide check, open the PR and read the integration-test jobs there instead of running broad patterns locally: the full suite takes far too long on a laptop, and CI is the source of truth
Testing a Worktree
When the user asks to test a worktree (e.g. "test this worktree", "run this worktree", "spin up "):
- Run
./scripts/dev-worktree.sh <worktree-name>in the background (e.g../scripts/dev-worktree.sh spec013-cont). - Once the apps are up, return these URLs to the user:
- API: http://localhost:9000
- Admin: http://localhost:7000
- Vendor: http://localhost:7001
Writing Code
- NEVER use
any. - Do NOT generate AI-like comments. Avoid narrating what the code does, explaining the obvious, or leaving tutorial-style commentary. Only add a comment when it captures genuinely non-obvious intent (a workaround, a gotcha, a "why" that the code can't express). Code must read as human-authored.
Testing
- Tests use Jest;
- Use
medusaIntegrationTestRunnerfrom@medusajs/test-utils. - Helpers for creating admin users, sellers, customers are in the
integration-tests/helpers - Tests are splitted by different endpoint groups:
admin,vendor,store. Example:http/product/vendor/product.spec.ts,http/product/admin/product.spec.ts.
Important Development Notes
- Bug fixes and new features MUST include tests
- For bug fixes: if the issue is reproducible in a test, write a failing test first, then implement the fix
- Ensure
bun run buildpasses before finishing - DO NOT COMMIT unless the user explicitly asks
- Conventional Commits:
feat(scope):,fix(scope):,docs:,chore:. Use!for breaking changes (e.g.feat(auth)!:) - Create branches following the convention
<type>/<feature>, where<type>matches the Conventional Commit types (feat,fix,docs,chore, etc.) and<feature>is a short kebab-case description of the work (e.g.feat/vendor-payouts,fix/order-split-rounding) - NEVER name branches or worktrees after the coding agent (
claude,claude/...,codex, etc.) or with random/auto-generated names. Branch AND worktree names MUST follow the<type>/<feature>convention above and describe the actual work - PRs target
main - NEVER mention AI coding assistants (Claude, Claude Code, Codex, Copilot, Cursor, etc.) in commit messages, PR titles, or PR descriptions. No
Co-Authored-By: Claudetrailers, no "Generated with Claude Code" footers, no "🤖" markers. Commits and PRs must read as human-authored.
Startup Workflow
Before writing code:
- Confirm the working directory with
pwd. - Read
claude-progress.mdfor the latest verified state and next step. - List
docs/specs/and pick the highest-priority unfinished spec (lowestpriorityvalue,statusnotpassing). - Review recent commits with
git log --oneline -5. - Run the end-to-end verification before starting new work.
If baseline verification is already failing, fix that first. Do not stack new spec work on top of a broken starting state.
Working Rules
- Work on one spec at a time.
- Do not mark a spec
passingjust because code was added. - Keep changes within the selected spec scope unless a blocker forces a narrow supporting fix.
- Do not silently change verification rules during implementation.
- Prefer durable repo artifacts over chat summaries.
Required Artifacts
docs/specs/SPEC-*.md: source of truth for feature/spec state (see schema below)claude-progress.md: session log and current verified statussession-handoff.md: optional compact handoff for larger sessions
docs/specs/SPEC-*.md
The spec tracker. One Markdown file per spec, each owning a single feature or
scoped product area. Specs replace the old feature_list.json and live at
docs/specs/SPEC-<NNN>-<kebab-slug>.md.
How to use it:
- Each spec is its own file under
docs/specs/. - Every spec starts with YAML frontmatter and a
# SPEC-<NNN> Titleheading. - Frontmatter fields:
status— one ofnot_started,in_progress,blocked,passing,live(uselivefor canonical product specs that are an ongoing contract rather than a one-shot feature)canonical— boolean;trueif this is the canonical owner of the areapriority— integer, lower = higher priority (optional forlivespecs)area— which part of the app (e.g."chat","import","search")created— ISO date (YYYY-MM-DD)last_updated— ISO date (YYYY-MM-DD)
- Required body sections (mirroring the old JSON schema):
- User-Visible Behavior — what the user should see when it works
- Verification — step-by-step instructions to confirm it works
- Evidence — recorded proof that verification passed (filled in by the agent)
- Notes — any extra context
Canonical product specs (e.g. SPEC-014) may use a richer body (Product Scope,
User Experience, Endpoint Contracts, etc.) instead of the simple
Verification/Evidence/Notes shape — pick the shape that fits the spec.
Status rules:
not_started— hasn't been touchedin_progress— the one spec currently being worked on (only one at a time)blocked— can't proceed due to a documented issuepassing— verification passed and evidence is recordedlive— canonical, ongoing contract (no terminal "done" state)
The agent must only have one spec in_progress at a time.
Definition Of Done
A spec is done only when all of the following are true:
- the target behavior is implemented
- the required verification actually ran
- all packages are built
- evidence is recorded in the spec file's Evidence section (and noted in
claude-progress.mdif appropriate) - the spec's frontmatter
statusis set topassingandlast_updatedis bumped - the repository remains restartable from the standard startup path
End Of Session
Before ending a session:
- Update
claude-progress.md. - Update the relevant
docs/specs/SPEC-*.mdfiles (status, evidence,last_updated). - Record any unresolved risk or blocker.
- Commit with a descriptive message once the work is in a safe state.
- Leave the repo clean enough for the next session