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
---
title: "Configuration"
description: "withMercur() options, environment variables, and provider configuration."
---
Mercur is configured through the standard Medusa config file.
`withMercur()` wraps `defineConfig()` and wires the marketplace layer in. You pass it the same shape you would pass to Medusa, plus one Mercur-specific field.
## withMercur()
```ts medusa-config.ts
import { loadEnv } from "@medusajs/framework/utils"
import { withMercur } from "@mercurjs/core"
loadEnv(process.env.NODE_ENV || "development", process.cwd())
module.exports = withMercur({
projectConfig: {
databaseUrl: process.env.DATABASE_URL,
redisUrl: process.env.REDIS_URL,
http: {
storeCors: process.env.STORE_CORS!,
adminCors: process.env.ADMIN_CORS!,
vendorCors: process.env.VENDOR_CORS!, // Mercur-specific
authCors: process.env.AUTH_CORS!,
jwtSecret: process.env.JWT_SECRET,
cookieSecret: process.env.COOKIE_SECRET,
},
},
featureFlags: {
seller_registration: true,
},
modules: [
// your modules and providers
],
})
```
The option surface is Medusa's `InputConfigWithArrayModules` extended with:
| Option | Type | Purpose |
| --- | --- | --- |
| `projectConfig.http.vendorCors` | `string` | CORS origins for the Vendor API (`/vendor/*`). The only Mercur-specific option |
### What withMercur applies
| Behavior | Detail |
| --- | --- |
| Registers the core plugin | Appends `@mercurjs/core` to `plugins` unless already present |
| Registers RBAC | Appends the `@medusajs/medusa/rbac` module and forces `featureFlags.rbac = true`, so vendor role scoping works out of the box |
| Disables the Medusa admin | `admin.disable` defaults to `true`, since Mercur ships its own dashboards |
| Adjusts core middlewares | Replaces the Medusa middlewares that Mercur overrides (e.g. collections with media) |
Everything else you pass is forwarded to `defineConfig()` unchanged, so any valid Medusa configuration stays valid here.
## Environment variables
The starter (`apps/api` and projects created with `create-mercur-app`) reads:
| Variable | Purpose | Default |
| --- | --- | --- |
| `DATABASE_URL` | Postgres connection string | Required |
| `REDIS_URL` | Redis for cache, event bus, workflow engine, locking | `redis://localhost:6379` |
| `STORE_CORS` | Storefront CORS origins | Required |
| `ADMIN_CORS` | Admin panel CORS origins | Required |
| `VENDOR_CORS` | Vendor panel CORS origins | Required |
| `AUTH_CORS` | Auth endpoint CORS origins | Required |
| `JWT_SECRET` | JWT signing secret | `supersecret` (change in production) |
| `COOKIE_SECRET` | Cookie signing secret | `supersecret` (change in production) |
| `FILE_BACKEND_URL` | Public origin baked into uploaded file URLs | `http://localhost:9000/static` |
| `MERCUR_VENDOR_URL` | Vendor dashboard base URL used in member invite links | `""`; can also be set via the seller module's `vendor_url` option |
| `MERCUR_DEV_CODEGEN` | Set to `"false"` to skip automatic type generation on dev startup | `"true"` |
| `NODE_ENV` | Environment selection | `development` |
## Dashboard modules
The admin and vendor dashboards are served by two UI modules:
```ts
modules: [
{
resolve: "@mercurjs/core/modules/admin-ui",
options: { appDir: "./admin", path: "/dashboard" },
},
{
resolve: "@mercurjs/core/modules/vendor-ui",
options: { appDir: "./vendor", path: "/seller" },
},
]
```
| Option | Type | Purpose |
| --- | --- | --- |
| `disable` | `boolean` | Skip serving this dashboard from the API process |
| `path` | `string` | Mount path (e.g. `/dashboard`, `/seller`) |
| `appDir` | `string` | Directory of the dashboard Vite app |
| `viteDevServerPort` / `viteDevServerHost` | `number` / `string` | Dev-mode proxy target (host defaults to `localhost`) |
## Stripe Connect payout provider
Register the Stripe connector plugin's payout provider on the payout module. A marketplace has exactly one payout provider; with none registered, the module loads the built-in `system` provider:
```ts
{
resolve: "@mercurjs/core/modules/payout",
options: {
providers: [
{
resolve: "@mercurjs/stripe-connector-plugin/providers/payout-stripe-connect",
id: "stripe-connect",
options: {
apiKey: process.env.STRIPE_SECRET_KEY,
webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
manualPayouts: true,
},
},
],
onboarding: {
returnUrl: `${process.env.VENDOR_URL}/stripe`,
refreshBaseUrl: process.env.BACKEND_URL,
},
},
}
```
| Option | Type | Default | Purpose |
| --- | --- | --- | --- |
| `apiKey` | `string` | Required | Stripe secret key |
| `webhookSecret` | `string` | Required | Verifies incoming Stripe webhook signatures |
| `manualPayouts` | `boolean` | `false` | Put new connected accounts on a manual payout schedule, so the plugin's settlements send bank payouts |
| `accountValidation.detailsSubmitted` | `boolean` | `true` | Require onboarding details submitted before the account is active |
| `accountValidation.chargesEnabled` | `boolean` | `true` | Require charges enabled |
| `accountValidation.payoutsEnabled` | `boolean` | `true` | Require payouts enabled |
| `accountValidation.noOutstandingRequirements` | `boolean` | `true` | Treat pending Stripe requirements as `restricted` |
| `accountValidation.requiredCapabilities` | `string[]` | `[]` | Stripe capabilities that must be `active` |
The payout module itself accepts only `onboarding` options (`returnUrl`, `refreshBaseUrl`, `prefill`, `defaultCountry`). Scheduling options (`capture`, `transfers`, `reversals`, `settlements`, `notifications`, `alerting`, `kycMonitor`) belong to the Stripe connector plugin's entry under `plugins`. See the [Stripe Connect integration](/resources/integrations/stripe-connect/configuration).
## Next steps
<CardGroup cols={2}>
<Card title="Installation" href="/learn/introduction" />
<Card title="Stripe Connect integration" href="/rc/resources/integrations/stripe-connect/configuration" />
</CardGroup>