@mercurjs/docs 2.2.0-canary.50 → 2.2.0-canary.53

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

@@ -0,0 +1,286 @@
+---
+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."
+---
+
+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).
+
+## 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`.
+
+```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:
+
+```tsx
+<Container className="divide-y p-0">
+  <div className="flex items-center justify-between px-6 py-4">
+    <Heading level="h2">Details</Heading>
+    <Button size="small" variant="secondary">Edit</Button>
+  </div>
+  <div className="px-6 py-4">
+    <Text size="small" className="text-ui-fg-subtle">Body</Text>
+  </div>
+</Container>
+```
+
+## 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.
+
+<Note>
+  The two imports you need — and where each lives:
+
+  ```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>
+
+### Add form fields (edit / create)
+
+Contribute inputs into a built-in form `zone`. Values submit under `additional_data`:
+
+```tsx title="apps/vendor/src/custom-fields/product.tsx"
+import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
+import { createFormHelper } from "@mercurjs/dashboard-shared"
+
+const form = createFormHelper<{ custom_fields?: { is_featured?: boolean } }>()
+
+export default defineCustomFieldsConfig({
+  model: "product",
+  link: "custom_fields",
+  forms: [
+    {
+      zone: "edit",
+      fields: {
+        is_featured: form.define({
+          validation: form.boolean().optional(),
+          label: "Featured",
+          defaultValue: (data) => Boolean(data?.custom_fields?.is_featured),
+        }),
+      },
+    },
+  ],
+})
+```
+
+### Change the list table
+
+Add or override a column (and add bulk actions) on the model's built-in list:
+
+```tsx
+list: {
+  columns: [
+    { id: "is_featured", header: "Featured", component: ({ row }) => (row.custom_fields?.is_featured ? "★" : "") },
+  ],
+},
+```
+
+### Read-only fields in detail sections — e.g. surface (or change) a status
+
+`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:
+
+```tsx title="apps/vendor/src/custom-fields/product.tsx"
+import { StatusBadge, Button, toast } from "@medusajs/ui"
+
+// inside defineCustomFieldsConfig(...)
+displays: [
+  {
+    zone: "general",
+    fields: [
+      {
+        id: "review_status",
+        component: ({ data }) => (
+          <div className="flex items-center justify-between px-6 py-4">
+            <StatusBadge color={data.custom_fields?.approved ? "green" : "orange"}>
+              {data.custom_fields?.approved ? "Approved" : "Pending"}
+            </StatusBadge>
+            <Button
+              size="small"
+              variant="secondary"
+              onClick={async () => {
+                await sdk.vendor.products.$id.mutate({
+                  $id: data.id,
+                  additional_data: { approved: true },
+                })
+                toast.success("Approved")
+              }}
+            >
+              Approve
+            </Button>
+          </div>
+        ),
+      },
+    ],
+  },
+],
+```
+
+<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.
+</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`.
+
+```tsx title="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"
+
+export const config: RouteConfig = {
+  label: "Reviews",
+  icon: Star,
+}
+
+export default function ReviewsPage() {
+  return (
+    <Container className="divide-y p-0">
+      <div className="px-6 py-4">
+        <Heading>Reviews</Heading>
+      </div>
+    </Container>
+  )
+}
+```
+
+<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).
+</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.
+
+```tsx
+import {
+  SingleColumnPage,
+  TwoColumnPage,
+  DataTable,
+  useDataTable,
+  SectionRow,
+  RouteDrawer,
+  Form,
+  ActionMenu,
+} from "@mercurjs/dashboard-shared"
+import { Container, Heading, Text, Button, Input, toast } from "@medusajs/ui"
+import { createColumnHelper } from "@tanstack/react-table"
+```
+
+### Layout + 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:
+
+```tsx title="apps/vendor/src/routes/reviews/page.tsx"
+const columnHelper = createColumnHelper<Review>()
+
+const columns = [
+  columnHelper.accessor("title", { header: "Title" }),
+  columnHelper.accessor("rating", { header: "Rating" }),
+  columnHelper.display({
+    id: "actions",
+    cell: ({ row }) => (
+      <ActionMenu groups={[{ actions: [{ label: "Edit", to: `${row.original.id}/edit` }] }]} />
+    ),
+  }),
+]
+
+export default function ReviewsPage() {
+  const { reviews = [], count = 0, isLoading } = useReviews()
+  const { table } = useDataTable({ data: reviews, columns, count, pageSize: 20, getRowId: (r) => r.id })
+
+  return (
+    <SingleColumnPage>
+      <Container className="divide-y p-0">
+        <div className="flex items-center justify-between px-6 py-4">
+          <Heading>Reviews</Heading>
+        </div>
+        <DataTable table={table} columns={columns} count={count} pageSize={20} isLoading={isLoading} navigateTo={(row) => row.id} pagination search />
+      </Container>
+    </SingleColumnPage>
+  )
+}
+```
+
+### 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:
+
+```tsx
+<Container className="divide-y p-0">
+  <div className="flex items-center justify-between px-6 py-4">
+    <Heading>{review.title}</Heading>
+    <ActionMenu groups={[{ actions: [{ label: "Edit", to: "edit" }] }]} />
+  </div>
+  <SectionRow title="Rating" value={`${review.rating} / 5`} />
+  <SectionRow title="Status" value={review.approved ? "Approved" : "Pending"} />
+</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`).
+
+### 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:
+
+```tsx title="apps/vendor/src/routes/reviews/[id]/edit/page.tsx"
+export default function EditReviewPage() {
+  return (
+    <RouteDrawer>
+      <RouteDrawer.Header>
+        <RouteDrawer.Title asChild>
+          <Heading>Edit review</Heading>
+        </RouteDrawer.Title>
+      </RouteDrawer.Header>
+      {/* <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.
+</Warning>
+
+```ts title="src/hooks/api/reviews.tsx"
+import { useQuery } from "@tanstack/react-query"
+import { sdk } from "../../lib/client"
+import { queryKeysFactory } from "@mercurjs/dashboard-shared"
+
+const reviewKeys = queryKeysFactory("reviews")
+
+export const useReviews = (query?: Record<string, unknown>) =>
+  useQuery({
+    queryKey: reviewKeys.list(query),
+    queryFn: () => sdk.vendor.reviews.query({ ...query }),
+  })
+```
+
+Invalidate `lists()` / `details()` / `detail(id)` in mutations, throw on `isError` so the route `ErrorBoundary` catches it, and 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`.

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

