Writing Medusa TSDocs
Adds TypeDoc (TSDoc) comments to Medusa TypeScript source files. Follows TypeDoc conventions and uses custom tags defined in www/utils/packages/typedoc-config/tsdoc.json.
Constraints
CRITICAL: Violating these produces incorrect or broken documentation.
- Never document unexported items — only
exported interfaces, types, functions, classes
- Never add TSDocs to test files — skip
*.spec.ts, *.test.ts, __tests__/
- Never fabricate
@since version numbers — only use the version passed in the prompt
- Never remove or modify existing TSDocs — only add where missing
- Never modify logic — only add/edit comment blocks
- For Medusa-specific custom tags, only use those defined in
tsdoc.json: @expandable, @featureFlag, @since, @apiIgnore, @schema, @tags, @version, @keep, @customNamespace, @namespaceMember
Load Reference Files When Needed
Load the reference file for the file type you're documenting before writing any TSDocs.
| Path pattern |
Load |
packages/core/types/src/http/ |
reference/http-types.md |
packages/medusa/src/api/admin/ or /store/ |
reference/api-routes.md |
packages/design-system/ui/src/components/ |
reference/ui-components.md |
packages/modules/*/src/models/ |
reference/data-models.md |
packages/core/types/src/ (non-http) |
reference/service-interfaces.md |
packages/core/js-sdk/src/ |
reference/service-interfaces.md |
packages/core/utils/src/ (abstract providers) |
reference/service-interfaces.md |
packages/core/workflows-sdk/src/utils/composer/ |
reference/service-interfaces.md |
packages/core/core-flows/src/ (workflows) |
reference/workflows-steps.md |
packages/core/core-flows/src/ (steps) |
reference/workflows-steps.md |
packages/core/utils/src/core-flows/events.ts |
reference/events.md |
Quick Reference
TSDoc block format
/**
* Brief description.
*/
export interface Foo {
/**
* The foo's ID.
*/
id: string
}
Per-type depth guide
| File type |
What to document |
Key Medusa tags |
| HTTP types |
Every exported interface/type + all properties |
@expandable on nested objects |
| API routes |
Exported handlers only (minimal) |
@featureFlag, @since |
| UI components |
Component + all props |
Plain descriptions |
| Data models |
Model + each property |
@since on new items |
| Service interfaces |
Every method in full |
@param, @returns, @example |
| JS SDK |
Every public method |
@param, @returns, @example, @tags |
| Providers |
Class + every abstract method |
@param, @returns, @example |
| Workflow SDK |
Every exported function |
@param, @returns, @example |
| core-flows workflows |
Workflow export + hooks |
@summary, @featureFlag, @since |
| core-flows steps |
Step export + input type |
@featureFlag, @since, @example |
| Events |
Every event constant |
@eventPayload, @featureFlag, @since |
Medusa custom tags (from www/utils/packages/typedoc-config/tsdoc.json)
| Tag |
Kind |
Use when |
@featureFlag <name> |
block |
Export requires a feature flag to be enabled |
@expandable |
modifier |
Nested object expandable in API queries |
@since <version> |
block |
Export was added in this version (prompt-provided only) |
@apiIgnore |
modifier |
Exclude from API docs output |
@tags <name> |
block |
SDK categorization |
@schema |
block |
Custom schema documentation |
@keep |
modifier |
Preserve during doc generation |
@customNamespace |
block |
Assign to custom doc namespace |
Standard TypeDoc/JSDoc tags (@param, @returns, @example, @deprecated, @remarks, etc.) are always allowed.
Common Mistakes
Reference Files
reference/http-types.md - HTTP type interfaces: properties, @expandable
reference/api-routes.md - API routes: @featureFlag, @since, minimal docs
reference/ui-components.md - UI components: component + inline prop pattern
reference/data-models.md - DML models: @since, property descriptions
reference/service-interfaces.md - Methods, SDK, providers, workflow SDK: full JSDoc
reference/workflows-steps.md - core-flows workflows and steps: @summary, hooks, @example
reference/events.md - Event constants: @eventPayload, @featureFlag, @since
1---2name: writing-tsdocs3description: Adds and updates TypeDoc (TSDoc) comments to TypeScript source files in the Medusa codebase. Covers HTTP types, API routes, UI components, data models, service interfaces, JS SDK methods, abstract providers, workflow SDK functions, core-flows workflows and steps, and events. Use when adding TSDoc comments to files in packages/core/types/src/http, packages/medusa/src/api, packages/design-system/ui/src/components, packages/modules/*/src/models, packages/core/types/src, packages/core/js-sdk/src, packages/core/utils/src, packages/core/workflows-sdk/src/utils/composer, packages/core/core-flows/src, or packages/core/utils/src/core-flows/events.ts.4---5
6# Writing Medusa TSDocs
7
8Adds TypeDoc (TSDoc) comments to Medusa TypeScript source files. Follows TypeDoc conventions and uses custom tags defined in `www/utils/packages/typedoc-config/tsdoc.json`.
9
10## Constraints
11
12> **CRITICAL:** Violating these produces incorrect or broken documentation.
13
14- **Never document unexported items** — only `export`ed interfaces, types, functions, classes
15- **Never add TSDocs to test files** — skip `*.spec.ts`, `*.test.ts`, `__tests__/`
16- **Never fabricate `@since` version numbers** — only use the version passed in the prompt
17- **Never remove or modify existing TSDocs** — only add where missing
18- **Never modify logic** — only add/edit comment blocks
19- **For Medusa-specific custom tags**, only use those defined in `tsdoc.json`: `@expandable`, `@featureFlag`, `@since`, `@apiIgnore`, `@schema`, `@tags`, `@version`, `@keep`, `@customNamespace`, `@namespaceMember`
20
21## Load Reference Files When Needed
22
23> **Load the reference file for the file type you're documenting before writing any TSDocs.**
24
25| Path pattern | Load |
26|------|------|
27| `packages/core/types/src/http/` | `reference/http-types.md` |
28| `packages/medusa/src/api/admin/` or `/store/` | `reference/api-routes.md` |
29| `packages/design-system/ui/src/components/` | `reference/ui-components.md` |
30| `packages/modules/*/src/models/` | `reference/data-models.md` |
31| `packages/core/types/src/` (non-http) | `reference/service-interfaces.md` |
32| `packages/core/js-sdk/src/` | `reference/service-interfaces.md` |
33| `packages/core/utils/src/` (abstract providers) | `reference/service-interfaces.md` |
34| `packages/core/workflows-sdk/src/utils/composer/` | `reference/service-interfaces.md` |
35| `packages/core/core-flows/src/` (workflows) | `reference/workflows-steps.md` |
36| `packages/core/core-flows/src/` (steps) | `reference/workflows-steps.md` |
37| `packages/core/utils/src/core-flows/events.ts` | `reference/events.md` |
38
39## Quick Reference
40
41### TSDoc block format
42
43```typescript
44/**
45 * Brief description.
46 */
47export interface Foo {
48 /**
49 * The foo's ID.
50 */
51 id: string
52}
53```
54
55### Per-type depth guide
56
57| File type | What to document | Key Medusa tags |
58|-----------|-----------------|----------|
59| HTTP types | Every exported interface/type + all properties | `@expandable` on nested objects |
60| API routes | Exported handlers only (minimal) | `@featureFlag`, `@since` |
61| UI components | Component + all props | Plain descriptions |
62| Data models | Model + each property | `@since` on new items |
63| Service interfaces | Every method in full | `@param`, `@returns`, `@example` |
64| JS SDK | Every public method | `@param`, `@returns`, `@example`, `@tags` |
65| Providers | Class + every abstract method | `@param`, `@returns`, `@example` |
66| Workflow SDK | Every exported function | `@param`, `@returns`, `@example` |
67| core-flows workflows | Workflow export + hooks | `@summary`, `@featureFlag`, `@since` |
68| core-flows steps | Step export + input type | `@featureFlag`, `@since`, `@example` |
69| Events | Every event constant | `@eventPayload`, `@featureFlag`, `@since` |
70
71### Medusa custom tags (from `www/utils/packages/typedoc-config/tsdoc.json`)
72
73| Tag | Kind | Use when |
74|-----|------|----------|
75| `@featureFlag <name>` | block | Export requires a feature flag to be enabled |
76| `@expandable` | modifier | Nested object expandable in API queries |
77| `@since <version>` | block | Export was added in this version (prompt-provided only) |
78| `@apiIgnore` | modifier | Exclude from API docs output |
79| `@tags <name>` | block | SDK categorization |
80| `@schema` | block | Custom schema documentation |
81| `@keep` | modifier | Preserve during doc generation |
82| `@customNamespace` | block | Assign to custom doc namespace |
83
84Standard TypeDoc/JSDoc tags (`@param`, `@returns`, `@example`, `@deprecated`, `@remarks`, etc.) are always allowed.
85
86## Common Mistakes
87
88- [ ] Documenting unexported or `private` items
89- [ ] Using `@since` without a version being provided in the prompt
90- [ ] Writing property descriptions longer than 2 sentences
91- [ ] Adding `@param`/`@returns` to non-method exports (interfaces, types)
92- [ ] Documenting an `id` field without specifying what resource it belongs to
93
94## Reference Files
95
96```
97reference/http-types.md - HTTP type interfaces: properties, @expandable
98reference/api-routes.md - API routes: @featureFlag, @since, minimal docs
99reference/ui-components.md - UI components: component + inline prop pattern
100reference/data-models.md - DML models: @since, property descriptions
101reference/service-interfaces.md - Methods, SDK, providers, workflow SDK: full JSDoc
102reference/workflows-steps.md - core-flows workflows and steps: @summary, hooks, @example
103reference/events.md - Event constants: @eventPayload, @featureFlag, @since
104```
medusajs