@mercurjs/docs 2.2.1 → 2.3.0-canary.1

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

@@ -1,214 +0,0 @@
----
-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/content/tools/api-client.mdx

@@ -1,155 +0,0 @@
----
-title: "API Client"
-description: "Type-safe client for consuming Mercur APIs."
----
-
-`@mercurjs/client` provides a type-safe way to interact with your Mercur backend. Every endpoint, request input, and response is fully typed — inferred directly from your backend routes.
-
-## Installation
-
-```bash
-bun add @mercurjs/client
-```
-
-## Create a client
-
-```typescript
-import { createClient } from "@mercurjs/client";
-import type { Routes } from "./.mercur/_generated";
-
-export const client = createClient<Routes>({
-  baseUrl: "http://localhost:9000",
-});
-```
-
-<Info>
-  The `Routes` type is generated from your backend using `@mercurjs/cli@latest
-  codegen`. This gives the client full type safety with zero manual type
-  definitions.
-</Info>
-
-You can pass default fetch options for authentication or other headers:
-
-```typescript
-export const client = createClient<Routes>({
-  baseUrl: "http://localhost:9000",
-  fetchOptions: {
-    credentials: "include",
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
-  },
-});
-```
-
-## Calling APIs
-
-The client exposes three methods:
-
-```typescript
-// GET — fetch data
-const { reviews } = await client.vendor.reviews.query({ limit: 10 });
-
-// POST — create or update
-const { product } = await client.vendor.products.mutate({
-  title: "New Product",
-  status: "draft",
-});
-
-// DELETE — remove a resource
-await client.vendor.reviews.$id.delete({ $id: "rev_123" });
-```
-
-Use `$`-prefixed keys for path parameters:
-
-```typescript
-const { review } = await client.vendor.reviews.$id.query({
-  $id: "rev_123",
-});
-```
-
-Override fetch options per request when needed:
-
-```typescript
-const { reviews } = await client.vendor.reviews.query({
-  fetchOptions: {
-    signal: abortController.signal,
-  },
-});
-```
-
-## Inferring types
-
-Extract input and output types from any client method using `InferClientInput` and `InferClientOutput`:
-
-```typescript
-import type { InferClientInput, InferClientOutput } from "@mercurjs/client";
-
-type ListInput = InferClientInput<typeof client.vendor.reviews.query>;
-type ReviewDTO = InferClientOutput<
-  typeof client.vendor.reviews.$id.query
->["review"];
-```
-
-## React Query
-
-The client returns plain Promises, so it works with any data-fetching library. Here's a typical pattern with TanStack React Query:
-
-```typescript
-import { useQuery } from "@tanstack/react-query";
-import { client } from "../lib/client";
-
-export function useReviews(
-  query?: InferClientInput<typeof client.vendor.reviews.query>,
-) {
-  const { data, ...rest } = useQuery({
-    queryKey: ["reviews", query],
-    queryFn: () => client.vendor.reviews.query(query),
-  });
-
-  return { ...data, ...rest };
-}
-```
-
-## Error handling
-
-Failed requests throw a `ClientError`:
-
-```typescript
-import { ClientError } from "@mercurjs/client";
-
-try {
-  await client.vendor.reviews.$id.query({ $id: "invalid" });
-} catch (error) {
-  if (error instanceof ClientError) {
-    error.message; // "Review not found"
-    error.status; // 404
-    error.statusText; // "Not Found"
-  }
-}
-```
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="Why is a route missing from the client after I added it?">
-    The client's types come from the generated route map — run `bunx @mercurjs/cli@latest codegen` after adding or changing route files. During development, `codegen --watch` keeps the map current automatically.
-  </Accordion>
-  <Accordion title="How are URLs derived from property access?">
-    Each property becomes a kebab-cased path segment (`client.vendor.salesSummary` → `/vendor/sales-summary`), `$`-prefixed keys fill path parameters, and the terminal method picks the HTTP verb: `query` → GET, `mutate` → POST, `delete` → DELETE.
-  </Accordion>
-  <Accordion title="Can I upload files through the client?">
-    Yes — pass `Blob`/`File` values in the payload and the client switches to multipart form data automatically.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Add a custom API route" href="/rc/resources/tutorials/custom-api-route">
-    Build a route and call it through the client, end to end.
-  </Card>
-  <Card title="CLI" href="/rc/tools/cli">
-    The codegen command that generates the client's route map.
-  </Card>
-</CardGroup>

package/content/tools/cli.mdx

