v2.0.0

# Mercur 2.0 is here 🚀

Mercur isn't just a marketplace framework. It's a structured platform designed for both developers and AI to extend safely.

Most tools use AI to generate snippets. Mercur lets AI work at the system level — composing APIs, modifying workflows, extending UI, and evolving your marketplace architecture.

---

**Mercur 2.0 is a ground-up redesign.** Every layer has been rethought based on real feedback from development teams — covering architecture, developer experience, extensibility, and AI-native workflows.

|                | Mercur 1.x                  | Mercur 2.0                                                |
| -------------- | --------------------------- | --------------------------------------------------------- |
| Architecture   | Monolithic, tightly coupled | Modular blocks, core plugin + registry                    |
| Customization  | Fork the repo               | CLI installs blocks you own                               |
| CLI            | Basic scaffolding           | Full lifecycle: create, add, diff, search, build, codegen |
| Admin Panel    | Single app, external repo   | In-monorepo, file-based routing, dashboard SDK            |
| Vendor Panel   | Separate repo               | In-monorepo, same SDK and patterns as admin               |
| API Client     | Generic JS SDK              | Typed router shared between server and client             |
| Code Ownership | Dependency on packages      | Code copied into your project — full ownership            |
| AI Integration | None                        | Governance skills, structured blocks                      |
| Payments       | Basic Stripe                | Native marketplace payouts with Stripe Connect            |
| Documentation  | Basic guides                | Full docs with API reference                              |
| Monorepo       | None                        | Turborepo with clear workspace boundaries                 |

---

## AI-Native Development

Mercur 2.0 provides clear, predictable patterns that AI can reason about:

1. **Typed API Client** — API specifications are shared between the server and the client. AI can read types and generate correct integrations without guessing.

2. **Block Registry with CLI** — Like shadcn/ui, but for your marketplace backend. Features are modular blocks that can be added, updated, and diffed. The CLI is native for AI agents, so they can safely add, extend, and modify your system — not by guessing, but by working with structured building units.

3. **Monorepo Setup** — Everything lives in one consistent system. AI has full context across backend, admin, vendor, and shared packages.

4. **Core Workflows as Programmable Building Blocks** — Cart, orders, pricing, and vendors are exposed as structured logic that can be extended, replaced, or hooked into. AI doesn't need to rebuild flows — it can modify steps, inject logic, and adapt them to new business models.

5. **Extensible Panels** — Admin and vendor panels are extended through file-based routing and a block registry — add custom pages, replace entire sections, or swap out specific components using compound components, all wired in automatically by the dashboard SDK.

6. **Native Marketplace Payments** — Pluggable payout providers with Stripe Connect out of the box. Swap or extend providers as your marketplace evolves.

7. **Built on MedusaJS** — A structured commerce framework with modules, workflows, links, and subscribers as first-class building blocks. This gives AI context, not chaos — so it can safely modify real systems instead of guessing.

---

## New Architecture

### Block-Based System

Inspired by shadcn/ui — code is copied directly into your project for full ownership. No black-box dependencies.

**Block types:**

- **Modules** — Data models and business logic
- **Links** — Relationships between modules
- **Workflows** — Multi-step business processes
- **API Routes** — HTTP endpoints
- **Admin Extensions** — Admin dashboard customizations
- **Vendor Extensions** — Vendor portal customizations

### Core Plugin (`@mercurjs/core-plugin`)

Marketplace fundamentals that every project needs, shipped as a single plugin:

**8 Modules:** Seller, Commission, Payout, Custom Fields, Admin UI, Vendor UI, Codegen, and core MedusaJS integrations

**13+ Workflow Categories:**

- Seller management — create, invite, update sellers
- Commission — batch rules, CRUD rates, refresh order commission lines
- Payouts — create payouts, onboarding, process webhooks
- Cart — split orders by seller, seller shipping methods, seller promotions
- Orders — order groups with detail and list views
- Inventory, campaigns, price lists, promotions, shipping, stock locations

**19 Module Links:** Connecting sellers to products, orders, customers, payouts, campaigns, inventory, fulfillment, and more

**Full API Surface:**

- Admin routes: products, order-groups, commission-rates, payouts, sellers
- Vendor routes: products, categories, inventory, fulfillment, price-lists, promotions, customers, orders, payments, regions, currencies, sales-channels, campaigns, reservations
- Store routes: marketplace-aware cart and checkout

### Official Block Registry

8 pre-built blocks ready to install:

| Block                     | Description                                   |
| ------------------------- | --------------------------------------------- |
| **reviews**               | Product and seller review system with ratings |
| **product-import-export** | Bulk CSV import/export for products           |
| **team-management**       | Multi-user teams with role-based access       |
| **wishlist**              | Customer wishlist functionality               |
| **vendor-notifications**  | Event-driven notification system              |
| **algolia**               | Algolia search integration and indexing       |
| **requests**              | Request/quotation workflows                   |
| **vendor-chat**           | Real-time vendor messaging                    |

Each block includes modules, links, workflows, API routes, and UI extensions — installed with a single command.

---

