@mercurjs/docs 2.2.0-rc.0 → 2.2.0-rc.2

package/content/resources/tutorials/store-setup-checklist.mdx

@@ -0,0 +1,214 @@
+---
+title: "Build a store-setup checklist"
+description: "Render an onboarding progress checklist on the vendor store-setup surface with a seller.setup widget — the seller is handed to you as data, no fetching required."
+---
+
+The vendor **store-setup / onboarding** surface is a widget zone (`seller.setup`)
+that renders the full `seller` object as its `data`. That makes it the perfect
+seam for an onboarding **checklist**: derive completion from the seller you're
+handed, show what's left, and link each step to the page that completes it — all
+from a single widget file, with nothing fetched and nothing forked.
+
+<Info>
+  **This is the pattern the built-in store-setup card uses.** The shipped
+  "Complete store profile" card is itself a `seller.setup` widget that reads the
+  `seller` and renders a progress list. This tutorial rebuilds it so you can
+  shape your own onboarding steps.
+</Info>
+
+## What you'll build
+
+A collapsible progress card on the store-setup surface that checks four parts of
+the seller profile (details, address, company, payment), draws a progress bar,
+and routes the vendor to the settings page for each incomplete step. When every
+step is done, the card removes itself.
+
+## Register the typed targets (once)
+
+Widget zones are typed ids the vendor panel generates from its own pages and
+ships as `@mercurjs/vendor/extension-targets`. Reference them once so `seller.setup`
+autocompletes and a wrong zone fails `tsc`:
+
+```typescript apps/vendor/src/extension-targets.d.ts
+/// <reference types="@mercurjs/vendor/extension-targets" />
+```
+
+## Build the checklist widget
+
+<Steps>
+  <Step title="Derive the steps from the seller">
+    The `data` prop is the full `SellerDTO`. Compute each step's `completed` flag
+    from it — no request needed. Give every step a `path` to the settings page
+    that finishes it:
+
+    ```tsx apps/vendor/src/widgets/store-setup-checklist.tsx
+    import "@mercurjs/vendor/extension-targets"
+    import { SellerDTO } from "@mercurjs/types"
+
+    type ProfileStep = {
+      key: string
+      label: string
+      completed: boolean
+      path: string
+    }
+
+    function getProfileSteps(seller: SellerDTO): ProfileStep[] {
+      const hasStoreDetails = !!(seller.name && seller.email && seller.description)
+      const hasAddress = !!(
+        seller.address?.address_1 &&
+        seller.address?.city &&
+        seller.address?.country_code
+      )
+      const hasCompanyDetails = !!seller.professional_details?.corporate_name
+      const hasPaymentDetails = !!(
+        seller.payment_details?.holder_name &&
+        seller.payment_details?.country_code
+      )
+
+      return [
+        { key: "store_details", label: "Add store details", completed: hasStoreDetails, path: "/settings/store/edit" },
+        { key: "address", label: "Add address", completed: hasAddress, path: "/settings/store/address" },
+        { key: "company_details", label: "Add company details", completed: hasCompanyDetails, path: "/settings/store/professional-details" },
+        { key: "payment_details", label: "Add payment details", completed: hasPaymentDetails, path: "/settings/store/payment-details" },
+      ]
+    }
+    ```
+
+  </Step>
+  <Step title="Render the collapsible progress card">
+    Use `@medusajs/ui` primitives and `@medusajs/icons` only. Draw a progress bar
+    from the completed ratio, list each step with a status icon, and navigate on
+    click. Return `null` when everything is done so the card disappears:
+
+    ```tsx apps/vendor/src/widgets/store-setup-checklist.tsx
+    import { useMemo, useState } from "react"
+    import { useNavigate } from "react-router-dom"
+    import { Container, Text, clx } from "@medusajs/ui"
+    import { CheckCircleSolid, TriangleDownMini, CircleDottedLine } from "@medusajs/icons"
+    import { Collapsible as RadixCollapsible } from "radix-ui"
+
+    const StoreSetupChecklist = ({ data: seller }: { data?: SellerDTO }) => {
+      const navigate = useNavigate()
+      const [open, setOpen] = useState(true)
+
+      const steps = useMemo(
+        () => (seller ? getProfileSteps(seller) : []),
+        [seller]
+      )
+
+      if (!seller) {
+        return null
+      }
+
+      const completedCount = steps.filter((s) => s.completed).length
+      const totalCount = steps.length
+      const progressPercent = (completedCount / totalCount) * 100
+
+      if (completedCount === totalCount) {
+        return null
+      }
+
+      return (
+        <RadixCollapsible.Root open={open} onOpenChange={setOpen}>
+          <Container className="overflow-hidden p-0">
+            <div
+              className="h-1 bg-ui-tag-green-icon transition-all duration-500"
+              style={{ width: `${progressPercent}%` }}
+            />
+            <div className="p-6">
+              <RadixCollapsible.Trigger asChild>
+                <button className="flex w-full items-center justify-between">
+                  <Text size="large" weight="plus" leading="compact">
+                    Complete store profile
+                  </Text>
+                  <TriangleDownMini
+                    className={clx(
+                      "text-ui-fg-muted transition-transform duration-200",
+                      !open && "-rotate-90"
+                    )}
+                  />
+                </button>
+              </RadixCollapsible.Trigger>
+
+              <RadixCollapsible.Content>
+                <div className="mt-4 flex flex-col gap-y-3">
+                  {steps.map((step) => (
+                    <button
+                      key={step.key}
+                      className="flex items-center gap-x-3 text-left"
+                      onClick={() => !step.completed && navigate(step.path)}
+                      disabled={step.completed}
+                    >
+                      {step.completed ? (
+                        <CheckCircleSolid className="text-ui-tag-green-icon shrink-0" />
+                      ) : (
+                        <CircleDottedLine className="text-ui-fg-muted shrink-0" />
+                      )}
+                      <Text size="small" leading="compact" className="text-ui-fg-base">
+                        {step.label}
+                      </Text>
+                    </button>
+                  ))}
+                </div>
+              </RadixCollapsible.Content>
+            </div>
+          </Container>
+        </RadixCollapsible.Root>
+      )
+    }
+    ```
+
+  </Step>
+  <Step title="Attach it to the store-setup zone">
+    Export the component as the **default** and a `config` with a `seller.setup`
+    zone. `before` renders it above the built-in card; use `after` to place it
+    below:
+
+    ```tsx apps/vendor/src/widgets/store-setup-checklist.tsx
+    import { defineWidgetConfig } from "@mercurjs/dashboard-sdk"
+
+    export const config = defineWidgetConfig({
+      zone: "seller.setup.before",
+    })
+
+    export default StoreSetupChecklist
+    ```
+
+  </Step>
+</Steps>
+
+## Where it renders
+
+`seller.setup` is hosted in two places, both passing the same `seller` as `data`:
+
+| Host                                     | When it shows                                                |
+| ---------------------------------------- | ------------------------------------------------------------ |
+| The vendor shell (above the page outlet) | On top-level routes — the dashboard "home" onboarding banner |
+| The store settings detail page           | Always, above the store status banner                        |
+
+A single widget file covers both. Multiple `seller.setup.before` / `.after`
+widgets stack in registration order, so your checklist and the built-in card can
+coexist — or hide the built-in one by rendering your own and letting theirs
+complete.
+
+<Note>
+  **No data fetching.** Because the zone hands you the resolved `seller`, the
+  widget is pure render — you never call the SDK. To *collect and persist* a new
+  onboarding value (e.g. a Tax ID) rather than just link to existing pages, see
+  [Extend the onboarding flow](/rc/resources/tutorials/extend-onboarding), which
+  carries a value through `additional_data` to a workflow hook.
+</Note>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card
+    title="Extend the onboarding flow"
+    href="/rc/resources/tutorials/extend-onboarding"
+  >
+    Collect a new value and persist it through a workflow hook.
+  </Card>
+  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
+    The full widget model and the published zone registry.
+  </Card>
+</CardGroup>