@@ -0,0 +1,157 @@
+---
+title: "Module links"
+description: "Relate modules without coupling them — defineLink, the link-direction rule, built-in link steps, and filtering by links."
+---
+
+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.
+
+<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.
+</Note>
+
+## `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.
+
+```ts title="src/links/product-brand.ts"
+import { defineLink } from "@medusajs/framework/utils"
+import ProductModule from "@medusajs/medusa/product"
+import BrandModule from "../modules/brand"
+
+export default defineLink(
+  ProductModule.linkable.product,
+  BrandModule.linkable.brand
+)
+```
+
+After adding or changing a link, generate and run the migration so the link table exists:
+
+```bash
+npx medusa db:migrate
+```
+
+Once linked, you read across the boundary with Query — never by calling the other module's service:
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "brand.*"], // follows the product ↔ brand link
+})
+```
+
+## 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".
+
+- `defineLink(A.linkable.a, B.linkable.b)` — one `a` ↔ one `b`.
+- 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"
+import { defineLink } from "@medusajs/framework/utils"
+import ProductModule from "@medusajs/medusa/product"
+import BrandModule from "../modules/brand"
+
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    isList: true,
+  },
+  BrandModule.linkable.brand
+)
+```
+
+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:
+
+```ts title="src/links/product-brand.ts — many-to-many"
+export default defineLink(
+  { linkable: ProductModule.linkable.product, isList: true },
+  { linkable: BrandModule.linkable.brand, isList: true },
+  {
+    database: {
+      table: "product_brand",
+    },
+  }
+)
+```
+
+<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).
+</Warning>
+
+## Built-in link steps — 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.
+
+- `createRemoteLinkStep` — create links (and it compensates by removing them on failure).
+- `dismissRemoteLinkStep` — remove 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"
+import { createRemoteLinkStep } from "@medusajs/medusa/core-flows"
+import { Modules } from "@medusajs/framework/utils"
+import { LinkDefinition } from "@medusajs/framework/types"
+import { BRAND_MODULE } from "../modules/brand"
+
+const productBrandLinks = transform(
+  { productId, brandId },
+  ({ productId, brandId }): LinkDefinition[] => [
+    {
+      [Modules.PRODUCT]: { product_id: productId },
+      [BRAND_MODULE]: { brand_id: brandId },
+    },
+  ]
+)
+
+createRemoteLinkStep(productBrandLinks)
+```
+
+<Tip>
+  Because `createRemoteLinkStep` already knows how to compensate, links created this way are torn down automatically if a later step in the workflow throws. This is the whole reason to link inside a workflow rather than in a route.
+</Tip>
+
+## Reading vs filtering across a link
+
+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`.
+
+<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.
+</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.
+
+### Filtering by a linked field — 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"
+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
+    },
+  },
+})
+```
+
+<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.
+</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`.
+
+## 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).
+- 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`.

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

@@ -0,0 +1,144 @@
+---
+title: "Modules"
+description: "Keep modules thin — data access and CRUD only. Naming, decorators, and what must never live in a module service."
+---
+
+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.
+</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.
+
+```ts title="src/modules/brand/models/brand.ts"
+import { model } from "@medusajs/framework/utils"
+
+export const Brand = model.define("brand", {
+  id: model.id().primaryKey(),
+  name: model.text(),
+})
+```
+
+```ts title="src/modules/brand/service.ts"
+import { MedusaService } from "@medusajs/framework/utils"
+import { Brand } from "./models/brand"
+
+class BrandModuleService extends MedusaService({
+  Brand,
+}) {
+  // Generated for you: listBrands, retrieveBrand, createBrands,
+  // updateBrands, deleteBrands, listAndCountBrands, ...
+}
+
+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:
+
+```ts title="A justified custom method — still single-module"
+class BrandModuleService extends MedusaService({ Brand }) {
+  @InjectManager()
+  async listActiveBrands(
+    filters: FindConfig<BrandDTO> = {},
+    @MedusaContext() sharedContext: Context = {}
+  ): Promise<BrandDTO[]> {
+    return this.listBrands({ ...filters, is_active: true }, {}, sharedContext)
+  }
+}
+```
+
+<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).
+</Warning>
+
+## Naming
+
+- **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"
+  import { Module } from "@medusajs/framework/utils"
+  import BrandModuleService from "./service"
+
+  export const BRAND_MODULE = "brand"
+
+  export default Module(BRAND_MODULE, {
+    service: BrandModuleService,
+  })
+  ```
+
+  <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.
+  </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).
+
+## 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.
+
+<Warning>
+  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):
+
+```ts title="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"
+
+export default defineLink(
+  ProductModule.linkable.product,
+  BrandModule.linkable.brand
+)
+```
+
+The model itself stays flat — plain columns, no relations pointing at other modules:
+
+```ts title="src/modules/brand/models/brand.ts"
+export const Brand = model.define("brand", {
+  id: model.id().primaryKey(),
+  name: model.text(),
+  is_active: model.boolean().default(true),
+  metadata: model.json().nullable(),
+})
+```
+
+## Decorators
+
+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 |
+| --- | --- | --- |
+| `@InjectManager()` | Read methods | Injects the entity manager so the method runs in the current context. |
+| `@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"
+@InjectTransactionManager()
+async deactivateBrand(
+  id: string,
+  @MedusaContext() sharedContext: Context = {}
+): Promise<BrandDTO> {
+  return this.updateBrands({ id, is_active: false }, sharedContext)
+}
+```
+
+<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.
+</Tip>
+
+## Checklist for a module
+
+- Extends `MedusaService({ ...models })`; 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`.
+- DTOs are exported and imported, never redeclared inline.
+- No orchestration, no events, no HTTP — those live in workflows and routes.