@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/deployment/self-host.mdx

@@ -0,0 +1,123 @@
+---
+title: "Self-host Mercur"
+sidebarTitle: "Self-host"
+description: "Deploy a Mercur marketplace to your own infrastructure: the API, the panels, and the databases behind them."
+---
+
+This guide covers the general steps to self-host a Mercur marketplace. Mercur is a
+Medusa plugin, so deployment follows Medusa's model, with one addition: the Vendor
+panel is a separate app. Apply these steps to the hosting provider of your choice.
+
+## What you'll deploy
+
+A Mercur marketplace has several parts.
+
+- **PostgreSQL:** the primary database.
+- **Redis:** session storage, the event bus, the workflow engine, and caching.
+- **Mercur API:** a Medusa server running the Mercur plugin. You deploy it twice, one instance in server mode and one in worker mode.
+- **Admin panel:** served by the API server.
+- **Vendor panel:** a separate static app that talks to the Vendor API.
+- **Storefront (optional):** your own frontend on the Store API.
+
+Server mode handles API requests and serves the Admin panel. Worker mode runs
+background work such as scheduled jobs and subscribers. Choose a host with at
+least 2GB of RAM per instance.
+
+## 1. Configure the API for production
+
+Set three values in `medusa-config.ts` so the same build can run as either a
+server or a worker.
+
+```ts medusa-config.ts
+module.exports = defineConfig({
+  projectConfig: {
+    // ...
+    redisUrl: process.env.REDIS_URL,
+    workerMode: process.env.MEDUSA_WORKER_MODE as "shared" | "worker" | "server",
+  },
+  admin: {
+    disable: process.env.DISABLE_MEDUSA_ADMIN === "true",
+  },
+})
+```
+
+The Admin panel is served by the server instance, so you disable it on the worker
+instance. `redisUrl` moves sessions, events, and the workflow engine onto Redis.
+
+## 2. Add a predeploy script
+
+Run migrations before the app starts in production. Add a `predeploy` script to
+`package.json`.
+
+```json package.json
+{
+  "scripts": {
+    "predeploy": "medusa db:migrate"
+  }
+}
+```
+
+## 3. Use production modules
+
+The default project ships modules meant for development, such as the local file
+provider. Swap them for production-ready ones and register them alongside
+`withMercur` in `medusa-config.ts`.
+
+- **Redis cache, event bus, and workflow engine:** move caching, events, and workflow state off the local process.
+- **Redis locking provider:** coordinate work safely across instances.
+- **S3 file provider:** store uploads durably.
+- **A notification provider** such as SendGrid or Resend, for transactional email.
+
+## 4. Set environment variables
+
+Set these on each API instance.
+
+| Variable | Description |
+| --- | --- |
+| `DATABASE_URL` | PostgreSQL connection string |
+| `REDIS_URL` | Redis connection string |
+| `JWT_SECRET` | Secret for signing auth tokens |
+| `COOKIE_SECRET` | Secret for signing session cookies |
+| `MEDUSA_WORKER_MODE` | `server` on the server instance, `worker` on the worker instance |
+| `DISABLE_MEDUSA_ADMIN` | `false` on the server, `true` on the worker |
+| `STORE_CORS` / `ADMIN_CORS` / `AUTH_CORS` | Allowed origins for the storefront, panels, and auth |
+
+## 5. Deploy the API
+
+Deploy the same build as two instances.
+
+<Steps>
+  <Step title="Build the app">
+    Run `bun run build` to compile the server and the Admin panel.
+  </Step>
+  <Step title="Run migrations">
+    The `predeploy` script runs `medusa db:migrate`. Run it once before starting.
+  </Step>
+  <Step title="Start the server instance">
+    Set `MEDUSA_WORKER_MODE=server` and `DISABLE_MEDUSA_ADMIN=false`. This instance serves the API and the Admin panel.
+  </Step>
+  <Step title="Start the worker instance">
+    Set `MEDUSA_WORKER_MODE=worker` and `DISABLE_MEDUSA_ADMIN=true`. This instance runs jobs and subscribers.
+  </Step>
+</Steps>
+
+## 6. Deploy the Vendor panel
+
+The Vendor panel is a separate Vite app. Build it with the API URL configured,
+then host the static output on any static host or CDN.
+
+<Note>
+  The Admin panel ships with the API server. The Vendor panel deploys on its own,
+  the same way a storefront does.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Medusa Cloud" icon="cloud" href="/resources/deployment/medusa-cloud">
+    Deploy without managing infrastructure yourself.
+  </Card>
+  <Card title="Stripe Connect" icon="credit-card" href="/resources/integrations/stripe-connect">
+    Wire up payments and payouts for production.
+  </Card>
+</CardGroup>