package/llms.txt

@@ -28,26 +28,39 @@ package (`node_modules/@mercurjs/docs/`).
 - [LLMs](content/resources/ai/llms.mdx) — Feed Mercur documentation directly to LLMs for accurate, context-aware assistance.
 - [MCP Server](content/resources/ai/mcp.mdx) — Connect your AI environment to Mercur documentation via Model Context Protocol.
 - [Building with AI](content/resources/ai/overview.mdx) — Mercur ships version-matched docs inside your project so AI coding agents build from accurate APIs instead of stale training data.
+- [API routes](content/resources/best-practices/api-routes.mdx) — Thin HTTP adapters — typed request/response generics, Zod validation with createFindParams, filterable fields, middlewares as filters, and queryConfig.
+- [Custom fields](content/resources/best-practices/custom-fields.mdx) — The full loop — add a custom field in core, render it in the panels with defineCustomFieldsConfig, pull linked data with the link property, and type it end-to-end.
+- [Frontend](content/resources/best-practices/frontend.mdx) — Build panel UI the right way — @medusajs/ui usage, custom-field extensions (forms, tables, read-only section fields), and new pages, with the correct imports.
+- [Module links](content/resources/best-practices/module-links.mdx) — Relate modules without coupling them — defineLink, the link-direction rule, built-in link steps, and filtering by links.
+- [Modules](content/resources/best-practices/modules.mdx) — Keep modules thin — data access and CRUD only. Naming, decorators, and what must never live in a module service.
+- [Best Practices Overview](content/resources/best-practices/overview.mdx) — How to build with Mercur — the layered architecture, the non-negotiable rules, and where each piece of logic belongs.
+- [Subscribers & jobs](content/resources/best-practices/subscribers-and-jobs.mdx) — React to events and run periodic work safely — fetch from { id }, mutate via workflows, log-don't-throw, idempotency and loop guards, cron jobs.
+- [Types & augmentation](content/resources/best-practices/types.mdx) — Type the panels against your own backend extensions — augment framework DTOs with declaration merging so every SDK endpoint carries your custom data.
+- [Workflows](content/resources/best-practices/workflows.mdx) — Where all business logic and mutations live — composition-function constraints, one-mutation-per-step with compensation, reusing built-in steps, and the query engine.
 - [Custom Fields](content/resources/customization/custom-fields.mdx) — Extend any Medusa entity with additional fields without modifying core code.
 - [Extend a workflow](content/resources/customization/extend-a-workflow.mdx) — Inject custom logic into an existing Mercur workflow through hooks — without rewriting it.
