The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
chore: v2.0.0-canary.98
Jakub Sieradzki6d635d643c7e
diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex 31c95efe5..b7771091c 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -374,6 +374,13 @@"v2/developer-guide/extending-panels","v2/developer-guide/custom-fields"]+ },+ {+ "group": "Migration",+ "pages": [+ "v2/migrations/overview",+ "v2/migrations/from-1-x-to-2-0"+ ]}]},diff --git a/apps/docs/v2/getting-started/installation.mdx b/apps/docs/v2/getting-started/installation.mdxindex 564658c06..276f6614b 100644--- a/apps/docs/v2/getting-started/installation.mdx+++ b/apps/docs/v2/getting-started/installation.mdx@@ -9,17 +9,58 @@ description: "Install Mercur and set up your marketplace project."- [Node.js v20+](https://nodejs.org/en/download) (LTS version)- [Git](https://git-scm.com/downloads)-- [PostgreSQL](https://www.postgresql.org/download/) installed and running+- PostgreSQL v14+-## Create a new project+<Tip>+ The quickest way to get PostgreSQL running locally is with Docker:++ ```bash+ docker run -d --name mercur-postgres \+ -e POSTGRES_PASSWORD=postgres \+ -p 5432:5432 postgres:16+ ```-Use the Mercur CLI to scaffold a new project:+ Or on macOS with Homebrew:++ ```bash+ brew install postgresql@16 && brew services start postgresql@16+ ```+</Tip>++## Create a new project```bash-npx @mercurjs/cli@canary create my-marketplace+npx @mercurjs/cli@canary create```-The CLI will guide you through template selection and database configuration.+The CLI will prompt for a project name and template, then handle everything automatically:+- downloads the template+- installs dependencies+- creates and migrates the database+- seeds initial data+- starts the development server and opens the admin setup page in your browser++### Options++| Option | Description | Default |+|--------|-------------|---------|+| `--template <template>` | Template to use (`basic` or `plugin`) | prompted |+| `--db-connection-string <string>` | Full PostgreSQL connection string | — |+| `--db-host <host>` | PostgreSQL host | `localhost` |+| `--db-port <port>` | PostgreSQL port | `5432` |+| `--no-deps` | Skip dependency installation | — |+| `--skip-db` | Skip database setup | — |++**Examples:**++## Start the development server++After stopping the server, start it again from your project directory:++```bash+cd <your-project-name>+bun dev+```## Initialize an existing project@@ -53,20 +94,3 @@ After adding blocks that include modules:npx medusa db:generate <module1> <module2> ...npx medusa db:migrate```--## Start the development server--```bash-npx medusa develop-```--## Default credentials--If you used the CLI to create a new project with seed data:--**Vendor:**--```-email: [email protected]-password: supersecret-```diff --git a/apps/docs/v2/migrations/from-1-x-to-2-0.mdx b/apps/docs/v2/migrations/from-1-x-to-2-0.mdxnew file mode 100644index 000000000..1f12dfdab--- /dev/null+++ b/apps/docs/v2/migrations/from-1-x-to-2-0.mdx@@ -0,0 +1,114 @@+---+title: From 1.x to 2.0+description: What changed and how to port your existing Mercur 1.x code to 2.0.+---++# Migrating from 1.x to 2.0++Start with a working 2.0 project (see [Installation](/v2/getting-started/installation)). This guide covers what to change when porting your 1.x code.++<Note>+**Using version older than 1.4.0?** Your admin panel code is inside the backend repo (not a separate app). When scanning for custom admin code to port, look there instead of `apps/admin/`. Everything else in this guide applies identically.+</Note>++## Package Mapping++| 1.x Package | 2.0 Equivalent |+|-------------|----------------|+| `@mercurjs/b2c-core` | `@mercurjs/core-plugin` |+| `@mercurjs/commission` | Built into core-plugin |+| `@mercurjs/algolia` | Block: `mercurjs add algolia` |+| `@mercurjs/resend` | No 2.0 equivalent — port manually |+| `@mercurjs/payment-stripe-connect` | No 2.0 equivalent — port manually |+| `@mercurjs/stripe-tax-provider` | No 2.0 equivalent — port manually |+| `@medusajs/admin-vite-plugin` | `@mercurjs/dashboard-sdk` |+| `@medusajs/js-sdk` | `@mercurjs/client` |++## Directory Mapping++| 1.x | 2.0 |+|-----|-----|+| `apps/backend/src/*` | `packages/api/src/*` |+| `apps/admin/src/routes/` | `apps/admin/src/pages/` |+| `apps/vendor/src/routes/` | `apps/vendor/src/pages/` |++## What You DON'T Need to Port++Built into core-plugin today:++- `seller`+- `payout`+- `commission`+- `split-order-payment`++Moved to registry blocks:++- `reviews`+- `requests`+- `wishlist`+- `team-management`+- `algolia`+- `vendor-notifications`+- `vendor-chat`+- `product-import-export`++Install these blocks instead of porting their 1.x package code.++## Current Migration Exceptions++These areas do not currently have full 1.x parity and should be treated as manual migration work:++- **`TaxCode`** — no 2.0 equivalent today. Port the old logic manually if your project depends on it.+- **`SecondaryCategory`** — no full 1.x parity today. Port manually for now if your project depends on it. Fuller support is planned for a future 2.x release.+- **Product attributes** — the 1.x attribute module is not carried over 1:1. Port manually for now if your project depends on it. Fuller support is planned for a future 2.x release.++## Porting Custom Backend Code++### Modules++Copy to `packages/api/src/modules/`, register in `medusa-config.ts`. Update imports from `@mercurjs/b2c-core` to `@mercurjs/core-plugin`.++### Workflows++Copy to `packages/api/src/workflows/<entity>/`. Don't create barrel `index.ts` files — conflicts with block installation.++### API Routes++Copy to `packages/api/src/api/`. Type both generics — codegen reads these:++```typescript+export const GET = async (+ req: AuthenticatedMedusaRequest<BodyType>,+ res: MedusaResponse<ResponseType>+) => { ... }+```++Run `bunx @mercurjs/cli@canary codegen` after adding routes.++### Links and Subscribers++Copy to `packages/api/src/links/` and `src/subscribers/`. Don't duplicate links that core-plugin already provides (seller↔product, seller↔order, etc.).++### Custom Providers++Copy to `packages/api/src/providers/`. Two required changes:++```typescript+// medusa-config.ts — must use ./src/ prefix+resolve: './src/providers/my-provider'++// provider index.ts — must import from framework/utils+import { Modules, ModuleProvider } from "@medusajs/framework/utils"+```++## Porting Custom Dashboard Code++Only if you have custom pages not covered by core-admin/vendor.++| Old import | New import |+|-----------|------------|+| `@medusajs/js-sdk` | `@mercurjs/client` |+| `@custom-types/*` | `@mercurjs/types` |+| `@hooks/*`, `@components/*`, `@lib/*` | Keep local, or `@mercurjs/dashboard-shared` if the symbol exists there |++Move pages from `src/routes/` to `src/pages/` with `export default`.\ No newline at end of filediff --git a/apps/docs/v2/migrations/overview.mdx b/apps/docs/v2/migrations/overview.mdxnew file mode 100644index 000000000..2973c53c3--- /dev/null+++ b/apps/docs/v2/migrations/overview.mdx@@ -0,0 +1,57 @@+---+title: Migration Overview+description: Understand what changes between Mercur 1.x and 2.0 and how to migrate your project.+---++# Migration Overview++Mercur 2.0 replaces the monolithic plugin architecture (`@mercurjs/b2c-core`) with a block-based model (`@mercurjs/core-plugin` + 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](/v2/getting-started/installation).++<Tip>+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.+</Tip>++## What Replaced What++| 1.x | 2.0 |+|-------|--------|+| `@mercurjs/b2c-core` (monolithic) | `@mercurjs/core-plugin` — all core modules built in |+| `@mercurjs/commission` (separate) | Built into core-plugin |+| `@mercurjs/algolia`, reviews, requests | Registry 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 + Turbo | bun (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-plugin 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++<Warning>+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](/v2/migrations/from-1-x-to-2-0) for the full migration guidance and current status.+</Warning>++## Next Steps++- [Migration guide](/v2/migrations/from-1-x-to-2-0) — what changed and how to port your code\ No newline at end of filediff --git a/packages/admin/package.json b/packages/admin/package.jsonindex ed14f27ab..df3d2209f 100644--- a/packages/admin/package.json+++ b/packages/admin/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/admin",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex b1fd326f7..cc52361f4 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/cli",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/cli/src/commands/create.ts b/packages/cli/src/commands/create.tsindex 4967561fa..3547262d3 100644--- a/packages/cli/src/commands/create.ts+++ b/packages/cli/src/commands/create.ts@@ -1,4 +1,4 @@-import { exec } from "node:child_process";+import { spawn } from "node:child_process";import { Readable } from "node:stream";import { pipeline } from "node:stream/promises";import path from "path";@@ -51,6 +51,8 @@ export const create = new Command().option("--skip-db", "skip database configuration.", false).option("--skip-email", "skip email prompt.", false).option("--db-connection-string <string>", "PostgreSQL connection string.")+ .option("--db-host <host>", "PostgreSQL host.", "localhost")+ .option("--db-port <port>", "PostgreSQL port.", "5432").action(async (name, opts) => {try {validateNodeVersion();@@ -174,6 +176,8 @@ export const create = new Command()projectDir,projectName,dbConnectionString,+ dbHost: opts.dbHost,+ dbPort: parseInt(opts.dbPort, 10),spinner: dbSpinner,});@@ -228,13 +232,31 @@ export const create = new Command()? `http://localhost:9000/dashboard/invite?token=${dbResult.inviteToken}&first_run=true`: "http://localhost:9000/dashboard";- const serverProcess = exec(`${packageManager === "npm" ? "npm run" : packageManager} dev`, {+ const devCmd = packageManager === "npm" ? "npm" : packageManager;+ const devArgs = packageManager === "npm" ? ["run", "dev"] : ["dev"];++ const serverProcess = spawn(devCmd, devArgs, {cwd: projectDir,+ stdio: "inherit",env: process.env,});- serverProcess.stdout?.pipe(process.stdout);- serverProcess.stderr?.pipe(process.stderr);+ const printRestartHint = () => {+ logger.break();+ logger.log(kleur.bgGreen(kleur.black(" Project stopped. To start again: ")));+ logger.log(successMessage(projectDir, packageManager));+ logger.log(feedbackOutro());+ logger.break();+ };++ // Ctrl+C sends SIGINT to the whole process group (parent + child).+ // Suppress Node's default exit so we can wait for the child to close first.+ process.on("SIGINT", () => {});++ serverProcess.on("close", () => {+ printRestartHint();+ process.exit(0);+ });waitOn({resources: ["http://localhost:9000/health"],@@ -356,8 +378,7 @@ ${header("Launch Application:")}${header("Documentation:")}- - ${createTerminalLink("Getting Started", "https://mercurjs.com/docs/getting-started")}- - ${createTerminalLink("Configuration", "https://mercurjs.com/docs/configuration")}+ - ${createTerminalLink("Getting Started", "https://docs.mercurjs.com/v2/welcome")}`;}diff --git a/packages/cli/src/utils/create-db.ts b/packages/cli/src/utils/create-db.tsindex 10d048d5c..a0f6a4075 100644--- a/packages/cli/src/utils/create-db.ts+++ b/packages/cli/src/utils/create-db.ts@@ -8,8 +8,8 @@ import path from "path";import pg from "pg";import prompts from "prompts";-const DEFAULT_DB_HOST = "localhost";-const DEFAULT_DB_PORT = 5432;+const dbHost = "localhost";+const dbPort = 5432;const API_DIR = "packages/api";const ADMIN_EMAIL = "[email protected]";@@ -30,12 +30,16 @@ export async function setupDatabase(args: {projectDir: string;projectName: string;dbConnectionString?: string;+ dbHost?: string;+ dbPort?: number;spinner?: Ora;}): Promise<SetupDatabaseResult> {const dbName = args.projectName.replace(/[^a-zA-Z0-9]/g, "-");const { client, dbConnectionString } = await getDbClient({dbConnectionString: args.dbConnectionString,+ dbHost: args.dbHost ?? dbHost,+ dbPort: args.dbPort ?? dbPort,dbName,spinner: args.spinner,});@@ -122,10 +126,14 @@ interface DbClientResult {async function getDbClient({dbConnectionString,+ dbHost,+ dbPort,dbName,spinner: spinnerRef,}: {dbConnectionString?: string;+ dbHost: string;+ dbPort: number;dbName: string;spinner?: Ora;}): Promise<DbClientResult> {@@ -142,80 +150,107 @@ async function getDbClient({}}- let postgresUsername = "postgres";- let postgresPassword = "";+ // Step 1: silent default attempt (postgres / no password)+ if (spinnerRef) {+ spinnerRef.text = `Trying default connection (postgres@${dbHost}:${dbPort})...`;+ }try {const client = new pg.Client({- user: postgresUsername,- password: postgresPassword,- host: DEFAULT_DB_HOST,- port: DEFAULT_DB_PORT,+ user: "postgres",+ password: "",+ host: dbHost,+ port: dbPort,database: "postgres",});await client.connect();return {client,dbConnectionString: formatConnectionString({- user: postgresUsername,- password: postgresPassword,- host: DEFAULT_DB_HOST,- port: DEFAULT_DB_PORT,+ user: "postgres",+ password: "",+ host: dbHost,+ port: dbPort,db: dbName,}),};} catch {- spinnerRef?.stop();+ // Default connection failed — ask the user for credentials+ }++ spinnerRef?.stop();++ logger.break();+ logger.log(`PostgreSQL is required. Make sure it is installed and running on ${dbHost}:${dbPort}.`);+ logger.break();++ // Step 2: prompt with up to 3 retry attempts+ const MAX_ATTEMPTS = 3;++ for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {+ const attemptSuffix = attempt > 1 ? ` (attempt ${attempt}/${MAX_ATTEMPTS})` : "";const answers = await prompts([{type: "text",name: "postgresUsername",- message: "Enter your Postgres username",+ message: `Enter your Postgres username${attemptSuffix}`,initial: "postgres",},{type: "password",name: "postgresPassword",- message: "Enter your Postgres password",+ message: 'Enter your Postgres password (press Enter for "postgres")',},]);+ // User cancelled (Ctrl+C)if (!answers.postgresUsername) {return { client: null, dbConnectionString: null };}- postgresUsername = answers.postgresUsername;- postgresPassword = answers.postgresPassword || "";+ const username = answers.postgresUsername as string;+ const password = (answers.postgresPassword as string) || "postgres";spinnerRef?.start("Connecting to database...");try {const client = new pg.Client({- user: postgresUsername,- password: postgresPassword,- host: DEFAULT_DB_HOST,- port: DEFAULT_DB_PORT,- database: postgresUsername,+ user: username,+ password,+ host: dbHost,+ port: dbPort,+ database: "postgres",});await client.connect();+ spinnerRef?.stop();return {client,dbConnectionString: formatConnectionString({- user: postgresUsername,- password: postgresPassword,- host: DEFAULT_DB_HOST,- port: DEFAULT_DB_PORT,+ user: username,+ password,+ host: dbHost,+ port: dbPort,db: dbName,}),};} catch (err) {- logger.error(- `Couldn't connect to PostgreSQL${err instanceof Error ? `: ${err.message}` : ""}.`- );- return { client: null, dbConnectionString: null };+ spinnerRef?.stop();+ const message = err instanceof Error ? err.message : String(err);++ if (attempt < MAX_ATTEMPTS) {+ logger.warn(`Attempt ${attempt}/${MAX_ATTEMPTS} failed: ${message}`);+ } else {+ logger.error(+ `Couldn't connect to PostgreSQL: ${message}\n` ++ ` → Is PostgreSQL running? Try: pg_isready -h ${dbHost} -p ${dbPort}\n` ++ ` → Check your username, password, and that the server is accessible.`+ );+ }}}++ return { client: null, dbConnectionString: null };}async function doesDbExist(@@ -232,7 +267,7 @@ function formatConnectionString({user,password,host,- port = DEFAULT_DB_PORT,+ port = dbPort,db,}: {user: string;diff --git a/packages/client/package.json b/packages/client/package.jsonindex ffd6e23e6..3cc3886c6 100644--- a/packages/client/package.json+++ b/packages/client/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/client",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/core-plugin/package.json b/packages/core-plugin/package.jsonindex 6b62e3381..d360d0a72 100644--- a/packages/core-plugin/package.json+++ b/packages/core-plugin/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/core-plugin",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/dashboard-sdk/package.json b/packages/dashboard-sdk/package.jsonindex 91591dd34..8b797ca4f 100644--- a/packages/dashboard-sdk/package.json+++ b/packages/dashboard-sdk/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/dashboard-sdk",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/dashboard-shared/package.json b/packages/dashboard-shared/package.jsonindex 0611a3671..65fdf060a 100644--- a/packages/dashboard-shared/package.json+++ b/packages/dashboard-shared/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/dashboard-shared",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/types/package.json b/packages/types/package.jsonindex 84aa645af..0ac2d0164 100644--- a/packages/types/package.json+++ b/packages/types/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/types",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/packages/vendor/package.json b/packages/vendor/package.jsonindex cca952e8b..514e40745 100644--- a/packages/vendor/package.json+++ b/packages/vendor/package.json@@ -1,6 +1,6 @@{"name": "@mercurjs/vendor",- "version": "2.0.0-canary.97",+ "version": "2.0.0-canary.98","repository": {"type": "git","url": "https://github.com/mercurjs/mercur",diff --git a/templates/basic/apps/admin/package.json b/templates/basic/apps/admin/package.jsonindex e6c951a57..20451e2b9 100644--- a/templates/basic/apps/admin/package.json+++ b/templates/basic/apps/admin/package.json@@ -11,16 +11,16 @@},"dependencies": {"@medusajs/icons": "^2.13.3",- "@mercurjs/dashboard-sdk": "2.0.0-canary.97",- "@mercurjs/dashboard-shared": "2.0.0-canary.97",- "@mercurjs/admin": "2.0.0-canary.97",+ "@mercurjs/dashboard-sdk": "2.0.0-canary.98",+ "@mercurjs/dashboard-shared": "2.0.0-canary.98",+ "@mercurjs/admin": "2.0.0-canary.98","react": "^18.0.0","react-dom": "^18.0.0","react-i18next": "13.5.0","@tanstack/react-query": "5.64.2","@medusajs/ui": "4.1.1","react-router-dom": "6.30.3",- "@mercurjs/client": "2.0.0-canary.97",+ "@mercurjs/client": "2.0.0-canary.98","@acme/api": "*","@tanstack/react-table": "8.20.5","react-hook-form": "7.49.1",diff --git a/templates/basic/apps/vendor/package.json b/templates/basic/apps/vendor/package.jsonindex 561172580..8e9eaade1 100644--- a/templates/basic/apps/vendor/package.json+++ b/templates/basic/apps/vendor/package.json@@ -11,16 +11,16 @@},"dependencies": {"@medusajs/icons": "^2.13.3",- "@mercurjs/dashboard-sdk": "2.0.0-canary.97",- "@mercurjs/dashboard-shared": "2.0.0-canary.97",- "@mercurjs/vendor": "2.0.0-canary.97",+ "@mercurjs/dashboard-sdk": "2.0.0-canary.98",+ "@mercurjs/dashboard-shared": "2.0.0-canary.98",+ "@mercurjs/vendor": "2.0.0-canary.98","react": "^18.0.0","react-dom": "^18.0.0","react-i18next": "13.5.0","@tanstack/react-query": "5.64.2","@medusajs/ui": "4.1.1","react-router-dom": "6.30.3",- "@mercurjs/client": "2.0.0-canary.97",+ "@mercurjs/client": "2.0.0-canary.98","@acme/api": "*","@tanstack/react-table": "8.20.5","react-hook-form": "7.49.1",diff --git a/templates/basic/packages/api/package.json b/templates/basic/packages/api/package.jsonindex a864a1c48..409cfe7de 100644--- a/templates/basic/packages/api/package.json+++ b/templates/basic/packages/api/package.json@@ -34,11 +34,11 @@"@medusajs/admin-shared": "^2.13.3","@medusajs/medusa": "^2.13.3","@medusajs/draft-order": "2.13.3",- "@mercurjs/core-plugin": "2.0.0-canary.97",- "@mercurjs/types": "2.0.0-canary.97",+ "@mercurjs/core-plugin": "2.0.0-canary.98",+ "@mercurjs/types": "2.0.0-canary.98","zod": "3.25.76","http-proxy-middleware": "^3.0.3",- "@mercurjs/cli": "2.0.0-canary.97"+ "@mercurjs/cli": "2.0.0-canary.98"},"devDependencies": {"@medusajs/test-utils": "^2.13.3",