package/content/resources/integrations/overview.mdx

@@ -0,0 +1,38 @@
+---
+title: "Integrations"
+sidebarTitle: "Overview"
+description: "Extend Mercur with third-party providers and installable blocks."
+---
+
+Mercur integrates with third-party providers to extend your marketplace. Payout
+providers settle seller earnings, and installable blocks add extra capabilities on
+top of the core platform.
+
+## Payout providers
+
+A payout provider settles seller earnings to their connected accounts. Stripe
+Connect ships out of the box. You can add your own provider against the same
+interface.
+
+<CardGroup cols={2}>
+  <Card title="Stripe Connect" icon="credit-card" href="/resources/integrations/stripe-connect">
+    Configure the Stripe Connect payout provider.
+  </Card>
+  <Card title="Payout module" icon="wallet" href="/platform/payout/overview">
+    Accounts, onboarding, and the transfer pipeline.
+  </Card>
+</CardGroup>
+
+## Blocks
+
+Other integrations ship as installable blocks. You add the block, own its source
+in your project, and update it explicitly.
+
+<CardGroup cols={2}>
+  <Card title="Add a Block" icon="cubes" href="/resources/tutorials/add-a-block">
+    Install a feature block into your project.
+  </Card>
+  <Card title="Build a Block" icon="hammer" href="/resources/tutorials/build-a-block">
+    Package your own feature as a distributable block.
+  </Card>
+</CardGroup>

package/content/resources/integrations/stripe-connect.mdx

@@ -1,14 +1,15 @@
 ---
-title: "Stripe Connect Integration"
-description: "Set up Stripe Connect for marketplace payments and seller payouts — from Stripe Dashboard configuration to the full end-to-end payment lifecycle."
+title: "Stripe Connect"
+sidebarTitle: "Stripe Connect"
+description: "Set up Stripe Connect for marketplace payments and seller payouts, from Stripe Dashboard configuration to the full end-to-end payment lifecycle."
 ---
 
 A Mercur marketplace needs **two** Stripe integrations working together. The first is the standard Medusa payment provider, which charges customers at checkout. The second is the Mercur payout provider, which transfers funds from the platform to sellers after orders are fulfilled.
 
-This guide covers both — setting up Stripe, configuring both providers, wiring up webhooks, and understanding how money flows from customer to seller.
+This guide covers both. It walks through setting up Stripe, configuring both providers, wiring up webhooks, and understanding how money flows from customer to seller.
 
 <Tip>
-  This page is the configuration reference. For a hands-on walkthrough that takes one seller from onboarding to a settled payout, follow the [Set up seller payouts](/rc/resources/tutorials/seller-payouts-stripe) tutorial after completing the setup below.
+  This page is the configuration reference. For how payout accounts, onboarding, and the transfer pipeline work, see the [Payout](/platform/payout/overview) module.
 </Tip>
 
 <Info>