## Mercur CLI (`@mercurjs/cli`)

Full project lifecycle management:

```bash
# Create a new marketplace
npx @mercurjs/cli create my-marketplace

# Initialize block configuration
mercurjs init

# Add blocks from the registry
mercurjs add reviews wishlist vendor-chat

# Search available blocks
mercurjs search -q "payment"

# View block details
mercurjs view reviews

# Compare local blocks against registry
mercurjs diff reviews

# Generate TypeScript types from API routes
mercurjs codegen

# Build a custom registry
mercurjs build
```

**Templates:**

- `basic` — Full marketplace starter with admin + vendor panels
- `registry` — Create and distribute your own block registry
- `plugin` — Build reusable MedusaJS plugins

---

## Dashboard SDK (`@mercurjs/dashboard-sdk`)

Vite plugin powering both admin and vendor panels with a unified development experience:

- **File-based routing** — `src/pages/users/[id]/page.tsx` → `/users/:id`
- **Virtual modules** — Auto-generated routes, config, components, menu items, i18n
- **Hot module reloading** — Instant feedback during development
- **Plugin extensions** — Load MedusaJS plugin UI extensions automatically

```typescript
// vite.config.ts
import { dashboardPlugin } from "@mercurjs/dashboard-sdk";

export default {
  plugins: [react(), dashboardPlugin()],
};
```

---

## Admin Panel

35+ pages covering every marketplace operation:

- **Products** — Products, variants, categories, collections, types, tags
- **Orders** — Orders, order groups, fulfillment, shipping profiles
- **Inventory** — Stock levels, locations, reservations
- **Pricing** — Price lists, promotions, campaigns
- **Sellers** — Seller management, commission rates, payouts
- **Customers** — Customers, groups
- **Regions** — Regions, tax regions, currencies
- **System** — Users, API keys, settings

## Vendor Panel

19+ pages for seller self-service:

- **Products** — Full CRUD with variants and categories
- **Orders** — Order management with payment capture/refund
- **Inventory** — Stock management with batch operations
- **Pricing** — Price lists and promotions
- **Finance** — Payout tracking and management
- **Settings** — Store configuration

### Shared UI Library (`@mercurjs/dashboard-shared`)

Components and hooks shared between admin and vendor:

- Data grids, tables, forms, modals, filtering, localization
- Custom hooks: `use-data-table`, `use-query-params`, `use-date`, `use-command-history`
- Query key factories for TanStack React Query

---

## Typed API Client (`@mercurjs/client`)

Type-safe API client generated from your routes:

```typescript
import { createClient, InferClientOutput } from "@mercurjs/client";

// Fully typed — autocomplete for every route
const products = await sdk.admin.products.query({ limit: 10 });
const product = await sdk.admin.products.$id.query({ $id: "prod_123" });
await sdk.admin.products.mutate({ title: "New Product" });
await sdk.admin.products.$id.delete({ $id: "prod_123" });

// Type inference
type Product = InferClientOutput<typeof sdk.admin.products.$id.query>;
```

---

## Stripe Connect Payouts (`@mercurjs/payout-stripe-connect`)

Native marketplace payment splitting:

- Seller payout account creation and onboarding
- Automatic order-to-payout processing
- Webhook handling for payout lifecycle events
- KYC/KYB data management
- Idempotent payment processing
- Pluggable — swap with your own payout provider

---

## AI Governance

Templates ship with `.ai/skills/` — canonical skill definitions that teach AI agents how to work with your Mercur project:

- **mercur-cli** — CLI command patterns
- **mercur-blocks** — Block discovery and installation
- **medusa-ui-conformance** — UI component conventions
- **admin-page-ui** — Admin page structure
- **admin-form-ui** — Form validation patterns
- **admin-tab-ui** — Tabbed wizard workflows
- **migration-guide** — 1.x → 2.0 migration procedures

---

## Quick Start

```bash
# 1. Create a new marketplace
bunx @mercurjs/cli create my-marketplace

# 2. Start development
cd my-marketplace
npm run dev

# 3. Access your marketplace
# Backend API:  http://localhost:9000
# Admin Panel:  http://localhost:9000/dashboard
# Vendor Panel: http://localhost:9000/seller
```

## Prerequisites

- Node.js v20+
- PostgreSQL
- Redis
- Git

---

## Tech Stack

- **Foundation:** MedusaJS v2
- **Language:** TypeScript
- **Monorepo:** Turborepo
- **Package Manager:** Bun
- **Frontend:** React 18, Vite 5, React Router 6
- **Data Fetching:** TanStack React Query v5
- **UI Components:** @medusajs/ui
- **Forms:** React Hook Form + Zod
- **Tables:** TanStack React Table v8

---

## Links

- [Documentation](https://docs.mercurjs.com)
- [Quick Start](https://docs.mercurjs.com/v2/getting-started/installation)
- [Discord](https://discord.gg/hnZBzc4NJU)
- [GitHub](https://github.com/mercurjs/mercur)
- [Roadmap](https://github.com/orgs/mercurjs/projects/2/views/1)
- [Website](https://mercurjs.com)