@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/best-practices/frontend.mdx

@@ -1,24 +1,25 @@
 ---
-title: "Frontend"
-description: "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."
+title: "Frontend Patterns"
+sidebarTitle: "Frontend Patterns"
+description: "Build Admin and Vendor panel UI with the shared design system: @medusajs/ui, custom-field extensions, and new pages, with the correct imports."
 ---
 
-The Admin and Vendor panels share one design system. The three things you'll actually do — style with `@medusajs/ui`, extend built-in screens with **custom fields**, and add **new pages** — all have an established shape and, importantly, a set of **correct imports**. This page is that short list. The full reference is the [UI architecture](/rc/references/panel-extension-api).
+The Admin and Vendor panels share one design system. You do three things with it: style with `@medusajs/ui`, extend built-in screens with custom fields, and add new pages. Each has an established shape and a set of correct imports. This page is that short list. For the full reference, see the [panel extensions reference](/references/panel-extensions/overview).
 
-## Use `@medusajs/ui` — and only it
+## Use @medusajs/ui, and only it
 
-<Warning>
-  Never introduce a second UI library, and never restyle Medusa UI components with custom CSS. Build on the primitives; don't work around them.
-</Warning>
-
-- **Components** come from `@medusajs/ui`, **icons** from `@medusajs/icons`, and colours/spacing/type from Medusa UI **tokens** (`text-ui-fg-*`, `bg-ui-bg-*`, `border-ui-border-*`) — never hex, `rgb()`, or `text-gray-500`.
+Components come from `@medusajs/ui`, icons from `@medusajs/icons`, and colours, spacing, and type from Medusa UI tokens (`text-ui-fg-*`, `bg-ui-bg-*`, `border-ui-border-*`). Never use hex, `rgb()`, or `text-gray-500`.
 
 ```tsx
 import { Container, Heading, Text, Button, Badge, StatusBadge, toast } from "@medusajs/ui"
 import { PencilSquare, Trash, EllipsisHorizontal } from "@medusajs/icons"
 ```
 
-- A **section** is a `Container` with the standard shell — a divided card with a header row:
+<Warning>
+  Never introduce a second UI library, and never restyle Medusa UI components with custom CSS. Build on the primitives. Do not work around them.
+</Warning>
+
+A section is a `Container` with the standard shell: a divided card with a header row.
 
 ```tsx
 <Container className="divide-y p-0">
@@ -34,24 +35,24 @@ import { PencilSquare, Trash, EllipsisHorizontal } from "@medusajs/icons"
 
 ## Extend built-in screens with custom fields
 
-The primary way to customise an existing entity's screens (product, order, customer…) is a **custom-fields config** — one file per model that contributes form fields, table columns, and read-only section fields. See [Custom fields](/rc/resources/best-practices/custom-fields) for the full backend↔frontend loop; here's the frontend surface with the right imports.
+The primary way to customise an existing entity's screens (product, order, customer) is a custom-fields config: one file per model that contributes form fields, table columns, and read-only section fields. See [Custom fields](/rc/resources/best-practices/custom-fields) for the full backend and frontend loop. This section covers the frontend surface with the right imports.
 
-<Note>
-  The two imports you need — and where each lives:
+You need two imports, and each lives in a different package.
 
-  ```tsx
-  import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"   // the config helper
-  import { createFormHelper } from "@mercurjs/dashboard-shared"        // typed form fields (zod)
-  ```
+```tsx
+import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"   // the config helper
+import { createFormHelper } from "@mercurjs/dashboard-shared"        // typed form fields (zod)
+```
 
-  `defineCustomFieldsConfig` is build-time config (SDK, zod-free); `createFormHelper` is the runtime form surface (dashboard-shared). Don't cross them over.
+<Note>
+  `defineCustomFieldsConfig` is build-time config (SDK, zod-free). `createFormHelper` is the runtime form surface (dashboard-shared). Do not cross them over.
 </Note>
 
 ### Add form fields (edit / create)
 
-Contribute inputs into a built-in form `zone`. Values submit under `additional_data`:
+Contribute inputs into a built-in form `zone`. Values submit under `additional_data`.
 
-```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"
 