-- [Extending Panels](content/resources/customization/extending-panels.mdx) — Add pages, customize navigation, branding, and replace components in the admin and vendor panels.
+- [Extending Panels](content/resources/customization/extending-panels.mdx) — Add pages, inject widgets, customize navigation, and extend forms and tables in the admin and vendor panels.
 - [Medusa Cloud deployment](content/resources/deployment/medusa-cloud.mdx) — Deploy Mercur — backend, admin panel, and vendor panel — on Medusa Cloud.
 - [Notifications](content/resources/integrations/notifications.mdx) — Send transactional emails and marketplace notifications with Resend.
 - [Search](content/resources/integrations/search.mdx) — Mercur's provider-agnostic search module — zero-infrastructure Orama by default, swappable for Algolia, Meilisearch, or your own provider.
 - [Stripe Connect Integration](content/resources/integrations/stripe-connect.mdx) — Set up Stripe Connect for marketplace payments and seller payouts — from Stripe Dashboard configuration to the full end-to-end payment lifecycle.
 - [Add a feature with a block](content/resources/tutorials/add-a-block.mdx) — Install the reviews block end-to-end and see it live across the admin, vendor, and storefront surfaces.
+- [Add a widget](content/resources/tutorials/add-a-widget.mdx) — Inject a React component at a named zone on a built-in panel page with defineWidgetConfig — no forking.
+- [Add a button to order details](content/resources/tutorials/add-order-detail-button.mdx) — Drop a 'Copy link' button onto the vendor order detail page with a widget — no forking, no page override.
 - [Create attributes and variant axes](content/resources/tutorials/attributes-and-variant-axes.mdx) — Build the attribute catalog: a filterable attribute, a variant axis backed by a native product option, and an inline product-scoped axis.
 - [Build your own block](content/resources/tutorials/build-a-block.mdx) — Author a reusable feature as a block — backend, panel UI, and docs — build it into a registry, and install it into any Mercur project.
 - [Configure commissions](content/resources/tutorials/configure-commissions.mdx) — Set the global commission, add scoped rules for categories and sellers, and confirm the right rate lands on an order.
 - [Add a custom API route](content/resources/tutorials/custom-api-route.mdx) — Create a backend endpoint, regenerate the route map, and call it from a panel page with full type safety end to end.
 - [Add a custom panel page](content/resources/tutorials/custom-panel-page.mdx) — Add a page to the vendor portal with file-based routing — the dashboard SDK wires it in automatically.