@@ -19,7 +20,7 @@ This guide covers both — setting up Stripe, configuring both providers, wiring
 
 - A [Stripe account](https://dashboard.stripe.com) with Connect enabled
 - Stripe Secret API key and Publishable API key
-- A running Mercur project ([installation guide](/rc/learn/installation))
+- A running Mercur project ([installation guide](/learn/introduction))
 - Node.js 20+
 
 ## Architecture overview
@@ -51,8 +52,8 @@ The two integrations serve different purposes:
   <Step title="Find your API keys">
     Go to **Developers → API keys**. You'll need:
 
-    - **Secret key** — starts with `sk_test_` (test mode) or `sk_live_` (production)
-    - **Publishable key** — starts with `pk_test_` or `pk_live_`
+    - **Secret key:** starts with `sk_test_` (test mode) or `sk_live_` (production)
+    - **Publishable key:** starts with `pk_test_` or `pk_live_`
   </Step>
   <Step title="Set environment variables">
     Add the following to your `.env` file:
@@ -147,8 +148,8 @@ module.exports = defineConfig({
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `apiKey` | `string` | — | Stripe secret API key |
-| `webhookSecret` | `string` | — | Signing secret for the payout webhook endpoint |
+| `apiKey` | `string` | - | Stripe secret API key |
+| `webhookSecret` | `string` | - | Signing secret for the payout webhook endpoint |
 | `accountValidation` | `object` | See below | Controls when a connected account is considered `ACTIVE` |
 
 ### Account validation options
@@ -172,12 +173,12 @@ The payout module itself accepts timing options that control the capture and pay
 | `disabled` | `boolean` | `false` | Disable automatic capture checks and daily payout jobs |
 | `authorizationWindowMs` | `number` | `604800000` (7 days) | How long a payment authorization remains valid |
 | `sellerActionWindowMs` | `number` | `259200000` (72 hours) | How long sellers have to accept/fulfill before cancellation |
-| `captureSafetyBufferMs` | `number` | `86400000` (24 hours) | Safety margin before authorization expiry — capture happens before `authorization expiry - buffer` |
+| `captureSafetyBufferMs` | `number` | `86400000` (24 hours) | Safety margin before authorization expiry. Capture happens before `authorization expiry - buffer` |
 | `requiredFulfillmentStatus` | `string` | `"fulfilled"` | Minimum fulfillment status before an order is eligible for capture |
 
 ## Set up webhooks
 
-You need **two separate webhook endpoints** in Stripe — one for payment events, one for payout events.
+You need **two separate webhook endpoints** in Stripe: one for payment events, one for payout events.
 
 <Warning>
   These are two distinct webhook endpoints, each with its own signing secret. Do not combine them into a single endpoint.
@@ -216,19 +217,19 @@ Here's a concrete example. A customer buys items from two sellers:
 - **Shipping**: €10
 - **Cart total**: €80
 
-### Step 1 — Authorize payment
+### Step 1: Authorize payment
 
-At checkout, a single `PaymentIntent` is created for €80 with `capture_method: "manual"`. The customer authenticates once (SCA-compliant). No money moves yet — the funds are held on the customer's card.
+At checkout, a single `PaymentIntent` is created for €80 with `capture_method: "manual"`. The customer authenticates once (SCA-compliant). No money moves yet. The funds are held on the customer's card.
 
-### Step 2 — Split orders
+### Step 2: Split orders
 
-Mercur's `completeCartWithSplitOrdersWorkflow` groups items by seller and creates separate orders — one for Seller A (€40) and one for Seller B (€30), plus shipping allocation.
+Mercur's `completeCartWithSplitOrdersWorkflow` groups items by seller and creates separate orders: one for Seller A (€40) and one for Seller B (€30), plus shipping allocation.
 
-### Step 3 — Seller acceptance and fulfillment
+### Step 3: Seller acceptance and fulfillment
 
 Each seller reviews and fulfills their order through the Vendor Portal. The payout module's `sellerActionWindowMs` (default: 72 hours) defines how long sellers have to act.
 
-### Step 4 — Capture payment
+### Step 4: Capture payment
 
 Once orders meet the `requiredFulfillmentStatus` (default: `"fulfilled"`), the platform captures the authorized payment. The capture-check job runs automatically and respects the `captureSafetyBufferMs` to ensure capture happens before authorization expiry.
 
@@ -236,7 +237,7 @@ Once orders meet the `requiredFulfillmentStatus` (default: `"fulfilled"`), the p
   Card authorizations typically expire after **7 days**. The default configuration gives sellers 72 hours to fulfill, with a 24-hour safety buffer before capture. If your business requires longer seller action windows, consider whether the 7-day authorization window is sufficient.
 </Warning>
 
-### Step 5 — Commission calculation and transfers
+### Step 5: Commission calculation and transfers
 
 After capture, Mercur calculates commission for each order and creates Stripe Transfers for the net amounts:
 
@@ -247,7 +248,7 @@ Seller B net = €30 - commission
 
 Each transfer is linked to the original charge via `source_transaction` and grouped by `transfer_group` (the order ID).
 
-### Step 6 — Bank payouts
+### Step 6: Bank payouts
 
 Stripe automatically pays out connected account balances to sellers' bank accounts on the configured payout schedule. Mercur tracks payout status changes via the `account.updated` webhook.
 
@@ -263,16 +264,16 @@ PENDING → (Stripe onboarding) → ACTIVE
                                REJECTED (permanent)
 ```
 
-1. **Account creation** — Mercur calls `stripe.accounts.create({ type: "express" })`, creating a Stripe Express connected account. The payout account starts in `PENDING` status.
+1. **Account creation.** Mercur calls `stripe.accounts.create({ type: "express" })`, creating a Stripe Express connected account. The payout account starts in `PENDING` status.
 
-2. **Onboarding link** — The seller receives a Stripe-hosted onboarding URL via `stripe.accountLinks.create()`. They complete identity verification, bank account setup, and any required compliance steps directly on Stripe.
+2. **Onboarding link.** The seller receives a Stripe-hosted onboarding URL via `stripe.accountLinks.create()`. They complete identity verification, bank account setup, and any required compliance steps directly on Stripe.
 
-3. **Webhook activation** — When the seller completes onboarding, Stripe sends an `account.updated` webhook. The provider evaluates the account against the `accountValidation` options and transitions the status:
+3. **Webhook activation.** When the seller completes onboarding, Stripe sends an `account.updated` webhook. The provider evaluates the account against the `accountValidation` options and transitions the status:
    - All validation checks pass → `ACTIVE`
    - Missing requirements or disabled reason → `RESTRICTED`
    - Disabled reason starts with `rejected.` → `REJECTED`
 
-4. **Ongoing monitoring** — Stripe may send additional `account.updated` events if requirements change. The provider re-evaluates and updates the status accordingly.
+4. **Ongoing monitoring.** Stripe may send additional `account.updated` events if requirements change. The provider re-evaluates and updates the status accordingly.
 
 For more details on payout accounts, balances, and transactions, see [Payout](/rc/learn/payouts).
 
@@ -284,7 +285,7 @@ Stripe uses two distinct concepts for moving money, and it's important to unders
 |---|---|---|
 | **What it does** | Moves funds from platform balance to connected account balance | Moves funds from connected account balance to seller's bank account |
 | **Speed** | Instant ledger movement | 1–3 business days (varies by country) |
-| **Status lifecycle** | None — transfers are immediate | `pending` → `in_transit` → `paid` / `failed` |
+| **Status lifecycle** | None. Transfers are immediate | `pending` → `in_transit` → `paid` / `failed` |
 | **Who triggers it** | Mercur (via `stripe.transfers.create()`) | Stripe (on the connected account's payout schedule) |
 | **Mercur tracking** | Transfer created with status `PAID` immediately | Status tracked via webhooks |
 
@@ -294,8 +295,8 @@ When Mercur's `createPayout` method is called, the Stripe Connect provider creat
 
 Refunding a charge does **not** automatically reverse the associated transfers. These are two separate operations:
 
-1. **Refund the PaymentIntent** — Returns funds to the customer's payment method
-2. **Reverse the Transfer(s)** — Claws back funds from the connected account(s)
+1. **Refund the PaymentIntent.** Returns funds to the customer's payment method
+2. **Reverse the Transfer(s).** Claws back funds from the connected account(s)
 
 For a full refund of a multi-seller order, you would need to reverse each seller's transfer individually. For partial refunds, you need to calculate how much to reverse from each seller based on which items are being refunded.
 
@@ -343,13 +344,13 @@ Use Stripe test mode keys (`sk_test_`, `pk_test_`) during development. All conne
 
 ### Webhook forwarding with Stripe CLI
 
-Since webhooks need to reach your local machine during development, use the [Stripe CLI](https://docs.stripe.com/stripe-cli) to forward events. You need **two separate listeners** — one for each webhook endpoint:
+Since webhooks need to reach your local machine during development, use the [Stripe CLI](https://docs.stripe.com/stripe-cli) to forward events. You need **two separate listeners**, one for each webhook endpoint:
 
 ```bash
-# Terminal 1 — Payment webhooks
+# Terminal 1: Payment webhooks
 stripe listen --forward-to localhost:9000/hooks/payment/stripe_stripe
 
-# Terminal 2 — Payout webhooks
+# Terminal 2: Payout webhooks
 stripe listen --forward-to localhost:9000/hooks/payout
 ```
 
@@ -370,26 +371,26 @@ stripe listen --forward-to localhost:9000/hooks/payout
 
 <AccordionGroup>
   <Accordion title="Why do I need two webhook endpoints with two secrets?">
-    They belong to two different integrations: the payment webhook feeds Medusa's payment provider (charges, captures, refunds), while the payout webhook feeds Mercur's payout provider (connected-account status, transfer status). Each endpoint verifies its own signing secret — combining them silently breaks whichever side's signature doesn't match.
+    They belong to two different integrations: the payment webhook feeds Medusa's payment provider (charges, captures, refunds), while the payout webhook feeds Mercur's payout provider (connected-account status, transfer status). Each endpoint verifies its own signing secret. Combining them silently breaks whichever side's signature doesn't match.
   </Accordion>
   <Accordion title="Why must capture be set to false on the payment provider?">
-    The marketplace flow authorizes at checkout and captures later, after sellers fulfill. Automatic capture would take the money before the split-order pipeline (fulfillment checks, commission, payouts) has run — `capture: false` hands that timing to the payout module's capture job.
+    The marketplace flow authorizes at checkout and captures later, after sellers fulfill. Automatic capture would take the money before the split-order pipeline (fulfillment checks, commission, payouts) has run. `capture: false` hands that timing to the payout module's capture job.
   </Accordion>
-  <Accordion title="A seller finished Stripe onboarding but is still not ACTIVE — why?">
-    Check the `accountValidation` options: by default the account must have details submitted, charges and payouts enabled, and **no outstanding requirements**. Stripe often adds follow-up requirements (e.g. extra KYC) after initial onboarding — the account shows as `RESTRICTED` until they're cleared.
+  <Accordion title="A seller finished Stripe onboarding but is still not ACTIVE. Why?">
+    Check the `accountValidation` options: by default the account must have details submitted, charges and payouts enabled, and **no outstanding requirements**. Stripe often adds follow-up requirements (e.g. extra KYC) after initial onboarding. The account shows as `RESTRICTED` until they're cleared.
   </Accordion>
   <Accordion title="Who handles VAT, disputes, and chargebacks?">
-    The platform. Separate Charges and Transfers makes the platform the Merchant of Record — see [EU/EEA considerations](#eueea-considerations) for what that entails.
+    The platform. Separate Charges and Transfers makes the platform the Merchant of Record. See [EU/EEA considerations](#eueea-considerations) for what that entails.
   </Accordion>
 </AccordionGroup>
 
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card title="Set up seller payouts" href="/rc/resources/tutorials/seller-payouts-stripe">
-    Hands-on: one seller from onboarding to a settled payout.
+  <Card title="Payout" href="/platform/payout/overview">
+    Payout accounts, onboarding, and the transfer pipeline.
   </Card>
-  <Card title="Payout" href="/rc/learn/payouts">
-    The pipeline reference — statuses, jobs, and webhook events.
+  <Card title="The payout pipeline" href="/platform/payout/concepts/payout-pipeline">
+    Statuses, jobs, and webhook events.
   </Card>
 </CardGroup>

package/content/resources/tutorials/add-a-block.mdx

@@ -1,25 +1,28 @@
 ---
-title: "Add a feature with a block"
-description: "Install the reviews block end-to-end and see it live across the admin, vendor, and storefront surfaces."
+title: "How to Add a Block"
+sidebarTitle: "Add a Block"
+description: "Install the reviews block end-to-end and follow it live across the admin, vendor, and storefront surfaces."
 ---
 
-Blocks are complete features — backend module, workflows, API routes, and panel UI — installed as **source code** into your project. This tutorial installs the `reviews` block and follows it across every surface it touches.
+Install a block and see the feature running on every surface it touches.
+
+Blocks are complete features installed as **source code** into your project. A block bundles the backend module, workflows, API routes, and panel UI. This tutorial installs the `reviews` block and follows it across each surface it appears on.
 
 <Info>
-  **Blocks are copied, not installed as dependencies.** `add` writes the block's source files into your project via the aliases in `blocks.json` — you own and can edit every file afterwards. Updates are opt-in through `diff` and `add --overwrite`. When you outgrow the catalog, [build your own block](/rc/resources/tutorials/build-a-block).
+  Blocks are copied, not installed as dependencies. `add` writes the block's source files into your project through the aliases in `blocks.json`. You own and can edit every file afterwards. Updates are opt-in through `diff` and `add --overwrite`. When you outgrow the catalog, [build your own block](/rc/resources/tutorials/build-a-block).
 </Info>
 
 ## Goal
 
-Install reviews as a block and see it running everywhere it appears.
+Install reviews as a block and confirm it runs everywhere it appears.
 
 ## Install the block
 
 <Steps>
   <Step title="Discover the block">
-    Search the registry and inspect what the block ships before installing:
+    Search the registry and inspect what the block ships before you install it.
 
-    ```bash
+    ```bash Terminal
     bunx @mercurjs/cli@latest search --query reviews
     bunx @mercurjs/cli@latest view reviews
     ```
@@ -27,16 +30,18 @@ Install reviews as a block and see it running everywhere it appears.
     `view` lists the block's files by target (API, admin, vendor) and its dependencies.
   </Step>
   <Step title="Install it">
-    ```bash
+    Run `add` to copy the block into your project.
+
+    ```bash Terminal
     bunx @mercurjs/cli@latest add reviews
     ```
 
-    The CLI copies the source into the directories mapped by your `blocks.json` aliases and prints the block's post-install instructions — module registration, middlewares, migrations.
+    The CLI copies the source into the directories mapped by your `blocks.json` aliases and prints the block's post-install instructions: module registration, middlewares, and migrations.
   </Step>
   <Step title="Run migrations and codegen">
-    The block introduced a reviews module, so generate and run its migrations, then refresh the typed route map:
+    The block introduced a reviews module. Generate and run its migrations, then refresh the typed route map.
 
-    ```bash
+    ```bash Terminal
     cd packages/api
     bunx medusa db:generate reviews
     bunx medusa db:migrate
@@ -44,25 +49,27 @@ Install reviews as a block and see it running everywhere it appears.
     ```
   </Step>
   <Step title="See it live">
-    Start the project — reviews now appear in the admin panel (moderation), the vendor portal (per-seller reviews), and the Store API (customer-facing review routes).
+    Start the project. Reviews now appear in the admin panel (moderation), the vendor portal (per-seller reviews), and the Store API (customer-facing review routes).
   </Step>
 </Steps>
 
 ## Verify
 
-1. The block's files exist in your repo under the alias-mapped paths.
-2. Migrations ran cleanly and the API boots.
-3. The admin and vendor panels show their reviews pages; the store review endpoints respond.
-4. `bunx @mercurjs/cli@latest diff reviews` reports no drift from the registry.
+Check that the install landed cleanly:
+
+- **Files:** the block's files exist in your repo under the alias-mapped paths.
+- **API:** migrations ran cleanly and the API boots.
+- **Panels and store:** the admin and vendor panels show their reviews pages, and the store review endpoints respond.
+- **No drift:** `bunx @mercurjs/cli@latest diff reviews` reports no drift from the registry.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="What if I've already modified files the block wants to write?">
-    The CLI asks before overwriting existing files (or force it with `--overwrite`). If you've customized a page the block also ships, merge by hand — you're merging source, not resolving package versions.
+    The CLI asks before overwriting existing files, or you can force it with `--overwrite`. If you have customized a page the block also ships, merge by hand. You are merging source, not resolving package versions.
   </Accordion>
   <Accordion title="How do I update a block later?">
-    `bunx @mercurjs/cli@latest diff reviews` shows what changed in the registry since you installed. Take updates with `add reviews --overwrite`, re-applying any local edits afterwards.
+    `bunx @mercurjs/cli@latest diff reviews` shows what changed in the registry since you installed. Take updates with `add reviews --overwrite`, then re-apply any local edits afterwards.
   </Accordion>
 </AccordionGroup>
 

package/content/resources/tutorials/add-a-widget.mdx

@@ -1,33 +1,38 @@
 ---
-title: "Add a widget"
-description: "Inject a React component at a named zone on a built-in panel page with defineWidgetConfig — no forking."
+title: "How to Add a Widget"
+sidebarTitle: "Add a Widget"
+description: "Render your own React component in a named zone on a built-in panel page without forking it."
 ---
 
-A **widget** is a React component attached to a named zone on a built-in page. You drop one file under `src/widgets/`, and the SDK renders it at that zone while the rest of the page — its data fetching, filters, pagination — stays exactly as shipped. This is the lightest way to add UI to a page you don't own.
+A widget is a React component attached to a named zone on a built-in page. You drop one file under `src/widgets/`, and the SDK renders it at that zone while the rest of the page stays exactly as shipped, including its data fetching, filters, and pagination.
+
+This is the lightest way to add UI to a page you don't own. Reach for it first when you want to add something to an existing screen.
 
 <Info>
-  **Additive, not a replacement.** Unlike a drop-in route (which owns the whole page), a widget layers your component onto the built-in page at a documented zone. Reach for this first when you just want to *add* something to an existing screen.
+  A widget is additive, not a replacement. Unlike a drop-in route, which owns the whole page, a widget layers your component onto the built-in page at a documented zone.
 </Info>
 
 ## What you'll build
 
-A tip banner above the vendor product list, rendered from a single file — with the list itself untouched.
+A tip banner above the vendor product list, rendered from a single file, with the list itself untouched.
 
-## Register the typed targets (once)
+## Register the typed targets
 
-Widget zones are typed ids that the vendor panel generates from its own pages and ships as `@mercurjs/vendor/extension-targets`. Register them once so the ids resolve everywhere, with a single ambient reference in your app's `src`:
+Widget zones are typed ids that the vendor panel generates from its own pages and ships as `@mercurjs/vendor/extension-targets`. Register them once so the ids resolve everywhere, with a single ambient reference in your app's `src`.
 
 ```typescript apps/vendor/src/extension-targets.d.ts
 /// <reference types="@mercurjs/vendor/extension-targets" />
 ```
 
-Projects from `create-mercur-app` already ship this file. With it present, an invalid zone fails `tsc` instead of silently doing nothing.
+<Note>
+  Projects from `create-mercur-app` already ship this file. With it present, an invalid zone fails `tsc` instead of silently doing nothing.
+</Note>
 
 ## Add the widget
 
 <Steps>
   <Step title="Create the widget file">
-    Drop a file under `src/widgets/`. Export the component as the **default** and a `config` built with `defineWidgetConfig`. The `zone` names where it renders:
+    Drop a file under `src/widgets/`. Export the component as the default and a `config` built with `defineWidgetConfig`. The `zone` names where it renders.
 
     ```tsx apps/vendor/src/widgets/product-list-banner.tsx
     import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
@@ -49,52 +54,56 @@ Projects from `create-mercur-app` already ship this file. With it present, an in
     ```
   </Step>
   <Step title="Understand the zone id">
-    A zone id is `<domain>.<view>.<placement>`. The last segment is the placement:
+    A zone id reads `<domain>.<view>.<placement>`. The last segment is the placement.
 
     | Placement | Effect |
     |-----------|--------|
     | `before` | Renders before the built-in content of the zone |
     | `after` | Renders after the built-in content |
 
-    Multiple `before` / `after` widgets on the same zone stack in registration order.
+    Multiple `before` or `after` widgets on the same zone stack in registration order.
   </Step>
   <Step title="Reload the panel">
-    Start the project (`bun run dev`) and open the vendor portal. Widget files hot-reload — the banner appears above the product list, and the table below it works exactly as before.
+    Start the project and open the vendor portal. Widget files hot-reload. The banner appears above the product list, and the table below it works exactly as before.
+
+    ```bash Terminal
+    bun run dev
+    ```
   </Step>
 </Steps>
 
 ## Available zones
 
-Zones mounted today in the **vendor portal**:
+These zones are mounted today in the vendor portal.
 
 | Zone | Where it renders |
 |------|------------------|
 | `product.list.before` / `.after` | Vendor product list page |
-| `seller.setup.before` / `.after` | The store-setup / onboarding surface (dashboard home + store settings), passed the `seller` as `data` |
+| `seller.setup.before` / `.after` | The store-setup and onboarding surface (dashboard home plus store settings), passed the `seller` as `data` |
 | `login.logo.*` | The logo slot on the public login screen |
-| `login.before.*` / `login.after.*` | Around the login form (rendered before authentication) |
+| `login.before.*` / `login.after.*` | Around the login form, rendered before authentication |
 
-The full, valid set is typed as `WidgetZoneId` and generated into `@mercurjs/vendor/extension-targets` from the panel's own zone hosts — let your editor autocomplete `zone:` to see every option. A zone no page renders can't be targeted and won't type-check.
+The full, valid set is typed as `WidgetZoneId` and generated into `@mercurjs/vendor/extension-targets` from the panel's own zone hosts. Let your editor autocomplete `zone:` to see every option. A zone no page renders can't be targeted and won't type-check.
 
 ## Verify
 
 1. The tip banner renders above the product list.
-2. Search, filter, and paginate the list — all built-in behavior still works.
-3. Change the zone to `product.list.after` and reload — the banner moves below the list.
-4. Set `zone: "not.a.zone"` — `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
-5. Delete the file — the banner disappears; nothing else changed.
+2. Search, filter, and paginate the list. All built-in behavior still works.
+3. Change the zone to `product.list.after` and reload. The banner moves below the list.
+4. Set `zone: "not.a.zone"`. `tsc` (`bun run lint`) fails with a "not assignable to `WidgetZoneId`" error.
+5. Delete the file. The banner disappears, and nothing else changes.
 
 ## FAQ
 
 <AccordionGroup>
   <Accordion title="Can a widget target more than one zone?">
-    Yes — `zone` accepts an array (`zone: ["product.list.before", "login.after.before"]`), and the same component renders at each.
+    Yes. `zone` accepts an array (`zone: ["product.list.before", "login.after.before"]`), and the same component renders at each.
   </Accordion>
   <Accordion title="Can a block ship widgets?">
-    Yes. A [block](/rc/learn/blocks) can include `src/widgets/` files in its `vendor_ui` / `admin_ui` entry, and they're aggregated just like the host app's — installing the block adds the widget with no wiring.
+    Yes. A [block](/rc/learn/blocks) can include `src/widgets/` files in its `vendor_ui` or `admin_ui` entry, and they're aggregated just like the host app's. Installing the block adds the widget with no wiring.
   </Accordion>
   <Accordion title="Does the admin panel have widget zones too?">
-    The zone set is per panel and generated from each panel's pages. Today the mounted zones live in the vendor portal (`product.list.*`, `login.*`); the admin panel exposes navigation and product custom fields. Check `@mercurjs/admin/extension-targets` for its current zones.
+    The zone set is per panel and generated from each panel's pages. Today the mounted zones live in the vendor portal (`product.list.*`, `login.*`). The admin panel exposes navigation and product custom fields. Check `@mercurjs/admin/extension-targets` for its current zones.
   </Accordion>
 </AccordionGroup>