@@ -77,7 +78,7 @@ export default defineCustomFieldsConfig({
 
 ### Change the list table
 
-Add or override a column (and add bulk actions) on the model's built-in list:
+Add or override a column, and add bulk actions, on the model's built-in list.
 
 ```tsx
 list: {
@@ -87,11 +88,11 @@ list: {
 },
 ```
 
-### Read-only fields in detail sections — e.g. surface (or change) a status
+### Read-only fields in detail sections
 
-`displays` add read-only rows into an existing detail-page section, keyed by `id` (unknown id **adds**, built-in id **replaces**, `component: null` **hides**). A read-only field can render a `StatusBadge`, and a section `action` can trigger a status change through a mutation:
+Use `displays` to add read-only rows into an existing detail-page section, keyed by `id`. An unknown id adds a row, a built-in id replaces one, and `component: null` hides one. A read-only field can render a `StatusBadge`, and a section `action` can trigger a status change through a mutation.
 
-```tsx title="apps/vendor/src/custom-fields/product.tsx"
+```tsx apps/vendor/src/custom-fields/product.tsx
 import { StatusBadge, Button, toast } from "@medusajs/ui"
 
 // inside defineCustomFieldsConfig(...)
@@ -128,14 +129,14 @@ displays: [
 ```
 
 <Tip>
-  Read-only displays are the idiomatic way to expose (and act on) an entity's state — an approval flag, a moderation status, an internal tag — without rebuilding the detail page. The mutation still goes through the typed SDK and rides `additional_data` into a [workflow hook](/rc/resources/best-practices/custom-fields#the-full-override-flow-additional_data--route--workflow-hook), never a direct write.
+  Read-only displays are the idiomatic way to expose an entity's state, such as an approval flag, a moderation status, or an internal tag, and to act on it without rebuilding the detail page. The mutation still goes through the typed SDK and rides `additional_data` into a [workflow hook](/rc/resources/best-practices/custom-fields#the-full-override-flow-additional_data--route--workflow-hook), never a direct write.
 </Tip>
 
 ## Add a new page
 
-A brand-new screen is one file: drop a `page.tsx` under the host app's `src/routes/`. The SDK registers the route from the file path and builds the sidebar entry from an exported `config`.
+A brand-new screen is one file. Drop a `page.tsx` under the host app's `src/routes/`. The SDK registers the route from the file path and builds the sidebar entry from an exported `config`.
 
-```tsx title="apps/vendor/src/routes/reviews/page.tsx"
+```tsx apps/vendor/src/routes/reviews/page.tsx
 import { Container, Heading } from "@medusajs/ui"
 import { Star } from "@medusajs/icons"
 import type { RouteConfig } from "@mercurjs/dashboard-sdk"
@@ -157,12 +158,12 @@ export default function ReviewsPage() {
 ```
 
 <Note>
-  Correct imports for a page: UI from `@medusajs/ui`, icons from `@medusajs/icons`, and the `RouteConfig` **type** from `@mercurjs/dashboard-sdk`. Dynamic segments use brackets — `src/routes/reviews/[id]/page.tsx` → `/reviews/:id`. See [Extending panels](/rc/resources/customization/extending-panels#routing-conventions).
+  Correct imports for a page: UI from `@medusajs/ui`, icons from `@medusajs/icons`, and the `RouteConfig` type from `@mercurjs/dashboard-sdk`. Dynamic segments use brackets: `src/routes/reviews/[id]/page.tsx` maps to `/reviews/:id`. See [Extending panels](/rc/resources/customization/extending-panels#routing-conventions).
 </Note>
 
 ## Compose a full page: layout, table, sections, edit
 
-For a real screen you assemble the same primitives the built-in pages use — all re-exported from `@mercurjs/dashboard-shared`, so you import from **one** place instead of Medusa internals.
+For a real screen you assemble the same primitives the built-in pages use. They are all re-exported from `@mercurjs/dashboard-shared`, so you import from one place instead of Medusa internals.
 
 ```tsx
 import {
@@ -179,11 +180,15 @@ import { Container, Heading, Text, Button, Input, toast } from "@medusajs/ui"
 import { createColumnHelper } from "@tanstack/react-table"
 ```
 
-### Layout + list table
+<Warning>
+  Import these primitives from `@mercurjs/dashboard-shared`, not from deep Medusa dashboard paths like `../../../components/table/data-table`. The shared package is the public, stable surface. Relative Medusa-internal imports are not available to consumer apps and break on upgrade.
+</Warning>
+
+### Layout and list table
 
-Pick a layout — `SingleColumnPage` for lists/simple pages, `TwoColumnPage` for a detail with a sidebar — and mount a `DataTable` inside the standard section shell. Build columns with `createColumnHelper`, wire the table with `useDataTable`, page size 20, and `keepPreviousData` for smooth pagination:
+Pick a layout: `SingleColumnPage` for lists and simple pages, `TwoColumnPage` for a detail with a sidebar. Mount a `DataTable` inside the standard section shell. Build columns with `createColumnHelper`, wire the table with `useDataTable`, use page size 20, and pass `keepPreviousData` for smooth pagination.
 
-```tsx title="apps/vendor/src/routes/reviews/page.tsx"
+```tsx apps/vendor/src/routes/reviews/page.tsx
 const columnHelper = createColumnHelper<Review>()
 
 const columns = [
@@ -216,7 +221,7 @@ export default function ReviewsPage() {
 
 ### General section (label / value rows)
 
-On a detail page, a "general" section is a `Container` header row plus `SectionRow` label/value pairs — the canonical way Medusa renders read-only entity data:
+On a detail page, a "general" section is a `Container` header row plus `SectionRow` label and value pairs. This is the canonical way Medusa renders read-only entity data.
 
 ```tsx
 <Container className="divide-y p-0">
@@ -229,13 +234,13 @@ On a detail page, a "general" section is a `Container` header row plus `SectionR
 </Container>
 ```
 
-For a detail page with a sidebar, wrap sections in `TwoColumnPage` and place them under `TwoColumnPage.Main` / `TwoColumnPage.Sidebar` (each stacked with `gap-y-3`).
+For a detail page with a sidebar, wrap sections in `TwoColumnPage` and place them under `TwoColumnPage.Main` and `TwoColumnPage.Sidebar`, each stacked with `gap-y-3`.
 
 ### Edit page (drawer)
 
-Quick edits live in a routed `RouteDrawer` with `Form` (React Hook Form + Zod). Gate the form until the entity has loaded, and use `useRouteModal().handleSuccess()` to close on save:
+Quick edits live in a routed `RouteDrawer` with `Form` (React Hook Form plus Zod). Gate the form until the entity has loaded, and use `useRouteModal().handleSuccess()` to close on save.
 
-```tsx title="apps/vendor/src/routes/reviews/[id]/edit/page.tsx"
+```tsx apps/vendor/src/routes/reviews/[id]/edit/page.tsx
 export default function EditReviewPage() {
   return (
     <RouteDrawer>
@@ -244,23 +249,19 @@ export default function EditReviewPage() {
           <Heading>Edit review</Heading>
         </RouteDrawer.Title>
       </RouteDrawer.Header>
-      {/* <EditReviewForm /> — RouteDrawer.Form + KeyboundForm, gated on !isPending && !!review */}
+      {/* <EditReviewForm />, RouteDrawer.Form + KeyboundForm, gated on !isPending && !!review */}
     </RouteDrawer>
   )
 }
 ```
 
-<Warning>
-  Import these primitives from `@mercurjs/dashboard-shared`, **not** from deep Medusa dashboard paths like `../../../components/table/data-table`. The shared package is the public, stable surface; relative Medusa-internal imports are not available to consumer apps and break on upgrade.
-</Warning>
-
 ## Data only through the typed SDK
 
 <Warning>
-  Never call `fetch` directly from a page. All HTTP goes through the typed SDK — `sdk.admin.*` in the admin panel, `sdk.vendor.*` in the vendor panel — wrapped in TanStack Query hooks.
+  Never call `fetch` directly from a page. All HTTP goes through the typed SDK (`sdk.admin.*` in the admin panel, `sdk.vendor.*` in the vendor panel), wrapped in TanStack Query hooks.
 </Warning>
 
-```ts title="src/hooks/api/reviews.tsx"
+```ts src/hooks/api/reviews.tsx
 import { useQuery } from "@tanstack/react-query"
 import { sdk } from "../../lib/client"
 import { queryKeysFactory } from "@mercurjs/dashboard-shared"
@@ -274,13 +275,24 @@ export const useReviews = (query?: Record<string, unknown>) =>
   })
 ```
 
-Invalidate `lists()` / `details()` / `detail(id)` in mutations, throw on `isError` so the route `ErrorBoundary` catches it, and show a `Skeleton` while loading.
+Invalidate `lists()`, `details()`, and `detail(id)` in mutations. Throw on `isError` so the route `ErrorBoundary` catches it. Show a `Skeleton` while loading.
 
 ## Checklist for panel work
 
-- Built only from `@medusajs/ui` + `@medusajs/icons`; Medusa UI tokens only, no custom CSS.
-- Extending an existing screen → a `defineCustomFieldsConfig` file (`@mercurjs/dashboard-sdk`) with `createFormHelper` (`@mercurjs/dashboard-shared`); forms submit under `additional_data`.
-- Read-only state (status/flags) surfaced via `displays`; changes go through the typed SDK + a workflow hook, not a direct write.
-- New screen → a `page.tsx` under `src/routes/` with a typed `RouteConfig`; compose it from `SingleColumnPage`/`TwoColumnPage`, `DataTable`, `SectionRow`, and `RouteDrawer` — all imported from `@mercurjs/dashboard-shared`, never Medusa-internal paths.
-- Data via `sdk.admin.*` / `sdk.vendor.*` in TanStack Query hooks; no raw `fetch`; mutations invalidate the right keys.
-- Every visible string translated; every interactive element has a `data-testid`.
+- **UI primitives:** built only from `@medusajs/ui` and `@medusajs/icons`, Medusa UI tokens only, no custom CSS.
+- **Extending a screen:** a `defineCustomFieldsConfig` file (`@mercurjs/dashboard-sdk`) with `createFormHelper` (`@mercurjs/dashboard-shared`). Forms submit under `additional_data`.
+- **Read-only state:** status and flags surfaced via `displays`. Changes go through the typed SDK and a workflow hook, not a direct write.
+- **New screen:** a `page.tsx` under `src/routes/` with a typed `RouteConfig`. Compose it from `SingleColumnPage` or `TwoColumnPage`, `DataTable`, `SectionRow`, and `RouteDrawer`, all imported from `@mercurjs/dashboard-shared`, never Medusa-internal paths.
+- **Data:** via `sdk.admin.*` or `sdk.vendor.*` in TanStack Query hooks. No raw `fetch`. Mutations invalidate the right keys.
+- **Strings and test ids:** every visible string translated, every interactive element has a `data-testid`.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Panel extensions reference" href="/references/panel-extensions/overview">
+    The full reference for custom fields, widgets, and new pages.
+  </Card>
+  <Card title="Custom fields" href="/rc/resources/best-practices/custom-fields">
+    The full backend and frontend loop, including the workflow hook.
+  </Card>
+</CardGroup>

package/content/resources/best-practices/module-links.mdx

@@ -1,19 +1,22 @@
 ---
-title: "Module links"
-description: "Relate modules without coupling them — defineLink, the link-direction rule, built-in link steps, and filtering by links."
+title: "How to Link Two Modules"
+sidebarTitle: "Link Modules"
+description: "Relate modules without coupling them using defineLink, the link-direction rule, built-in link steps, and cross-link filtering."
 ---
 
-Modules are isolated: a module never imports another module's service or points a foreign key at another module's table (see [Modules](/rc/resources/best-practices/modules)). Relationships between modules are declared **outside** the modules, as **links**, and read through **Query**. This is what keeps each module independently migratable and upgrade-safe.
+Modules stay isolated, so you relate them with links declared outside the modules and read through Query.
+
+A module never imports another module's service, and it never points a foreign key at another module's table (see [Modules](/rc/resources/best-practices/modules)). You declare relationships between modules **outside** the modules, as **links**, and read them through **Query**. This is what keeps each module independently migratable and upgrade-safe.
 
 <Note>
-  Links are a [Medusa framework primitive](https://docs.medusajs.com/learn/fundamentals/module-links). The examples below link a custom **Brand** module to Medusa's built-in **Product** module — the kind of relationship you'd add in your own project.
+  Links are a [Medusa framework primitive](https://docs.medusajs.com/learn/fundamentals/module-links). The examples below link a custom **Brand** module to Medusa's built-in **Product** module. It is the kind of relationship you would add in your own project.
 </Note>
 
-## `defineLink`
+## Define a link with `defineLink`
 
-A link is a small file that associates two linkable data models. Define it once and sync it to the database with a migration.
+A link is a small file that associates two linkable data models. You define it once and sync it to the database with a migration.
 
-```ts title="src/links/product-brand.ts"
+```ts src/links/product-brand.ts
 import { defineLink } from "@medusajs/framework/utils"
 import ProductModule from "@medusajs/medusa/product"
 import BrandModule from "../modules/brand"
@@ -26,13 +29,13 @@ export default defineLink(
 
 After adding or changing a link, generate and run the migration so the link table exists:
 
-```bash
+```bash Terminal
 npx medusa db:migrate
 ```
 
-Once linked, you read across the boundary with Query — never by calling the other module's service:
+Once linked, you read across the boundary with Query, never by calling the other module's service:
 
-```ts
+```ts Read across the link with Query
 const { data: products } = await query.graph({
   entity: "product",
   fields: ["id", "title", "brand.*"], // follows the product ↔ brand link
@@ -41,14 +44,14 @@ const { data: products } = await query.graph({
 
 ## The link-direction rule
 
-The **order of arguments to `defineLink` is meaningful** and cardinality is controlled with `isList`. Read it left-to-right as "the left model links to the right model".
+The order of arguments to `defineLink` is meaningful, and you control cardinality with `isList`. Read it left-to-right as "the left model links to the right model".
 
-- `defineLink(A.linkable.a, B.linkable.b)` — one `a` ↔ one `b`.
-- Wrap a side in `{ linkable, isList: true }` to make it the "many" side.
+- **`defineLink(A.linkable.a, B.linkable.b)`:** one `a` links to one `b`.
+- **`isList: true`:** wrap a side in `{ linkable, isList: true }` to make it the "many" side.
 
 If one brand has many products but each product belongs to a single brand, mark the **product** side as the list:
 
-```ts title="src/links/product-brand.ts — one brand, many products"
+```ts src/links/product-brand.ts
 import { defineLink } from "@medusajs/framework/utils"
 import ProductModule from "@medusajs/medusa/product"
 import BrandModule from "../modules/brand"
@@ -62,9 +65,9 @@ export default defineLink(
 )
 ```
 
-For a many-to-many relationship (a product can carry many brands *and* a brand spans many products) mark both sides as lists and pin an explicit table name:
+For a many-to-many relationship, where a product can carry many brands and a brand spans many products, mark both sides as lists and pin an explicit table name:
 
-```ts title="src/links/product-brand.ts — many-to-many"
+```ts src/links/product-brand.ts
 export default defineLink(
   { linkable: ProductModule.linkable.product, isList: true },
   { linkable: BrandModule.linkable.brand, isList: true },
@@ -77,19 +80,19 @@ export default defineLink(
 ```
 
 <Warning>
-  Direction determines the generated relation names and the shape of the link table. Getting it backwards produces a link that "works" but exposes the wrong nesting (`brand.products` vs `product.brands`) and is painful to migrate away from. Decide the natural reading direction first, then set `isList` on the many side(s).
+  Direction determines the generated relation names and the shape of the link table. Getting it backwards produces a link that "works" but exposes the wrong nesting (`brand.products` vs `product.brands`), and it is painful to migrate away from. Decide the natural reading direction first, then set `isList` on the many side or sides.
 </Warning>
 
-## Built-in link steps — create links inside workflows
+## Create links inside workflows
 
-Links are **data**, so creating or removing one is a mutation and must happen inside a [workflow](/rc/resources/best-practices/workflows) through the built-in link steps — never by writing to the link table directly.
+Links are **data**, so creating or removing one is a mutation. It must happen inside a [workflow](/rc/resources/best-practices/workflows) through the built-in link steps. Never write to the link table directly.
 
-- `createRemoteLinkStep` — create links (and it compensates by removing them on failure).
-- `dismissRemoteLinkStep` — remove links.
+- **`createRemoteLinkStep`:** creates links, and compensates by removing them on failure.
+- **`dismissRemoteLinkStep`:** removes links.
 
 Build the link definitions with `transform` (never inline logic in the composition function), then pass them to the step. Each entry names the two modules and the ids to associate:
 
-```ts title="Linking a product to a brand inside a workflow"
+```ts Linking a product to a brand inside a workflow
 import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
 import { Modules } from "@medusajs/framework/utils"
 import { LinkDefinition } from "@medusajs/framework/types"
@@ -116,42 +119,53 @@ createRemoteLinkStep(productBrandLinks)
 
 This is the distinction that trips people up:
 
-- **Reading** linked data — fetching `brand.*` alongside a product — works with `query.graph`. Query aggregates the two modules' data to build the result.
-- **Filtering** by a linked module's field — "give me products *where* `brand.id = X`" — does **not** work with `query.graph`.
+- **Reading** linked data (fetching `brand.*` alongside a product) works with `query.graph`. Query aggregates the two modules' data to build the result.
+- **Filtering** by a linked module's field ("give me products *where* `brand.id = X`") does **not** work with `query.graph`.
 
 <Warning>
-  `query.graph` **cannot filter by a linked (cross-module) field.** Because modules are isolated and Query aggregates their data after the fact, there's no join to filter on. Passing `filters: { brand: { id } }` to `query.graph` will not scope products by brand.
+  `query.graph` cannot filter by a linked (cross-module) field. Because modules are isolated and Query aggregates their data after the fact, there is no join to filter on. Passing `filters: { brand: { id } }` to `query.graph` will not scope products by brand.
 </Warning>
 
-You can still filter by a field that lives on the entity's **own** module (a plain column like `product.status` or `offer.seller_id`) — that's a normal `query.graph` filter. It's only *linked-module* fields that need a different tool.
+You can still filter by a field that lives on the entity's **own** module, a plain column such as `product.status` or `offer.seller_id`. That is a normal `query.graph` filter. Only *linked-module* fields need a different tool.
 
-### Filtering by a linked field — the Index Module
+### Filter by a linked field with the Index Module
 
 Cross-module filtering is what the [Index Module](https://docs.medusajs.com/learn/fundamentals/module-links/index-module) (`@medusajs/index`) exists for. It ingests data models into a single relational store on startup, so you can filter one entity by another's fields. Install it, make sure both models are ingested, and query with `query.index` instead of `query.graph`:
 
-```ts title="Filter products by their linked brand — query.index, not query.graph"
+```ts Filter products by their linked brand with query.index
 const { data: products, metadata } = await query.index({
   entity: "product",
   fields: ["id", "title", "brand.name"],
   filters: {
     brand: {
-      id: brandId, // ✅ cross-module filter — resolved by the Index Module
+      id: brandId, // ✅ cross-module filter, resolved by the Index Module
     },
   },
 })
 ```
 
 <Note>
-  By default Medusa ingests only `Product`, `ProductVariant`, `Price`, `PriceSet`, and `SalesChannel`. To filter products by a **custom** module like Brand, you must [ingest that model](https://docs.medusajs.com/learn/fundamentals/module-links/index-module#how-to-ingest-custom-data-models) into the Index Module first. The Index Module is still marked experimental, though it powers filtering in the Medusa Admin.
+  By default Medusa ingests only `Product`, `ProductVariant`, `Price`, `PriceSet`, and `SalesChannel`. To filter products by a **custom** module such as Brand, you must [ingest that model](https://docs.medusajs.com/learn/fundamentals/module-links/index-module#how-to-ingest-custom-data-models) into the Index Module first. The Index Module is still marked experimental, though it powers filtering in the Medusa Admin.
 </Note>
 
-`query.index` takes the same shape as `query.graph` (entity, fields, filters, pagination), so a route handler can forward `req.filterableFields` to it exactly the same way — the only change is `graph` → `index`.
+`query.index` takes the same shape as `query.graph` (entity, fields, filters, pagination), so a route handler can forward `req.filterableFields` to it exactly the same way. The only change is `graph` to `index`.
 
 ## Checklist for a link
 
 - Declared in its own file under `src/links/`, using `defineLink`.
-- Argument order reflects the natural reading direction; `isList` set on the many side(s).
+- Argument order reflects the natural reading direction, with `isList` set on the many side or sides.
 - Migration generated and run (`medusa db:migrate`).
 - Cross-module **reads** go through `query.graph`, never a service-to-service call.
-- Cross-module **filters** go through `query.index` (Index Module, with the model ingested) — `query.graph` can't filter by a linked field.
-- Links are created/removed only inside workflows via `createRemoteLinkStep` / `dismissRemoteLinkStep`.
+- Cross-module **filters** go through `query.index` (Index Module, with the model ingested). `query.graph` cannot filter by a linked field.
+- Links are created and removed only inside workflows via `createRemoteLinkStep` and `dismissRemoteLinkStep`.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Modules" href="/rc/resources/best-practices/modules">
+    Keep modules isolated so links stay the only boundary between them.
+  </Card>
+  <Card title="Workflows" href="/rc/resources/best-practices/workflows">
+    Create and remove links inside compensating workflow steps.
+  </Card>
+</CardGroup>

package/content/resources/best-practices/modules.mdx

@@ -1,19 +1,24 @@
 ---
-title: "Modules"
-description: "Keep modules thin — data access and CRUD only. Naming, decorators, and what must never live in a module service."
+title: "How to Create a Custom Module"
+sidebarTitle: "Create a Module"
+description: "Keep a module thin: it owns one domain's data and its CRUD, with no orchestration, events, or cross-module calls."
 ---
 
-A module is the lowest layer of the [architecture](/rc/resources/best-practices/overview): it owns exactly one domain's data and nothing else. Modules are isolated — they never reach into another module, never orchestrate a business operation, and never react to events. All of that lives one layer up, in [workflows](/rc/resources/best-practices/workflows).
+A module is the lowest layer of the [architecture](/rc/resources/best-practices/overview). It owns exactly one domain's data and nothing else.
+
+Modules are isolated. They never reach into another module, never orchestrate a business operation, and never react to events. All of that lives one layer up, in [workflows](/rc/resources/best-practices/workflows).
 
 <Note>
-  A Mercur module is a standard [Medusa module](https://docs.medusajs.com/learn/fundamentals/modules). The examples below build a small **Brand** module — the kind of custom module you'd add to your own project alongside the built-in ones — so the rules stand on their own rather than relying on Mercur internals.
+  A Mercur module is a standard [Medusa module](https://docs.medusajs.com/learn/fundamentals/modules). The examples below build a small **Brand** module. It is the kind of custom module you add to your own project alongside the built-in ones, so the rules stand on their own rather than relying on Mercur internals.
 </Note>
 
 ## Thin CRUD only
 
-A module service exists to read and write its own tables. Extend `MedusaService({ ...models })` and you get typed `list`, `listAndCount`, `retrieve`, `create`, `update`, and `delete` methods for every model for free — use them.
+A module service exists to read and write its own tables. Extend `MedusaService({ ...models })` and you get typed `list`, `listAndCount`, `retrieve`, `create`, `update`, and `delete` methods for every model for free. Use them.
+
+Define the model with plain columns.
 
-```ts title="src/modules/brand/models/brand.ts"
+```ts src/modules/brand/models/brand.ts
 import { model } from "@medusajs/framework/utils"
 
 export const Brand = model.define("brand", {
@@ -22,7 +27,9 @@ export const Brand = model.define("brand", {
 })
 ```
 
-```ts title="src/modules/brand/service.ts"
+Extend `MedusaService` to get the generated CRUD methods.
+
+```ts src/modules/brand/service.ts
 import { MedusaService } from "@medusajs/framework/utils"
 import { Brand } from "./models/brand"
 
@@ -36,9 +43,9 @@ class BrandModuleService extends MedusaService({
 export default BrandModuleService
 ```
 
-Only add a custom method when the logic is **about this module's own data** and can't be expressed with the generated methods — for example, a specialised query. When you do, use Medusa's DI decorators so the method runs in the ambient context:
+Add a custom method only when the logic is about this module's own data and can't be expressed with the generated methods, such as a specialised query. When you do, use Medusa's DI decorators so the method runs in the ambient context.
 
-```ts title="A justified custom method — still single-module"
+```ts src/modules/brand/service.ts
 class BrandModuleService extends MedusaService({ Brand }) {
   @InjectManager()
   async listActiveBrands(
@@ -51,14 +58,16 @@ class BrandModuleService extends MedusaService({ Brand }) {
 ```
 
 <Warning>
-  **What must never live in a module service:** business orchestration, calls to another module's service, event emission, HTTP concerns, or anything that mutates data outside this module. If a method needs a second module's data or writes across a boundary, it belongs in a [workflow](/rc/resources/best-practices/workflows), not here. See the [logic-placement cheat sheet](/rc/resources/best-practices/overview#logic-placement-cheat-sheet).
+  Some logic must never live in a module service: business orchestration, calls to another module's service, event emission, HTTP concerns, or anything that mutates data outside this module. If a method needs a second module's data or writes across a boundary, it belongs in a [workflow](/rc/resources/best-practices/workflows), not here. See the [logic-placement cheat sheet](/rc/resources/best-practices/overview#logic-placement-cheat-sheet).
 </Warning>
 
 ## Naming
 
+Follow four conventions so the module reads like the built-in ones.
+
 - **Register the module by a stable id constant.** Export the module id and register the service against it:
 
-  ```ts title="src/modules/brand/index.ts"
+  ```ts src/modules/brand/index.ts
   import { Module } from "@medusajs/framework/utils"
   import BrandModuleService from "./service"
 
@@ -70,14 +79,14 @@ class BrandModuleService extends MedusaService({ Brand }) {
   ```
 
   <Tip>
-    Mercur's own modules follow the same pattern but read their id from the shared `MercurModules` enum in `@mercurjs/types` (e.g. `Module(MercurModules.SELLER, …)`). For a project-local module, a single exported constant like `BRAND_MODULE` is enough — just never inline the raw string in more than one place.
+    Mercur's own modules follow the same pattern but read their id from the shared `MercurModules` enum in `@mercurjs/types` (e.g. `Module(MercurModules.SELLER, …)`). For a project-local module, a single exported constant such as `BRAND_MODULE` is enough. Just never inline the raw string in more than one place.
   </Tip>
 
-- **Methods are `camelCase` and model-suffixed.** Medusa generates `listBrands`, `createBrands`, `retrieveBrand` — match that casing and pluralisation when you add or override methods. Private helpers end with a trailing underscore (`computeBrandStats_`).
-- **Models are lowercase-defined, referenced by their key.** `model.define("brand", { ... })`; the object key you pass to `MedusaService` (`Brand`) is what drives the generated method names.
-- **Types live next to the module (or in a shared types package).** Export DTOs like `BrandDTO` and import them; never redeclare a model's shape ad hoc. See [Types & augmentation](/rc/resources/best-practices/types).
+- **Methods are `camelCase` and model-suffixed.** Medusa generates `listBrands`, `createBrands`, and `retrieveBrand`. Match that casing and pluralisation when you add or override methods. Private helpers end with a trailing underscore (`computeBrandStats_`).
+- **Models are lowercase-defined, referenced by their key.** `model.define("brand", { ... })`. The object key you pass to `MedusaService` (`Brand`) is what drives the generated method names.
+- **Types live next to the module, or in a shared types package.** Export DTOs such as `BrandDTO` and import them. Never redeclare a model's shape ad hoc. See [Types & augmentation](/rc/resources/best-practices/types).
 
-## Do not call `.linkable()` — links are declared separately
+## Do not call `.linkable()`: links are declared separately
 
 It is tempting to relate two modules by pointing a model at another module's table. Don't. A module model must not reference another module's data, and you should not wire relationships inside the model definition.
 
@@ -85,9 +94,9 @@ It is tempting to relate two modules by pointing a model at another module's tab
   Cross-module relationships are declared **outside** the modules, with `defineLink`, and read through **Query**. A module never imports another module's `.linkable` shape to build a foreign key into it. Keeping models link-free is what lets modules stay independently migratable and upgrade-safe.
 </Warning>
 
-Define the relationship as its own link file instead — covered in full on [Module links](/rc/resources/best-practices/module-links):
+Define the relationship as its own link file instead. This is covered in full on [Module links](/rc/resources/best-practices/module-links).
 
-```ts title="Relationship declared as a link, not inside the model"
+```ts Relationship declared as a link, not inside the model
 import { defineLink } from "@medusajs/framework/utils"
 import ProductModule from "@medusajs/medusa/product"
 import BrandModule from "../modules/brand"
@@ -98,9 +107,9 @@ export default defineLink(
 )
 ```
 
-The model itself stays flat — plain columns, no relations pointing at other modules:
+The model itself stays flat: plain columns, no relations pointing at other modules.
 
-```ts title="src/modules/brand/models/brand.ts"
+```ts src/modules/brand/models/brand.ts
 export const Brand = model.define("brand", {
   id: model.id().primaryKey(),
   name: model.text(),
@@ -111,7 +120,7 @@ export const Brand = model.define("brand", {
 
 ## Decorators
 
-Custom service methods that touch the database use Medusa's dependency-injection decorators so they participate in the ambient transaction and shared context:
+Custom service methods that touch the database use Medusa's dependency-injection decorators so they participate in the ambient transaction and shared context.
 
 | Decorator | Use it on | Purpose |
 | --- | --- | --- |
@@ -119,7 +128,7 @@ Custom service methods that touch the database use Medusa's dependency-injection
 | `@InjectTransactionManager()` | Write methods | Runs the method inside a transaction, enabling rollback. |
 | `@MedusaContext()` | The trailing `sharedContext` parameter | Threads the request/transaction context through the call. |
 
-```ts title="Decorator pattern for a custom write"
+```ts Decorator pattern for a custom write
 @InjectTransactionManager()
 async deactivateBrand(
   id: string,
@@ -130,15 +139,32 @@ async deactivateBrand(
 ```
 
 <Tip>
-  If you don't need a custom method, don't write one. The generated `MedusaService` methods already carry the right decorators and transaction behaviour — reaching for them first keeps modules thin by default.
+  If you don't need a custom method, don't write one. The generated `MedusaService` methods already carry the right decorators and transaction behaviour. Reaching for them first keeps modules thin by default.
 </Tip>
 
 ## Checklist for a module
 
-- Extends `MedusaService({ ...models })`; leans on generated CRUD.
+- Extends `MedusaService({ ...models })` and leans on generated CRUD.
 - Registered with `Module(BRAND_MODULE, { service })` against a stable id.
 - No import of, or call into, any other module's service.
-- Models are flat — no `.linkable()` wiring, no cross-module foreign keys.
-- Custom methods use `@InjectManager` / `@InjectTransactionManager` + `@MedusaContext`.
+- Models are flat: no `.linkable()` wiring, no cross-module foreign keys.
+- Custom methods use `@InjectManager` / `@InjectTransactionManager` plus `@MedusaContext`.
 - DTOs are exported and imported, never redeclared inline.
-- No orchestration, no events, no HTTP — those live in workflows and routes.
+- No orchestration, no events, no HTTP. Those live in workflows and routes.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Workflows" href="/rc/resources/best-practices/workflows">
+    Orchestrate business operations across modules, with compensation on failure.
+  </Card>
+  <Card title="Module links" href="/rc/resources/best-practices/module-links">
+    Relate two modules with `defineLink` and read the relationship through Query.
+  </Card>
+  <Card title="Types & augmentation" href="/rc/resources/best-practices/types">
+    Export DTOs and share a model's shape instead of redeclaring it inline.
+  </Card>
+  <Card title="Best practices overview" href="/rc/resources/best-practices/overview">
+    See the layered architecture and the logic-placement cheat sheet.
+  </Card>
+</CardGroup>