+- [Customize navigation](content/resources/tutorials/customize-navigation.mdx) — Reorder, hide, relabel, and re-parent built-in sidebar items with a single _navigation.ts file and defineNavigationConfig.
+- [Extend forms and tables](content/resources/tutorials/extend-forms-and-tables.mdx) — Add validated fields to built-in forms, replace fields in detail sections, and add list columns with defineCustomFieldsConfig and createFormHelper.
+- [Extend the onboarding flow](content/resources/tutorials/extend-onboarding.mdx) — Add a field to the vendor store-setup surface, submit it through additional_data, and persist it durably from a workflow hook — end to end, without forking.
 - [Build your first marketplace](content/resources/tutorials/first-marketplace.mdx) — Go end-to-end: create a project, approve a seller, list a product, place a split order, and watch a payout settle.
 - [Handle product requests](content/resources/tutorials/handle-product-requests.mdx) — Walk a vendor's product submission and a follow-up edit through the operator review pipeline — confirm, decline, or send back.
 - [Import and export products via CSV](content/resources/tutorials/import-export-products.mdx) — Install the product-import-export block and give vendors CSV import and export drawers on their product list.
 - [Work with master products and offers](content/resources/tutorials/master-products-and-offers.mdx) — Two sellers compete on one catalog entry: publish a master product, create competing offers, and read per-offer prices from the Store API.
-- [Re-compose a built-in page](content/resources/tutorials/recompose-a-page.mdx) — Override a built-in panel page by dropping a route file at the same path and re-composing its compound component slots.
-- [Replace panel components](content/resources/tutorials/replace-panel-components.mdx) — Swap the sidebar, topbar actions, or store setup screen for your own components through dashboard SDK configuration.
 - [Set up seller payouts](content/resources/tutorials/seller-payouts-stripe.mdx) — Take a seller from zero to paid: Stripe Connect onboarding, an order through fulfillment, capture, and the automated payout.
+- [Build a store-setup checklist](content/resources/tutorials/store-setup-checklist.mdx) — Render an onboarding progress checklist on the vendor store-setup surface with a seller.setup widget — the seller is handed to you as data, no fetching required.
 
 ## Tools — CLI, API client, dashboard SDK
 
@@ -213,6 +226,7 @@ package (`node_modules/@mercurjs/docs/`).
 - [Search module](content/references/modules/search.mdx) — The provider-agnostic search module, its document shapes, and the provider contract.
 - [Seller module](content/references/modules/seller.mdx) — Data models, links, and service methods for the Seller module.
 - [References](content/references/overview.mdx) — Technical references for Mercur's modules, HTTP APIs, workflows, and configuration.
