Skip to main content
Mercur is a Medusa application with a marketplace layer on top. One Node process serves three HTTP APIs, two React panels and your storefront call it through a typed client, and PostgreSQL stores all data. This page lists each piece, the package it ships in, and where your own code fits. Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers. Mercur's architecture: the admin and vendor panels, a storefront, and your services call the backend through @mercurjs/client. The backend exposes /admin, /vendor, and /store and runs marketplace modules from @mercurjs/core beside Medusa's commerce modules and your own code, over PostgreSQL, Redis, and providers.

How a request runs

Mercur keeps Medusa’s layers as they are, so Medusa’s architecture guide applies to every Mercur project. A request passes through four layers:
  1. API route: an HTTP handler under /admin, /vendor, or /store. Middleware authenticates the caller first; on /vendor it also resolves the caller’s seller before any handler runs, including handlers you add.
  2. Workflow: the handler runs a workflow for every write. Each step has a compensation function, so when a step fails, the steps before it roll back.
  3. Module: workflow steps call module services. A module owns its tables and never imports another module.
  4. Data: every module stores its tables in the same PostgreSQL database. Links record relationships between modules without foreign keys between their tables.
Reads skip the workflow layer. Handlers call Medusa’s Query, which follows links across modules in one call. Checkout uses all four layers in a single request. completeCartWithSplitOrdersWorkflow groups the cart’s items by seller, creates one order per seller under an order group, and refreshes each order’s commission lines. If a step fails, the workflow rolls back and the cart stays open. A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout. A cart with items from two sellers becomes order group #G98, split into order #100 for ACME and order #99 for GLOBEX, each with its own status, commission, and payout.

Backend packages

The backend is one Medusa server. Mercur adds a plugin and providers to it; it doesn’t replace or fork the framework.

Medusa

Medusa is the commerce engine: products, pricing, carts, orders, payments, fulfillment, promotions, and the module, workflow, and event system the rest of Mercur is built on. Anything in Medusa’s documentation works in a Mercur project.

@mercurjs/core

The marketplace plugin. It contains the marketplace modules (sellers and members, offers, commissions, payouts, product attributes, the product change pipeline, reviews, and custom fields), the workflows that connect them to commerce, the /vendor API, and the marketplace routes on /admin and /store. You register it by wrapping your Medusa config with withMercur():
medusa-config.ts
Everything else in this file is standard Medusa configuration. Source · Platform modules

@mercurjs/stripe-connector-plugin

A Stripe payment provider and a payout provider built on Stripe Connect. It creates a connected account per seller, returns onboarding links, transfers each seller’s share, and maps Stripe webhooks to payout account statuses. It also brings the payout operations core leaves out: the scheduled capture, payout, reversal, and settlement jobs, settlements and bank payouts, operator adjustments, and the Integrations → Stripe screens. Source · Stripe Connect guide

PostgreSQL and Redis

PostgreSQL is the only supported database. The starter medusa-config.ts uses Redis for the event bus, the workflow engine, locking, and the cache; Medusa also ships in-memory versions of these modules for development.

Providers

Mercur doesn’t choose your payment gateway, carrier, email service, or search engine. Each integration sits behind a provider interface, and you pick the implementation in medusa-config.ts: Swapping a provider doesn’t touch marketplace code. A payout provider implements IPayoutProvider from @mercurjs/types, which has four methods: createPayoutAccount, createOnboarding, createPayout, and getWebhookActionAndData. You register it on the payout module:
medusa-config.ts
For the Medusa provider types, see Medusa’s integrations.

Panel packages

The admin panel and the vendor panel are React 18 apps built with Vite and Medusa UI. They ship as packages that your host apps render, so you upgrade them by bumping a version.

@mercurjs/admin and @mercurjs/vendor

@mercurjs/admin is the operator panel and @mercurjs/vendor is the seller panel. A host app renders the panel and adds its stylesheet:
apps/admin/src/main.tsx
In development, the host apps run on ports 7000 and 7001. In production you can deploy them as static sites, or serve them from the backend with the admin-ui and vendor-ui modules of @mercurjs/core. Admin source · Vendor source

@mercurjs/dashboard-sdk

A Vite plugin that turns files in a host app into panel extensions. Pages come from src/routes/**/page.tsx, widgets from src/widgets/, custom-field UI from src/custom-fields/, and sidebar changes from src/_navigation.ts:
vite.config.ts
The plugin also writes extension-targets.d.ts with every zone id and model name, so a widget that targets a missing zone fails type-checking. Source · Panel extensions

@mercurjs/dashboard-shared

The UI primitives both panels are built from: forms, tabbed create flows, data tables, route modals and drawers, and query-key helpers. Use them in your own pages so they match the built-in screens. Source

Client packages

Every Mercur client, the panels included, talks to the backend over HTTP through the same typed client.

@mercurjs/client

A typed fetch wrapper. mercurjs codegen reads your backend’s API routes, including the ones you add, and writes a Routes type. The client turns property access on that type into requests:
src/lib/client.ts
.query() sends a GET, .mutate() sends a POST, and .delete() sends a DELETE. Because the panels use this client too, a backend change that breaks a caller fails at tsc instead of at runtime. Source · Add a typed API route

@mercurjs/types

Mercur’s entity and HTTP types (sellers, offers, commissions, payouts, order groups), plus re-exports of Medusa’s types. A storefront can type its responses with this package without importing the backend. Source

Tooling packages

These packages run on your machine or in CI. None of them run in production.

@mercurjs/cli

The mercurjs command. It installs and updates blocks (add, diff, search, view), generates route types (codegen), and builds plugins and registries:
Source

create-mercur-app

Creates a new project: the API, the admin host app, and the vendor host app in one Turborepo workspace.
Source

Blocks

Blocks are features that the CLI copies into your project as source code: modules, workflows, API routes, and panel extensions. Once installed, a block is your code. mercurjs diff shows what changed upstream, and you decide what to take. The official registry includes wishlist, algolia, meilisearch, vendor-chat, and requests, and you can host your own registry. Blocks · Registry

@mercurjs/docs

These docs, bundled into node_modules with an llms.txt index. Coding agents read them to get the contracts for the Mercur version you installed. Build with AI

Where your code goes

Your code lives next to Mercur’s in the same project, and nothing requires a fork. Each kind of change has one place to go: Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target. Stacked panels for Blocks, Panels, and Backend, with an Extensions table in front listing one file per zone: a workflow hook, an API route, a module, a custom field, a page, and a widget, each with its typed target.

Design decisions

These decisions explain the shape of the packages above:
  • A Mercur project is a Medusa project: Mercur adds modules, routes, and workflows to Medusa and changes none of its layers
  • Modules don’t import each other: links connect them, so you can replace Mercur’s commission module or remove a module you don’t use
  • Integrations are providers: payments, payouts, fulfillment, notifications, files, and search each sit behind an interface you implement or swap
  • Seller scoping runs before handlers: /vendor middleware resolves the seller before your code runs
  • Types come from the backend: codegen reads your routes, the client reads the generated types, and the panels use the client
  • Panels are packages, features are source: you upgrade the panels by bumping a version, and you own every block you install

Next steps

Platform modules

Data models, workflows, and events for each marketplace module.

Extend a workflow

Run your own step inside an existing flow through a hook.

Panel extensions

Add pages, widgets, custom fields, and navigation to the panels.

API conventions

Authentication, seller scoping, and the three API surfaces.