@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/best-practices/api-routes.mdx

@@ -1,22 +1,23 @@
 ---
-title: "API routes"
-description: "Thin HTTP adapters — typed request/response generics, Zod validation with createFindParams, filterable fields, middlewares as filters, and queryConfig."
+title: "How to Create an API Route"
+sidebarTitle: "Create an API Route"
+description: "Write API routes as thin HTTP adapters that type both sides, validate with Zod, and scope reads through middlewares and queryConfig."
 ---
 
-An API route is a thin adapter between HTTP and the rest of the system. Its whole job is: validate the request, run a [workflow](/rc/resources/best-practices/workflows) (for writes) or a [Query](/rc/resources/best-practices/workflows#the-query-engine) (for reads), and shape the response. No business logic lives here.
+An API route is a thin adapter between HTTP and the rest of the system. It validates the request, runs a [workflow](/rc/resources/best-practices/workflows) for writes or a [Query](/rc/resources/best-practices/workflows#the-query-engine) for reads, and shapes the response. No business logic lives here.
 
 <Note>
-  Routes are [Medusa file-based API routes](https://docs.medusajs.com/learn/fundamentals/api-routes): a `route.ts` under `src/api/**` exports handlers named after HTTP verbs, and a sibling `middlewares.ts` wires validation and filters. Examples below use a custom **Brand** module exposed under `/admin/brands`.
+  Routes are [Medusa file-based API routes](https://docs.medusajs.com/learn/fundamentals/api-routes). A `route.ts` under `src/api/**` exports handlers named after HTTP verbs, and a sibling `middlewares.ts` wires validation and filters. Examples below use a custom **Brand** module exposed under `/admin/brands`.
 </Note>
 
 ## Type both the request and the response
 
-Every handler is typed on **both** sides — mirror how Medusa's own routes are written:
+Type every handler on both sides. Mirror how Medusa's own routes are written:
 
-- `AuthenticatedMedusaRequest<TBodyOrQuery>` — the generic is the validated **body** (writes) or **query params** (reads) type.
-- `MedusaResponse<TResponse>` — the generic is the **response shape**, so `res.json(...)` is checked and the SDK infers a real return type instead of `unknown`.
+- **`AuthenticatedMedusaRequest<TBodyOrQuery>`:** the generic is the validated body for writes or the query params type for reads.
+- **`MedusaResponse<TResponse>`:** the generic is the response shape, so `res.json(...)` is checked and the SDK infers a real return type instead of `unknown`.
 
-```ts title="src/api/admin/brands/route.ts"
+```ts src/api/admin/brands/route.ts
 import {
   AuthenticatedMedusaRequest,
   MedusaResponse,
@@ -64,13 +65,13 @@ export const POST = async (
 ```
 
 <Warning>
-  Don't leave `MedusaResponse` bare. An untyped response means `res.json({...})` accepts anything and the typed SDK resolves that endpoint to an empty/`unknown` response — the exact opposite of the point of the typed client. Always pass the response generic.
+  Don't leave `MedusaResponse` bare. An untyped response means `res.json({...})` accepts anything and the typed SDK resolves that endpoint to an empty or `unknown` response, the exact opposite of the point of the typed client. Always pass the response generic.
 </Warning>
 
 ## Only `GET`, `POST`, `DELETE`
 
 <Warning>
-  Mercur routes use **only** `GET`, `POST`, and `DELETE`. There is no `PUT` or `PATCH` — model an update as a `POST` to the resource. Keeping to three verbs is what keeps the typed SDK (`.query` / `.mutate` / `.delete`) consistent across every route.
+  Mercur routes use only `GET`, `POST`, and `DELETE`. There is no `PUT` or `PATCH`. Model an update as a `POST` to the resource. Keeping to three verbs is what keeps the typed SDK (`.query` / `.mutate` / `.delete`) consistent across every route.
 </Warning>
 
 | Verb | Meaning | SDK method |
@@ -81,11 +82,11 @@ export const POST = async (
 
 ## Validation with Zod + exported types
 
-Validation happens in `middlewares.ts` via `validateAndTransformBody` / `validateAndTransformQuery`, and every schema exports its inferred type so the handler generic and the SDK share one source of truth.
+Validation happens in `middlewares.ts` via `validateAndTransformBody` / `validateAndTransformQuery`. Every schema exports its inferred type so the handler generic and the SDK share one source of truth.
 
-**Bodies** are plain Zod objects:
+Bodies are plain Zod objects:
 
-```ts title="src/api/admin/brands/validators.ts"
+```ts src/api/admin/brands/validators.ts
 import { z } from "zod"
 
 export const AdminCreateBrand = z.object({
@@ -96,9 +97,9 @@ export const AdminCreateBrand = z.object({
 export type AdminCreateBrandType = z.infer<typeof AdminCreateBrand>
 ```
 
-**List/read params** use the framework helpers — `createFindParams` (pagination + `fields` + `order`) and `createSelectParams` (retrieve) — rather than a hand-rolled object. This is what wires pagination and field selection consistently across every route:
+List and read params use the framework helpers `createFindParams` (pagination, `fields`, and `order`) and `createSelectParams` (retrieve) rather than a hand-rolled object. This wires pagination and field selection consistently across every route:
 
-```ts title="src/api/admin/brands/validators.ts"
+```ts src/api/admin/brands/validators.ts
 import { createFindParams, createOperatorMap } from "@medusajs/medusa/api/utils/validators"
 
 export const AdminGetBrandsParams = createFindParams({
@@ -117,13 +118,13 @@ export const AdminGetBrandsParams = createFindParams({
 export type AdminGetBrandsParamsType = z.infer<typeof AdminGetBrandsParams>
 ```
 
-The handler then trusts `req.validatedBody` / the validated query to already match those types — never re-validate inside the handler.
+The handler then trusts `req.validatedBody` and the validated query to already match those types. Never re-validate inside the handler.
 
 ## List vs retrieve
 
-A list route (`GET /admin/brands`) and a retrieve route (`GET /admin/brands/:id`) select fields the same way but differ in their params helper and response shape. Retrieve uses `createSelectParams` (field selection only — no pagination or filters) and returns a single entity:
+A list route (`GET /admin/brands`) and a retrieve route (`GET /admin/brands/:id`) select fields the same way but differ in their params helper and response shape. Retrieve uses `createSelectParams` (field selection only, no pagination or filters) and returns a single entity:
 
-```ts title="src/api/admin/brands/[id]/route.ts"
+```ts src/api/admin/brands/[id]/route.ts
 export const GET = async (
   req: AuthenticatedMedusaRequest<AdminGetBrandParamsType>,
   res: MedusaResponse<AdminBrandResponse>
@@ -146,18 +147,18 @@ export const GET = async (
 }
 ```
 
-```ts title="src/api/admin/brands/validators.ts — retrieve params"
+```ts src/api/admin/brands/validators.ts: retrieve params
 import { createSelectParams } from "@medusajs/medusa/api/utils/validators"
 
 export const AdminGetBrandParams = createSelectParams()
 export type AdminGetBrandParamsType = z.infer<typeof AdminGetBrandParams>
 ```
 
-Both share the same `defaults` idea but declare them separately in the query config (`list` vs `retrieve`) — see [`queryConfig`](/rc/resources/best-practices/api-routes#queryconfig-and-field-selection) below.
+Both share the same `defaults` idea but declare them separately in the query config (`list` vs `retrieve`). See [`queryConfig`](/rc/resources/best-practices/api-routes#queryconfig-and-field-selection) below.
 
 ## Filterable fields
 
-`req.filterableFields` is the **parsed, validated filter set** produced by `validateAndTransformQuery` from the query params above. Only fields your validator declares can appear there — an unknown query param is dropped, not passed through. The handler forwards it straight to Query:
+`req.filterableFields` is the parsed, validated filter set produced by `validateAndTransformQuery` from the query params above. Only fields your validator declares can appear there. An unknown query param is dropped, not passed through. The handler forwards it straight to Query:
 
 ```ts
 const { data: brands, metadata } = await query.graph({
@@ -169,14 +170,14 @@ const { data: brands, metadata } = await query.graph({
 ```
 
 <Tip>
-  This is why filtering is declarative and safe: to make a field filterable you add it to the validator; to scope a request you inject onto `req.filterableFields` in middleware (next section). The handler never builds a `where` clause by hand.
+  This is why filtering is declarative and safe. To make a field filterable you add it to the validator. To scope a request you inject onto `req.filterableFields` in middleware (next section). The handler never builds a `where` clause by hand.
 </Tip>
 
 ## Middlewares as filters
 
-Middlewares aren't only for validation — they're where you inject **scoping filters** so handlers stay ignorant of the rule. A small middleware writes onto `req.filterableFields`; because the handler already forwards that to Query, the scope is applied without the handler knowing. For example, force `GET /admin/brands` to only ever return active rows:
+Middlewares aren't only for validation. They're where you inject scoping filters so handlers stay ignorant of the rule. A small middleware writes onto `req.filterableFields`, and because the handler already forwards that to Query, the scope is applied without the handler knowing. For example, force `GET /admin/brands` to only ever return active rows:
 
-```ts title="src/api/admin/brands/middlewares.ts"
+```ts src/api/admin/brands/middlewares.ts
 import {
   MedusaRequest,
   MedusaResponse,
@@ -205,28 +206,28 @@ export const adminBrandsMiddlewares = [
 ```
 
 <Tip>
-  Injecting a filter in middleware means a new route on the same resource is scoped by construction, not by remembering to add a filter. This works with `query.graph` because `is_active` lives on the **brand's own module**.
+  Injecting a filter in middleware means a new route on the same resource is scoped by construction, not by remembering to add a filter. This works with `query.graph` because `is_active` lives on the brand's own module.
 </Tip>
 
 <Warning>
-  You can only filter this way on a field that belongs to the entity's **own module**. Filtering by a **linked** module's field (e.g. products by their `brand`) does **not** work with `query.graph` — Query aggregates modules after the fact, so there's no join to filter on. Cross-module filtering requires the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module) and `query.index`.
+  You can only filter this way on a field that belongs to the entity's own module. Filtering by a linked module's field (e.g. products by their `brand`) does not work with `query.graph`. Query aggregates modules after the fact, so there's no join to filter on. Cross-module filtering requires the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module) and `query.index`.
 </Warning>
 
 ## Trust the auth middleware
 
-Authentication and actor resolution happen in middleware (`authenticate`), so by the time your handler runs the actor is already established — **trust it**. Read identity from the request context, never from the body:
+Authentication and actor resolution happen in middleware (`authenticate`), so by the time your handler runs the actor is already established. Trust it. Read identity from the request context, never from the body:
 
 ```ts
 const userId = req.auth_context.actor_id // set by the authenticate middleware
 ```
 
 <Warning>
-  Don't re-derive or re-check identity inside handlers, and don't read user/owner ids from the request body — always take them from `req.auth_context` (or a context object a scoping middleware populated). Trusting the middleware keeps authorization in one place.
+  Don't re-derive or re-check identity inside handlers, and don't read user or owner ids from the request body. Always take them from `req.auth_context` (or a context object a scoping middleware populated). Trusting the middleware keeps authorization in one place.
 </Warning>
 
 ## Vendor routes: `seller_context`
 
-Every route under `/vendor/*` is **already authenticated and seller-scoped** — you don't wire auth yourself. By the time your handler runs, the caller is a verified seller member and the request carries a `req.seller_context` you can trust:
+Every route under `/vendor/*` is already authenticated and seller-scoped. You don't wire auth yourself. By the time your handler runs, the caller is a verified seller member and the request carries a `req.seller_context` you can trust:
 
 ```ts
 export const POST = async (
@@ -239,12 +240,12 @@ export const POST = async (
 }
 ```
 
-`req.seller_context` gives you `seller_id`, `currency_code`, and the `seller_member` — all verified, so you never re-check membership in a handler.
+`req.seller_context` gives you `seller_id`, `currency_code`, and the `seller_member`, all verified, so you never re-check membership in a handler.
 
 <Warning>
-  Never take a `seller_id` from the request body or query to decide ownership — that's caller-supplied. The **only** authoritative seller is `req.seller_context.seller_id`. To scope a vendor list route to the caller's data, add the `filterBySellerId()` middleware and every query is constrained automatically — no per-handler `where`:
+  Never take a `seller_id` from the request body or query to decide ownership. That's caller-supplied. The only authoritative seller is `req.seller_context.seller_id`. To scope a vendor list route to the caller's data, add the `filterBySellerId()` middleware and every query is constrained automatically, with no per-handler `where`:
 
-  ```ts title="src/api/vendor/offers/middlewares.ts"
+  ```ts src/api/vendor/offers/middlewares.ts
   import { filterBySellerId } from "@mercurjs/core/..."
 
   {
@@ -262,7 +263,7 @@ export const POST = async (
 
 `validateAndTransformQuery` takes a query config that controls which `fields` are selectable, `isList`, and default pagination. The handler reads the resolved selection from `req.queryConfig.fields` and pagination from `req.queryConfig.pagination`.
 
-```ts title="src/api/admin/brands/query-config.ts"
+```ts src/api/admin/brands/query-config.ts
 export const adminBrandQueryConfig = {
   list: {
     defaults: ["id", "name", "is_active", "created_at"],
@@ -275,14 +276,14 @@ export const adminBrandQueryConfig = {
 ```
 
 <Warning>
-  **`fields` replaces defaults unless prefixed.** An unprefixed field in the request's `fields` param *replaces* the route's default set; prefix with `+`/`-` to merge (e.g. `+brand.name`) or base fields like `thumbnail` silently drop. This is the `medusa-fields-param` gotcha.
+  **`fields` replaces defaults unless prefixed.** An unprefixed field in the request's `fields` param *replaces* the route's default set. Prefix with `+`/`-` to merge (e.g. `+brand.name`), or base fields like `thumbnail` silently drop. This is the `medusa-fields-param` gotcha.
 </Warning>
 
 ## Response types
 
-Declare the response shapes next to the route (or in `@mercurjs/types` for shared ones) and use them as the `MedusaResponse` generic — the SDK reads these to type `.query()` / `.mutate()` returns:
+Declare the response shapes next to the route (or in `@mercurjs/types` for shared ones) and use them as the `MedusaResponse` generic. The SDK reads these to type `.query()` and `.mutate()` returns:
 
-```ts title="src/api/admin/brands/types.ts"
+```ts src/api/admin/brands/types.ts
 import { PaginatedResponse } from "@medusajs/framework/types"
 
 export interface AdminBrandResponse {
@@ -296,11 +297,22 @@ export type AdminBrandListResponse = PaginatedResponse<{
 
 ## Checklist for a route
 
-- Handler is thin: validate → run workflow (writes) or `query.graph` (reads) → respond.
-- **Both** generics set: `AuthenticatedMedusaRequest<TBody|TQuery>` and `MedusaResponse<TResponse>` — never a bare `MedusaResponse`.
-- Only `GET` / `POST` / `DELETE` exported; updates are `POST`.
-- Query params built with `createFindParams` / `createSelectParams`; bodies with Zod; inferred types exported.
-- Filterable fields declared in the validator; scoping injected via a `filterableFields` middleware, not inlined.
-- Identity read from `req.auth_context`, never the body. On vendor routes, the authoritative seller is `req.seller_context.seller_id` (set by `ensureSellerMiddleware`); scope reads with `filterBySellerId()`.
-- `fields` prefixed with `+`/`-` to merge; defaults declared in `queryConfig`.
+- Handler is thin: validate, run a workflow (writes) or `query.graph` (reads), then respond.
+- Both generics set: `AuthenticatedMedusaRequest<TBody|TQuery>` and `MedusaResponse<TResponse>`, never a bare `MedusaResponse`.
+- Only `GET` / `POST` / `DELETE` exported. Updates are `POST`.
+- Query params built with `createFindParams` / `createSelectParams`, bodies with Zod, and inferred types exported.
+- Filterable fields declared in the validator. Scoping injected via a `filterableFields` middleware, not inlined.
+- Identity read from `req.auth_context`, never the body. On vendor routes, the authoritative seller is `req.seller_context.seller_id` (set by `ensureSellerMiddleware`). Scope reads with `filterBySellerId()`.
+- `fields` prefixed with `+`/`-` to merge. Defaults declared in `queryConfig`.
 - No mutations outside a workflow.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Workflows" href="/rc/resources/best-practices/workflows">
+    Run business logic and the Query engine behind your routes.
+  </Card>
+  <Card title="Module links" href="/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module">
+    Filter by a linked field with the Index Module and `query.index`.
+  </Card>
+</CardGroup>

package/content/resources/best-practices/custom-fields.mdx

@@ -1,15 +1,20 @@
 ---
-title: "Custom fields"
-description: "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."
+title: "How to Add a Custom Field"
+sidebarTitle: "Add a Custom Field"
+description: "Attach extra data to a built-in entity across the full stack: declare it in core, render it in the panels, pull in linked data, and type it end-to-end."
 ---
 
-Custom Fields attach extra data to an existing entity (a product, customer, order…) through configuration — no hand-written model or migration. What makes them powerful is the **full loop across the stack**: you declare the field in core, render it in the panels with `defineCustomFieldsConfig`, optionally pull in [linked-module](/rc/resources/best-practices/module-links) data with the `link` property, and [type it end-to-end](/rc/resources/best-practices/types) so every SDK call carries it.
+Custom fields attach extra data to a built-in entity such as a product, customer, or order through configuration, with no hand-written model or migration.
 
-This page is the best-practices view. For the full storage-side setup see [Custom Fields](/rc/resources/customization/custom-fields).
+What makes them powerful is the full loop across the stack. You declare the field in core, render it in the panels with `defineCustomFieldsConfig`, optionally pull in [linked-module](/rc/resources/best-practices/module-links) data with the `link` property, and [type it end-to-end](/rc/resources/best-practices/types) so every SDK call carries it.
+
+<Info>
+  This page is the best-practices view. For the full storage-side setup see [Custom Fields](/rc/resources/customization/custom-fields).
+</Info>
 
 ## Reach for a custom field vs a module
 
-The decision is about the **shape and lifecycle** of the data, not its size.
+The decision is about the shape and lifecycle of the data, not its size.
 
 <CardGroup cols={2}>
   <Card title="Use a custom field when…" icon="circle-check">
@@ -21,16 +26,16 @@ The decision is about the **shape and lifecycle** of the data, not its size.
 </CardGroup>
 
 <Warning>
-  Custom Fields is strictly **one row per parent entity**. Forcing a one-to-many or stateful concept into it works until you need a second row or a state transition. If in doubt, model it as a [module](/rc/resources/best-practices/modules).
+  Custom Fields is strictly one row per parent entity. Forcing a one-to-many or stateful concept into it works until you need a second row or a state transition. If in doubt, model it as a [module](/rc/resources/best-practices/modules).
 </Warning>
 
 ## The full loop
 
 ### 1. Declare the field in core
 
-Register the Custom Fields module and describe the field in `medusa-config.ts`. The module generates the side table, the link, and the schema on `db:migrate`:
+Register the Custom Fields module and describe the field in `medusa-config.ts`. The module generates the side table, the link, and the schema on `db:migrate`.
 
-```ts title="medusa-config.ts"
+```ts medusa-config.ts
 {
   resolve: "@mercurjs/core/modules/custom-fields",
   options: {
@@ -43,21 +48,21 @@ Register the Custom Fields module and describe the field in `medusa-config.ts`.
 }
 ```
 
-The value now lives in the module's own `custom_fields` side table — linked to the product, readable alongside it through `query.graph`, and written through `additional_data` on the entity's create/update route. (Filtering products *by* a custom-field value is cross-module and needs the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module), not `query.graph`.)
+The value now lives in the module's own `custom_fields` side table. It is linked to the product, readable alongside it through `query.graph`, and written through `additional_data` on the entity's create/update route. Filtering products by a custom-field value is cross-module and needs the [Index Module](/rc/resources/best-practices/module-links#filtering-by-a-linked-field--the-index-module), not `query.graph`.
 
 <Warning>
-  **Prefer the `custom_fields` link over stuffing values into `metadata`.** `metadata` is an untyped JSON bag with no schema, no queryable columns, and no clean extension point — it turns into a dumping ground. The Custom Fields module gives you a real linked table (`custom_fields.*`) with typed columns you can read and (via the Index Module) filter on, while still being config-only. Reach for `metadata` only for genuinely throwaway, never-queried scratch data.
+  Prefer the `custom_fields` link over stuffing values into `metadata`. `metadata` is an untyped JSON bag with no schema, no queryable columns, and no clean extension point. It turns into a dumping ground. The Custom Fields module gives you a real linked table (`custom_fields.*`) with typed columns you can read and, via the Index Module, filter on, while still being config-only. Reach for `metadata` only for genuinely throwaway, never-queried scratch data.
 </Warning>
 
 <Tip>
-  Mutations still go through workflows. The panel submits custom-field values under **`additional_data`** on the parent's create/update route — and `additional_data` is exactly what [workflow hooks](/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow) receive. So the same values you enter in the panel can be consumed by a `productsCreated` / `productUpdated` hook to run follow-up logic, persist to the linked table, or trigger side effects. Never write a custom-field value with a direct route write.
+  Mutations still go through workflows. The panel submits custom-field values under `additional_data` on the parent's create/update route, and `additional_data` is exactly what [workflow hooks](/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow) receive. So the same values you enter in the panel can be consumed by a `productsCreated` / `productUpdated` hook to run follow-up logic, persist to the linked table, or trigger side effects. Never write a custom-field value with a direct route write.
 </Tip>
 
 ### 2. Render it in the panel with `defineCustomFieldsConfig`
 
-Drop one file per model under the panel's `src/custom-fields/`. A single config contributes **form fields** (edit drawer, submitted under `additional_data`), read-only **displays** (detail sections), and **list columns**. Declare `link: "custom_fields"` so the module's data is fetched alongside the product and available to your fields and displays:
+Drop one file per model under the panel's `src/custom-fields/`. A single config contributes form fields (edit drawer, submitted under `additional_data`), read-only displays (detail sections), and list columns. Declare `link: "custom_fields"` so the module's data is fetched alongside the product and available to your fields and displays.
 
-```tsx title="apps/vendor/src/custom-fields/product.tsx"
+```tsx apps/vendor/src/custom-fields/product.tsx
 import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
 import { createFormHelper } from "@mercurjs/dashboard-shared"
 
@@ -67,7 +72,7 @@ const form = createFormHelper<ProductWithCustomFields>()
 
 export default defineCustomFieldsConfig({
   model: "product",
-  link: "custom_fields", // fetch custom_fields.* with the product — no hand-written field list
+  link: "custom_fields", // fetch custom_fields.* with the product, no hand-written field list
   forms: [
     {
       zone: "edit",
@@ -87,7 +92,7 @@ export default defineCustomFieldsConfig({
       fields: [
         {
           id: "is_featured",
-          component: ({ data }) => (data.custom_fields?.is_featured ? "Featured" : "—"),
+          component: ({ data }) => (data.custom_fields?.is_featured ? "Featured" : "-"),
         },
       ],
     },
@@ -96,23 +101,23 @@ export default defineCustomFieldsConfig({
 ```
 
 <Note>
-  The `zone` values are typed — the panel's codegen scans the host `<FormExtensionZone>` / `<DisplayExtensionZone>` usages and emits the valid zones per model into `extension-targets.d.ts`. `zone: "nope"` fails `tsc`. You don't hand-maintain that list.
+  The `zone` values are typed. The panel's codegen scans the host `<FormExtensionZone>` / `<DisplayExtensionZone>` usages and emits the valid zones per model into `extension-targets.d.ts`. `zone: "nope"` fails `tsc`. You don't hand-maintain that list.
 </Note>
 
 The `displays` fields follow an add / replace / remove convention keyed by `id`:
 
-- **unknown id** → appends a new read-only row,
-- **built-in id + component** → replaces that field's render,
-- **built-in id + `component: null`** → hides the field.
+- **Unknown id:** appends a new read-only row.
+- **Built-in id with component:** replaces that field's render.
+- **Built-in id with `component: null`:** hides the field.
 
 ## The extension API `link` property
 
-A custom-field config can also declare **module links to fetch alongside the entity** with the `link` property. This is how you surface data from a linked module (e.g. a `brand`) in the product's columns and displays without wiring a second query:
+A custom-field config can also declare module links to fetch alongside the entity with the `link` property. This is how you surface data from a linked module such as a `brand` in the product's columns and displays without wiring a second query.
 
-```tsx title="apps/vendor/src/custom-fields/product.tsx"
+```tsx apps/vendor/src/custom-fields/product.tsx
 export default defineCustomFieldsConfig({
   model: "product",
-  link: "brand", // fetch brand.* with each product — one or an array of links
+  link: "brand", // fetch brand.* with each product, one or an array of links
   list: {
     columns: [
       // linked data is available on the row, no extra fetch
@@ -129,18 +134,18 @@ export default defineCustomFieldsConfig({
 ```
 
 <Tip>
-  `link` replaces the old "remember to add the fields to every fetch" chore. Under the hood the panel reads the registry's links (`getLinks(model)`) and merges them into the built-in list, detail, and edit fetches with `withLinkFields(fields, links)` (`+brand.*`) — so the linked data is present in **all three** places automatically. There's no `extendFields`: declaring the `link` is what makes its fields available to both columns and displays.
+  `link` replaces the old "remember to add the fields to every fetch" chore. Under the hood the panel reads the registry's links (`getLinks(model)`) and merges them into the built-in list, detail, and edit fetches with `withLinkFields(fields, links)` (`+brand.*`), so the linked data is present in all three places automatically. There's no `extendFields`: declaring the `link` is what makes its fields available to both columns and displays.
 </Tip>
 
 <Warning>
-  The link must actually exist as a [module link](/rc/resources/best-practices/module-links) and, in the vendor panel, respect the curated-field constraint — the fetch derived from `link` runs against the vendor product query, which rejects arbitrary `*`-relation overrides. Declare the link, then reference only its real fields.
+  The link must actually exist as a [module link](/rc/resources/best-practices/module-links) and, in the vendor panel, respect the curated-field constraint. The fetch derived from `link` runs against the vendor product query, which rejects arbitrary `*`-relation overrides. Declare the link, then reference only its real fields.
 </Warning>
 
 ## 3. Type it end-to-end
 
-The rendered value comes back from the API, but the panel's `ProductDTO` doesn't know about `is_featured` yet. Close the gap with a one-line declaration-merging `.d.ts` so **every** SDK endpoint is typed — no per-call casts:
+The rendered value comes back from the API, but the panel's `ProductDTO` doesn't know about `is_featured` yet. Close the gap with a one-line declaration-merging `.d.ts` so every SDK endpoint is typed, with no per-call casts.
 
-```ts title="apps/vendor/src/types/custom-fields.d.ts"
+```ts apps/vendor/src/types/custom-fields.d.ts
 import "@medusajs/types"
 
 declare module "@medusajs/types" {
@@ -150,92 +155,111 @@ declare module "@medusajs/types" {
 }
 ```
 
-Now `product.custom_fields?.is_featured` is typed on every `sdk.vendor.products.*` response — the runtime value is delivered by the `link` / registry merge above, not a hand-added `+field.*` (the vendor product query rejects arbitrary `*`-relation overrides). The mechanics — why merging into the upstream interface flows through — are covered in [Types & augmentation](/rc/resources/best-practices/types#the-scenario-a-custom-field-typed-end-to-end).
+Now `product.custom_fields?.is_featured` is typed on every `sdk.vendor.products.*` response. The runtime value is delivered by the `link` / registry merge above, not a hand-added `+field.*` (the vendor product query rejects arbitrary `*`-relation overrides). The mechanics, why merging into the upstream interface flows through, are covered in [Types & augmentation](/rc/resources/best-practices/types#the-scenario-a-custom-field-typed-end-to-end).
 
 ## The full override flow: `additional_data` → route → workflow hook
 
-Rendering and typing a field is only half the story. The reason custom fields submit under **`additional_data`** is that it's the framework's built-in extension channel: values entered in the panel travel through the entity's existing API route into the workflow's **hooks**, where your own code consumes them — **without forking the route or the workflow**. This is exactly what a Mercur override looks like.
+Rendering and typing a field is only half the story. The reason custom fields submit under `additional_data` is that it's the framework's built-in extension channel: values entered in the panel travel through the entity's existing API route into the workflow's hooks, where your own code consumes them, without forking the route or the workflow. This is exactly what a Mercur override looks like.
 
 The flow has three links in the chain.
 
-### 1. The panel submits under `additional_data`
-
-You already did this — a `defineCustomFieldsConfig` `edit`/`create` field is submitted as `additional_data.<field>` on the entity's create/update request. Nothing else to wire on the frontend.
+<Steps>
+  <Step title="The panel submits under additional_data">
+    You already did this. A `defineCustomFieldsConfig` `edit`/`create` field is submitted as `additional_data.<field>` on the entity's create/update request. Nothing else to wire on the frontend.
+  </Step>
 
-### 2. The route accepts it via `additionalDataValidator`
+  <Step title="The route accepts it via additionalDataValidator">
+    The vendor/admin product routes accept an `additional_data` body param, but each key must be declared or it's rejected. Register the allowed keys with `additionalDataValidator` in a middleware, with no need to touch the route handler.
 
-The vendor/admin product routes accept an `additional_data` body param, but each key must be **declared** or it's rejected. Register the allowed keys with `additionalDataValidator` in a middleware — no need to touch the route handler:
+    ```ts src/api/middlewares.ts
+    import { defineMiddlewares } from "@medusajs/framework/http"
+    import { z } from "@medusajs/framework/zod"
 
-```ts title="src/api/middlewares.ts"
-import { defineMiddlewares } from "@medusajs/framework/http"
-import { z } from "@medusajs/framework/zod"
-
-export default defineMiddlewares({
-  routes: [
-    {
-      method: "POST",
-      matcher: "/vendor/products",
-      additionalDataValidator: {
-        brand_id: z.string().optional(),
+    export default defineMiddlewares({
+      routes: [
+        {
+          method: "POST",
+          matcher: "/vendor/products",
+          additionalDataValidator: {
+            brand_id: z.string().optional(),
+          },
+        },
+      ],
+    })
+    ```
+  </Step>
+
+  <Step title="A workflow hook consumes it">
+    Mercur's product create workflow is `createProductsWorkflow` from `@mercurjs/core/workflows` (id `mercur-create-products`). It is what the vendor route runs, and it exposes a `productsCreated` hook that runs after the products are created, receiving both the created records and your `additional_data`. Consume it to perform the real work, here [linking](/rc/resources/best-practices/module-links) the product to a brand, with a compensation function so a failure rolls the link back.
+
+    ```ts src/workflows/hooks/created-product.ts
+    import { createProductsWorkflow } from "@mercurjs/core/workflows"
+    import { StepResponse } from "@medusajs/framework/workflows-sdk"
+    import { Modules } from "@medusajs/framework/utils"
+    import { LinkDefinition } from "@medusajs/framework/types"
+    import { BRAND_MODULE } from "../../modules/brand"
+
+    createProductsWorkflow.hooks.productsCreated(
+      async ({ products, additional_data }, { container }) => {
+        if (!additional_data?.brand_id) {
+          return new StepResponse([], [])
+        }
+
+        const link = container.resolve("link")
+        const links: LinkDefinition[] = products.map((product) => ({
+          [Modules.PRODUCT]: { product_id: product.id },
+          [BRAND_MODULE]: { brand_id: additional_data.brand_id },
+        }))
+
+        await link.create(links)
+        return new StepResponse(links, links)
       },
-    },
-  ],
-})
-```
-
-### 3. A workflow hook consumes it
-
-Mercur's product create workflow — `createProductsWorkflow` from `@mercurjs/core/workflows` (id `mercur-create-products`) — is what the vendor route runs, and it exposes a `productsCreated` **hook** that runs after the products are created, receiving both the created records and your `additional_data`. Consume it to perform the real work — here, [linking](/rc/resources/best-practices/module-links) the product to a brand — with a compensation function so a failure rolls the link back:
-
-```ts title="src/workflows/hooks/created-product.ts"
-import { createProductsWorkflow } from "@mercurjs/core/workflows"
-import { StepResponse } from "@medusajs/framework/workflows-sdk"
-import { Modules } from "@medusajs/framework/utils"
-import { LinkDefinition } from "@medusajs/framework/types"
-import { BRAND_MODULE } from "../../modules/brand"
-
-createProductsWorkflow.hooks.productsCreated(
-  async ({ products, additional_data }, { container }) => {
-    if (!additional_data?.brand_id) {
-      return new StepResponse([], [])
-    }
-
-    const link = container.resolve("link")
-    const links: LinkDefinition[] = products.map((product) => ({
-      [Modules.PRODUCT]: { product_id: product.id },
-      [BRAND_MODULE]: { brand_id: additional_data.brand_id },
-    }))
-
-    await link.create(links)
-    return new StepResponse(links, links)
-  },
-  // compensation — undo the links if a later step fails
-  async (links, { container }) => {
-    if (!links?.length) {
-      return
-    }
-    await container.resolve("link").dismiss(links)
-  }
-)
-```
+      // compensation: undo the links if a later step fails
+      async (links, { container }) => {
+        if (!links?.length) {
+          return
+        }
+        await container.resolve("link").dismiss(links)
+      }
+    )
+    ```
+  </Step>
+</Steps>
 
 <Note>
-  Mercur's `createProductsWorkflow` wraps Medusa's stock create-products flow and adds the marketplace layer (seller association, attributes, audit trail). Because it re-exposes the `validate` and `productsCreated` hooks, you extend the **Mercur** flow the same way you would a plain Medusa one — consume its hook, don't fork it.
+  Mercur's `createProductsWorkflow` wraps Medusa's stock create-products flow and adds the marketplace layer (seller association, attributes, audit trail). Because it re-exposes the `validate` and `productsCreated` hooks, you extend the Mercur flow the same way you would a plain Medusa one. Consume its hook, don't fork it.
 </Note>
 
 <Tip>
-  This is the **override pattern** in one sentence: the panel writes to `additional_data`, the route lets it through via `additionalDataValidator`, and a `hooks.<name>` consumer turns it into real behaviour — all additively, without copying or replacing any built-in code. It's how you extend a Mercur (or Medusa) flow instead of forking it. See [Workflows → hooks](/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow).
+  This is the override pattern in one sentence: the panel writes to `additional_data`, the route lets it through via `additionalDataValidator`, and a `hooks.<name>` consumer turns it into real behaviour, all additively, without copying or replacing any built-in code. It's how you extend a Mercur (or Medusa) flow instead of forking it. See [Workflows → hooks](/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow).
 </Tip>
 
 <Warning>
-  The hook runs **inside** the workflow, so its mutation still obeys the [one-mutation-per-step + compensation](/rc/resources/best-practices/workflows#one-mutation-per-step--compensation) rule — always pair `link.create` with a `link.dismiss` compensation. Never do the work in a route handler after the workflow returns; put it in the hook.
+  The hook runs inside the workflow, so its mutation still obeys the [one-mutation-per-step + compensation](/rc/resources/best-practices/workflows#one-mutation-per-step--compensation) rule. Always pair `link.create` with a `link.dismiss` compensation. Never do the work in a route handler after the workflow returns. Put it in the hook.
 </Warning>
 
 ## Checklist
 
-- Data is genuinely one-row-per-parent with no lifecycle → custom field; otherwise a module.
-- Field registered in `medusa-config.ts`; `db:migrate` run; writes go through `additional_data` on a workflow.
-- Panel: one `defineCustomFieldsConfig` per model contributes forms / displays / list, with typed `zone`s.
-- Linked-module data pulled in with the `link` property (not a hand-written second fetch); the link exists and respects vendor field constraints.
+- Data is genuinely one row per parent with no lifecycle: use a custom field, otherwise a module.
+- Field registered in `medusa-config.ts`, `db:migrate` run, writes go through `additional_data` on a workflow.
+- Panel: one `defineCustomFieldsConfig` per model contributes forms, displays, and list, with typed `zone`s.
+- Linked-module data pulled in with the `link` property (not a hand-written second fetch), the link exists and respects vendor field constraints.
 - Extended fields typed once via a `.d.ts` merging into the framework DTO, and requested with `+…*` so they arrive.
-- The override chain is complete: panel → `additional_data` → `additionalDataValidator` declares the key → a `hooks.<name>` consumer does the work inside the workflow, with compensation. No route/workflow forked.
+- The override chain is complete: panel, then `additional_data`, then `additionalDataValidator` declares the key, then a `hooks.<name>` consumer does the work inside the workflow, with compensation. No route or workflow forked.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Module links" href="/rc/resources/best-practices/module-links">
+    Relate modules and fetch linked data alongside an entity.
+  </Card>
+  <Card title="Modules" href="/rc/resources/best-practices/modules">
+    Model data that has its own lifecycle, rows, and routes.
+  </Card>
+  <Card title="Workflows & hooks" href="/rc/resources/best-practices/workflows#hooks--let-others-extend-your-workflow">
+    Extend a built-in flow through its hooks instead of forking it.
+  </Card>
+  <Card title="Types & augmentation" href="/rc/resources/best-practices/types#the-scenario-a-custom-field-typed-end-to-end">
+    Type a custom field end-to-end with declaration merging.
+  </Card>
+</CardGroup>