+- [Panel Extension API](content/references/panel-extension-api.mdx) — The file-based helpers for extending the admin and vendor panels — defineWidgetConfig, defineNavigationConfig, defineCustomFieldsConfig, createFormHelper — and the exact props passed to every component you supply.
 - [addSellerShippingMethodToCartWorkflow](content/references/workflows/cart/add-seller-shipping-method-to-cart.mdx) — Add shipping methods to a cart, replacing only the same seller's existing methods.
 - [completeCartWithSplitOrdersWorkflow](content/references/workflows/cart/complete-cart-with-split-orders.mdx) — Complete a multi-seller cart by splitting it into per-seller orders under an order group.
 - [listSellerShippingOptionsForCartWorkflow](content/references/workflows/cart/list-seller-shipping-options-for-cart.mdx) — List available shipping options for a cart, grouped by seller.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercurjs/docs",
-  "version": "2.2.0-rc.0",
+  "version": "2.2.0-rc.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/mercurjs/mercur",

package/content/resources/tutorials/recompose-a-page.mdx

@@ -1,129 +0,0 @@
----
-title: "Re-compose a built-in page"
-description: "Override a built-in panel page by dropping a route file at the same path and re-composing its compound component slots."
----
-
-Every page in the admin and vendor panels is exported as a **compound component** — a root plus named slots like `Header`, `HeaderActions`, and `DataTable`. That means you never fork a page to change one part of it: you drop a `page.tsx` at the same route path, render the original page, and swap only the slot you care about. Everything you don't touch keeps its default behavior — data fetching, filters, pagination, i18n, all of it.
-
-<Info>
-  **This is not Medusa's widget system.** Medusa's admin lets you inject widgets into predefined zones around a page. Mercur takes a different approach: pages are React compound components you re-compose directly. There are no injection zones and no `defineWidgetConfig` — you get the actual page component and decide what renders inside it. See [Extending Panels](/rc/resources/customization/extending-panels) for the full comparison.
-</Info>
-
-## What you'll build
-
-A vendor portal `/products` page with **Import** and **Export** buttons added next to the built-in Create button — while the table, search, filters, and everything else stay exactly as shipped. This is the same technique the official `product-import-export` block uses.
-
-## Slot anatomy
-
-Built-in pages are exported from the `/pages` subpath of each panel package:
-
-```typescript
-import { ProductListPage } from "@mercurjs/vendor/pages"   // vendor portal
-import { CustomerListPage } from "@mercurjs/admin/pages"   // admin panel
-```
-
-Each list page exposes the same family of slots:
-
-| Slot | Renders |
-|------|---------|
-| `Table` | The `Container` shell holding header + table |
-| `Header` | The title/actions row |
-| `HeaderTitle` | Heading and subtitle |
-| `HeaderActions` | The action button cluster |
-| `HeaderCreateButton` | The built-in Create button |
-| `DataTable` | The wired data table — fetching, columns, filters, pagination |
-
-Detail pages expose section slots instead (e.g. `CustomerDetailPage.Main`, `CustomerDetailPage.Sidebar`, `CustomerDetailPage.MainGeneralSection`).
-
-## Override the page
-
-<Steps>
-  <Step title="Drop a route file at the same path">
-    Create the file in your vendor app at the path that matches the built-in route. `/products` maps to `src/routes/products/page.tsx`:
-
-    ```tsx apps/vendor/src/routes/products/page.tsx
-    import { Link } from "react-router-dom"
-    import { Button } from "@medusajs/ui"
-    import { ArrowDownTray, ArrowUpTray } from "@medusajs/icons"
-    import { ProductListPage } from "@mercurjs/vendor/pages"
-
-    export default function ProductsWithImportExport() {
-      return (
-        <ProductListPage>
-          <ProductListPage.Table>
-            <ProductListPage.Header>
-              <ProductListPage.HeaderTitle />
-              <ProductListPage.HeaderActions>
-                <Button size="small" variant="secondary" asChild>
-                  <Link to="import">
-                    <ArrowUpTray />
-                    Import
-                  </Link>
-                </Button>
-                <Button size="small" variant="secondary" asChild>
-                  <Link to="export">
-                    <ArrowDownTray />
-                    Export
-                  </Link>
-                </Button>
-                <ProductListPage.HeaderCreateButton />
-              </ProductListPage.HeaderActions>
-            </ProductListPage.Header>
-            <ProductListPage.DataTable />
-          </ProductListPage.Table>
-        </ProductListPage>
-      )
-    }
-    ```
-  </Step>
-  <Step title="Reuse the slots you don't change">
-    Note what happened in that file: `HeaderTitle`, `HeaderCreateButton`, and `DataTable` are the originals, rendered untouched. Only `HeaderActions` gained two buttons. You re-compose top-down — render the page, re-declare only the branch you're changing, and keep original slots for everything inside it.
-  </Step>
-  <Step title="Reload the panel">
-    The dashboard SDK picks the file up automatically (adding or removing a route file triggers a full reload in dev). Because the path matches a built-in route, **your page replaces the built-in one** — no configuration, no registration.
-  </Step>
-</Steps>
-
-<Note>
-  When a custom route's path matches a built-in route, your page replaces the built-in one. Routes at new paths are appended instead. That one rule is the entire override mechanism.
-</Note>
-
-## How defaults work
-
-If you render a compound page with **no children**, it renders its full default composition — so `<ProductListPage />` alone is identical to the built-in page. Every page root follows the pattern:
-
-```tsx
-Children.count(children) > 0 ? children : <DefaultComposition />
-```
-
-## Verify
-
-1. Run your project (`bun run dev`) and open the vendor portal.
-2. Navigate to **Products** — the list should look identical to before, plus Import and Export buttons in the header.
-3. Search, filter, and paginate the table — all built-in behavior must still work, since `DataTable` is untouched.
-4. Delete your `src/routes/products/page.tsx` and reload — the built-in page comes back. Nothing was forked.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="Where do I find which slots a page exposes?">
-    Import the page from `@mercurjs/vendor/pages` or `@mercurjs/admin/pages` and let your editor's autocomplete list the attached members — every slot is a static property on the page component. The naming is consistent across pages: list pages expose `Table`/`Header`/`HeaderTitle`/`HeaderActions`/`HeaderCreateButton`/`DataTable`; detail pages expose `Main`/`Sidebar` plus one property per section.
-  </Accordion>
-  <Accordion title="Can I remove a built-in element, like the Create button?">
-    Yes — re-composition is declarative. Anything you don't render doesn't appear: re-declare `HeaderActions` with only your own buttons and omit `HeaderCreateButton`.
-  </Accordion>
-  <Accordion title="What about changing the table columns?">
-    `DataTable` is a single slot — you either keep it wholesale or replace it with your own table. For a different column set, replace the slot with your own component built on the shared `DataTable`/`useDataTable` primitives from the panel package.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Replace panel components" href="/rc/resources/tutorials/replace-panel-components">
-    Swap global chrome like the sidebar or topbar instead of a single page.
-  </Card>
-  <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route">
-    Back your custom page with a typed endpoint of your own.
-  </Card>
-</CardGroup>

