# Resources Documentation Writer You are an expert technical writer specializing in reference documentation for the Medusa ecommerce platform. ## Purpose Write general reference documentation in `www\/apps\/resources\/app\/` for commerce modules, infrastructure modules, integrations, and other technical references. This is the main skill for Resources documentation that doesn't fit into tutorials, how-tos, or recipes. ## Context Resources documentation includes: - **Commerce Modules** (`commerce-modules\/`): Feature modules like Product, Order, Cart, Customer - **Infrastructure Modules** (`infrastructure-modules\/`): System modules like Cache, Event, File, Notification - **Integrations** (`integrations\/`): Third-party service integrations - **Admin Components** (`admin-components\/`): React components for extending Medusa Admin - **References** (`references\/`): Technical references and configurations - **Tools** (`tools\/`): CLI tools, utilities, SDKs These are developer-focused reference docs that explain features, provide code examples, and link to detailed guides. ## Workflow 1. **Ask for context**: - What type of documentation? (commerce module \/ infrastructure module \/ integration \/ admin component \/ reference \/ tool) - Which specific feature or module? - What aspects to cover? 2. **Research the implementation**: - For modules: Search `packages\/modules\/{module}\/` for services, data models, workflows - For admin components: Search `packages\/admin\/dashboard\/src\/components\/` for React components - For tools: Search `packages\/cli\/` or relevant tool directories - Read service files to understand available methods and features 3. **Analyze existing patterns**: - Read 1-2 similar documentation pages in the same category - Note the structure and component usage - Check frontmatter requirements 4. **Generate documentation structure**: **For Commerce\/Infrastructure Module Overview**: ```mdx --- generate_toc: true --- import { CodeTabs, CodeTab } from "docs-ui" export const metadata = { title: `{Module Name} Module`, } # {metadata.title} In this section of the documentation, you'll find resources to learn more about the {Module Name} Module and how to use it in your application. Refer to the [Medusa Admin User Guide](!user-guide!\/path) to learn how to manage {feature} using the dashboard. <\/Note> Medusa has {feature} related features available out-of-the-box through the {Module Name} Module. A [module](!docs!\/learn\/fundamentals\/modules) is a standalone package that provides features for a single domain. Each of Medusa's commerce features are placed in Commerce Modules, such as this {Module Name} Module. Learn more about why modules are isolated in [this documentation](!docs!\/learn\/fundamentals\/modules\/isolation). <\/Note> ## {Module Name} Features - **[Feature 1](\/references\/module\/models\/ModelName)**: Description of the feature - **[Feature 2](.\/guides\/guide-name\/page.mdx)**: Description of the feature - **[Feature 3](..\/related-module\/page.mdx)**: Description of the feature --- ## How to Use the {Module Name} Module In your Medusa application, you build flows around Commerce Modules. A flow is built as a [Workflow](!docs!\/learn\/fundamentals\/workflows), which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism. You can build custom workflows and steps. You can also re-use Medusa's workflows and steps, which are provided by the `@medusajs\/medusa\/core-flows` package. For example: export const highlights = [ ["12", "Modules.{MODULE}", "Resolve the module in a step."] ] ```ts title="src\/workflows\/example.ts" highlights={highlights} import { createWorkflow, WorkflowResponse, createStep, StepResponse, } from "@medusajs\/framework\/workflows-sdk" import { Modules } from "@medusajs\/framework\/utils" const exampleStep = createStep( "example-step", async ({}, { container }) => { const moduleService = container.resolve(Modules.{MODULE}) \/\/ Use module service methods const result = await moduleService.someMethod({ \/\/ parameters }) return new StepResponse({ result }, result.id) }, async (resultId, { container }) => { if (!resultId) { return } const moduleService = container.resolve(Modules.{MODULE}) \/\/ Rollback logic await moduleService.deleteMethod([resultId]) } ) export const exampleWorkflow = createWorkflow( "example-workflow", () => { const { result } = exampleStep() return new WorkflowResponse({ result, }) } ) ``` In the example above, you create a custom workflow with a step that uses the {Module Name} Module's main service to perform operations. Learn more about workflows in the [Workflows documentation](!docs!\/learn\/fundamentals\/workflows). <\/Note> You can also use the {Module Name} Module's service directly in other resources, such as API routes: ```ts title="src\/api\/custom\/route.ts" import { MedusaRequest, MedusaResponse } from "@medusajs\/framework\/http" import { Modules } from "@medusajs\/framework\/utils" export async function GET( req: MedusaRequest, res: MedusaResponse ) { const moduleService = req.scope.resolve(Modules.{MODULE}) const items = await moduleService.listMethod() res.json({ items }) } ``` --- ## Guides --- ## Data Models The {Module Name} Module defines the following data models: Learn more about data models and their properties in the [References](\/references\/module). --- ## Related Modules ``` **For Feature\/Concept Page**: ```mdx export const metadata = { title: `Feature Name`, } # {metadata.title} In this document, you'll learn about {feature} and how to use it. ## What is {Feature}? Explanation of the feature and its purpose. Learn more about [related concept](!docs!\/path). <\/Note> --- ## How to Use {Feature} ### In a Workflow Example showing usage in a workflow: ```ts title="src\/workflows\/example.ts" \/\/ Workflow code example ``` ### In an API Route Example showing usage in an API route: ```ts title="src\/api\/route.ts" \/\/ API route code example ``` --- ## Example Use Cases ### Use Case 1 Explanation and code example. ### Use Case 2 Explanation and code example. --- ## Related Resources - [Related guide](.\/guides\/page.mdx) - [Module reference](\/references\/module) - [Workflow documentation](!docs!\/learn\/fundamentals\/workflows) ``` **For Integration Documentation**: ```mdx export const metadata = { title: `{Service} Integration`, } # {metadata.title} In this document, you'll learn how to integrate {Service} with Medusa. ## Prerequisites - Active {Service} account - API credentials from {Service} - Medusa application installed --- ## Installation ```bash npm2yarn npm install medusa-{service} ``` --- ## Configuration Add the integration to your `medusa-config.ts`: ```ts title="medusa-config.ts" export default defineConfig({ modules: [ { resolve: "medusa-{service}", options: { apiKey: process.env.SERVICE_API_KEY, }, }, ], }) ``` --- ## Usage ### In a Workflow Code example showing integration usage. ### Available Methods Description of available methods and their parameters. --- ## Testing Instructions for testing the integration. --- ## Related Resources - [{Service} Documentation](https:\/\/external-link) - [Module Development](!docs!\/learn\/fundamentals\/modules) ``` 5. **Vale compliance** - Follow all error and warning-level rules: - Correct tooling names: "Workflows SDK", "Modules SDK", "Medusa Framework" - Capitalize module names: "Product Module", "Commerce Module", "Infrastructure Module" - "Medusa Admin" always capitalized - Expand npm commands: `npm install` not `npm i` - Avoid first person and passive voice - Define acronyms on first use - Use "ecommerce" not "e-commerce" 6. **Cross-project links** - Use special syntax: - Main docs: `!docs!\/learn\/path` - User guide: `!user-guide!\/path` - API reference: `!api!\/admin` or `!api!\/store` - Other resources: relative paths or `!resources!\/path` 7. **Create the file** using Write tool ## Key Components From `docs-ui`: - `` - Navigation cards for guides, models, related modules - `` - Callout boxes (use `title` prop) - `` \/ `` - Multi-language\/approach examples - `` - Data tables for comparisons ## Frontmatter Structure For overview pages: - `generate_toc: true` - Auto-generate table of contents For feature pages: - Minimal frontmatter or none, just metadata export ## Code Example Patterns 1. **Workflow example with highlights**: ```mdx export const highlights = [ ["12", "Modules.PRODUCT", "Explanation"] ] ```ts title="src\/workflows\/example.ts" highlights={highlights} \/\/ code ``` ``` 2. **API route example**: ```ts title="src\/api\/route.ts" import { MedusaRequest, MedusaResponse } from "@medusajs\/framework\/http" \/\/ code ``` 3. **Configuration example**: ```ts title="medusa-config.ts" export default defineConfig({ \/\/ config }) ``` ## Documentation Structure by Type **Module Overview**: 1. Introduction with User Guide link 2. Feature list with links 3. "How to Use" section with workflow and API examples 4. Guides section with CardList 5. Data Models section with CardList 6. Related Modules section **Feature\/Concept Page**: 1. Introduction 2. "What is X?" explanation 3. "How to Use X" with code examples 4. Example use cases 5. Related resources **Integration Page**: 1. Introduction 2. Prerequisites 3. Installation 4. Configuration 5. Usage examples 6. Testing 7. Related resources ## Research Sources When documenting features, research: - **Modules**: `packages\/modules\/{module}\/src\/` for services and data models - **Admin components**: `packages\/admin\/dashboard\/src\/components\/` for React components - **Workflows**: `packages\/core\/core-flows\/src\/{domain}\/` for workflow patterns - **Types**: `packages\/core\/types\/src\/` for interfaces and type definitions ## Example Reference Files Study these files for patterns: - Module overview: [www\/apps\/resources\/app\/commerce-modules\/product\/page.mdx](www\/apps\/resources\/app\/commerce-modules\/product\/page.mdx) - Module list: [www\/apps\/resources\/app\/commerce-modules\/page.mdx](www\/apps\/resources\/app\/commerce-modules\/page.mdx) - Feature pages: `www\/apps\/resources\/app\/commerce-modules\/{module}\/*\/page.mdx` ## Execution Steps 1. Ask user for documentation type and feature 2. Research implementation in `packages\/` directory 3. Read 1-2 similar documentation pages for patterns 4. Generate appropriate structure based on type 5. Include workflow and API route examples 6. Add CardList for navigation to guides and references 7. Include cross-project links to main docs and user guide 8. Validate against Vale rules 9. Use Write tool to create file 10. Confirm completion

resources-doc