@@ -1,196 +0,0 @@
----
-title: "CLI"
-description: "Install blocks, scaffold projects, and generate types from the command line."
----
-
-The Mercur CLI (`@mercurjs/cli@latest`) manages your marketplace project — installing blocks, generating types, and checking for updates. To create a new project, use [`create-mercur-app`](https://www.npmjs.com/package/create-mercur-app).
-
-## Installation
-
-```bash
-bun add -g @mercurjs/cli@latest
-```
-
-## Commands
-
-### create
-
-Scaffolding new projects lives in the standalone [`create-mercur-app`](https://www.npmjs.com/package/create-mercur-app) package, so it downloads fast and works with every package manager's `create` command.
-
-```bash
-bun create mercur-app@latest my-marketplace
-# or
-npm create mercur-app@latest my-marketplace
-```
-
-It will prompt you for database credentials and install dependencies automatically.
-
-| Option | Description |
-|--------|-------------|
-| `-t, --template <template>` | Template to use (default: `basic`) |
-| `--no-deps` | Skip dependency installation |
-| `--skip-db` | Skip database configuration |
-| `--db-connection-string <string>` | PostgreSQL connection string |
-
-### init
-
-Initialize an existing project by creating a `blocks.json` configuration file.
-
-```bash
-bunx @mercurjs/cli@latest init
-```
-
-This sets up path aliases so the CLI knows where to place blocks in your project:
-
-```json
-{
-  "aliases": {
-    "api": "packages/api/src",
-    "vendor": "apps/vendor/src",
-    "admin": "apps/admin/src"
-  }
-}
-```
-
-| Option | Description |
-|--------|-------------|
-| `-d, --defaults` | Use default paths without prompting |
-| `-s, --silent` | Suppress output |
-
-### add
-
-Install blocks from the registry into your project.
-
-```bash
-bunx @mercurjs/cli@latest add wishlist
-bunx @mercurjs/cli@latest add product-review order-tracking
-```
-
-Blocks are copied directly into your project as source code. The CLI resolves dependencies, transforms imports to match your path aliases, and installs required packages.
-
-| Option | Description |
-|--------|-------------|
-| `-o, --overwrite` | Overwrite existing files |
-| `-y, --yes` | Skip confirmation |
-| `-s, --silent` | Suppress output |
-
-### search
-
-Find available blocks in the registry.
-
-```bash
-bunx @mercurjs/cli@latest search --query wishlist
-```
-
-| Option | Description |
-|--------|-------------|
-| `-q, --query <query>` | Search by name or description |
-| `-r, --registry <registry>` | Registry to search (default: `@mercurjs`) |
-
-### view
-
-Display detailed information about a block.
-
-```bash
-bunx @mercurjs/cli@latest view wishlist
-```
-
-### diff
-
-Compare local blocks against registry versions to check for updates.
-
-```bash
-bunx @mercurjs/cli@latest diff wishlist
-```
-
-If there are changes you want, update with:
-
-```bash
-bunx @mercurjs/cli@latest add wishlist --overwrite
-```
-
-### codegen
-
-Generate TypeScript types from your API routes. Used by the [API Client](/rc/tools/api-client) for type-safe requests.
-
-```bash
-bunx @mercurjs/cli@latest codegen
-```
-
-| Option | Description |
-|--------|-------------|
-| `-w, --watch` | Watch for changes and regenerate automatically |
-
-### registry:build
-
-Build a custom registry from a `registry.json` file.
-
-```bash
-bunx @mercurjs/cli@latest build
-```
-
-| Option | Description |
-|--------|-------------|
-| `-o, --output <path>` | Output directory (default: `./r`) |
-| `-v, --verbose` | Show detailed output |
-
-### info
-
-Display project configuration and diagnostics.
-
-```bash
-bunx @mercurjs/cli@latest info
-```
-
-### telemetry
-
-Control anonymous usage data collection.
-
-```bash
-bunx @mercurjs/cli@latest telemetry --disable
-bunx @mercurjs/cli@latest telemetry --enable
-```
-
-## Custom registries
-
-Add custom block registries to your `blocks.json`:
-
-```json
-{
-  "registries": {
-    "@mercurjs": "https://registry.mercurjs.com/{name}",
-    "@my-registry": "https://my-registry.com/blocks/{name}.json"
-  }
-}
-```
-
-Use `{name}` as a placeholder for block names. Reference custom registries with the `-r` flag:
-
-```bash
-bunx @mercurjs/cli@latest search --query review --registry @my-registry
-```
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="When do I use create vs init?">
-    `create` scaffolds a brand-new project from a template. `init` only writes a `blocks.json` into an **existing** project so the CLI knows where to place blocks — use it when adopting blocks in a repo that wasn't created by the CLI.
-  </Accordion>
-  <Accordion title="When do I need to run codegen?">
-    After any change to API route files — added routes, changed validators, renamed paths. The [typed client](/rc/tools/api-client) reads the generated route map, so stale types mean `codegen` hasn't run.
-  </Accordion>
-  <Accordion title="Will add overwrite my local changes to a block?">
-    Not silently — the CLI asks before overwriting existing files unless you pass `--overwrite`. Use `diff` first to see exactly what changed between your copy and the registry.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Add a feature with a block" href="/rc/resources/tutorials/add-a-block">
-    The install workflow end to end — search, view, add, migrate.
-  </Card>
-  <Card title="API Client" href="/rc/tools/api-client">
-    What codegen's route map powers on the frontend.
-  </Card>
-</CardGroup>

package/content/tools/dashboard-sdk.mdx

@@ -1,35 +0,0 @@
----
-title: "Dashboard SDK"
-description: "The Vite plugin that powers admin and vendor panel extension — file-based routing, virtual modules, and block resolution."
----
-
-<Note>
-  This reference is being written. The outline below is the intended structure.
-</Note>
-
-<Info>
-  **Not Medusa's admin-vite-plugin.** The dashboard SDK is Mercur's own extension framework for both panels — it scans `src/routes/**/page.tsx` files, generates navigation, and injects everything through `virtual:mercur/*` modules at build time. Medusa's `defineWidgetConfig` / `defineRouteConfig` and widget zones are not part of this model. Start with [Extending Panels](/rc/resources/customization/extending-panels) for the authoring guide; this page covers the plugin's internals and options.
-</Info>
-
-## What it does
-
-File-based routing, virtual route modules, and block resolution for the admin and vendor panels.
-
-## Setup in a host app
-
-Registering `mercurDashboardPlugin` in a Vite app.
-
-## Configuration options
-
-Backend and vendor URLs, i18n, and build-time config.
-
-## Extension entry points
-
-`admin_ui` and `vendor_ui` entry points exported by block packages.
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Extending the panels" href="/rc/resources/customization/extending-panels" />
-  <Card title="API client" href="/rc/tools/api-client" />
-</CardGroup>