package/content/resources/tutorials/replace-panel-components.mdx

@@ -1,116 +0,0 @@
----
-title: "Replace panel components"
-description: "Swap the sidebar, topbar actions, or store setup screen for your own components through dashboard SDK configuration."
----
-
-Some customizations aren't about one page — they change the panel's global chrome. For those, the dashboard SDK exposes a small set of **named component overrides**: you point the plugin config at your own file, and the panel renders your component in place of the built-in one everywhere it appears.
-
-<Info>
-  **Choose the right tool.** A component override replaces one of four global layout slots across the whole panel. If you want to change a single page, [re-compose it](/rc/resources/tutorials/recompose-a-page) instead — and if you want to add a new screen, just [drop in a route](/rc/resources/tutorials/custom-panel-page). The decision guide in [Extending Panels](/rc/resources/customization/extending-panels#choosing-your-extension-mechanism) compares all three.
-</Info>
-
-## What you'll build
-
-A vendor portal with custom topbar actions (a help link and a status badge) and a custom main sidebar, configured entirely from `vite.config.ts`.
-
-## The available slots
-
-Exactly four layout components can be replaced:
-
-| Component | Where it renders |
-|-----------|------------------|
-| `MainSidebar` | Primary navigation sidebar on every main page |
-| `SettingsSidebar` | Sidebar of the `/settings` section |
-| `TopbarActions` | Action cluster on the right side of the top bar |
-| `StoreSetup` | The store setup screen shown to new sellers (vendor portal) |
-
-Anything else — a page, a section, a table — is customized through routes and compound components, not through overrides.
-
-## Set up the override
-
-<Steps>
-  <Step title="Write the replacement component">
-    Create the component anywhere under `src/`. It must have a **default export**:
-
-    ```tsx apps/vendor/src/components/topbar-actions.tsx
-    import { Badge, Button } from "@medusajs/ui"
-
-    export default function TopbarActions() {
-      return (
-        <div className="flex items-center gap-x-2">
-          <Badge size="2xsmall" color="green">
-            All systems operational
-          </Badge>
-          <Button size="small" variant="transparent" asChild>
-            <a href="https://help.example.com" target="_blank" rel="noreferrer">
-              Help
-            </a>
-          </Button>
-        </div>
-      )
-    }
-    ```
-  </Step>
-  <Step title="Register it in the Vite config">
-    Component overrides live in the `components` option of `mercurDashboardPlugin`, in your panel app's `vite.config.ts`. Paths are **relative to `src/`**:
-
-    ```typescript apps/vendor/vite.config.ts
-    import { defineConfig } from 'vite'
-    import react from '@vitejs/plugin-react'
-    import { mercurDashboardPlugin } from '@mercurjs/dashboard-sdk'
-
-    export default defineConfig({
-      plugins: [
-        react(),
-        mercurDashboardPlugin({
-          medusaConfigPath: '../../packages/api/medusa-config.ts',
-          components: {
-            TopbarActions: 'components/topbar-actions',
-            MainSidebar: 'components/main-sidebar',
-          },
-        }),
-      ],
-    })
-    ```
-
-    The plugin resolves each path at build time and swaps your component in through the `virtual:mercur/components` module — no runtime registration, no context providers to wire.
-  </Step>
-  <Step title="Restart the dev server">
-    Vite config changes require a restart. After it, your components render everywhere their slots appear.
-  </Step>
-</Steps>
-
-<Tip>
-  Build overrides with `@medusajs/ui` components and Medusa UI color tokens so they match the rest of the panel. The panels ship no other UI library.
-</Tip>
-
-## Verify
-
-1. Open the vendor portal — the top bar shows your badge and Help link on every page.
-2. Navigate between main pages and `/settings` — the override applies everywhere its slot renders.
-3. Remove the `components` entry and restart — the built-in components return. The originals were never modified.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="If I replace MainSidebar, do my custom routes still show up in the menu?">
-    Only if your sidebar renders them. A `MainSidebar` override replaces the **entire** navigation sidebar, including the auto-generated menu items from route `config` exports — read them from `virtual:mercur/menu-items` if you want to keep automatic navigation. If you only want to add or reorder items, you don't need an override at all: the `config` export on route files (with `rank` and `nested`) covers that.
-  </Accordion>
-  <Accordion title="Can I override other components, like the login page or a form?">
-    No — these four slots are the complete list. The login flow, forms, and everything page-level are customized through drop-in routes and [compound re-composition](/rc/resources/tutorials/recompose-a-page).
-  </Accordion>
-  <Accordion title="Do overrides apply to both panels?">
-    Each panel app has its own `vite.config.ts`, so overrides are configured per panel. `StoreSetup` only exists in the vendor portal; the other three slots exist in both.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Re-compose a built-in page" href="/rc/resources/tutorials/recompose-a-page">
-    Change one page's composition instead of global chrome.
-  </Card>
-  <Card title="Extending Panels" href="/rc/resources/customization/extending-panels">
-    The full reference for routes, navigation, branding, and overrides.
-  </Card>
-</CardGroup>