diff --git a/.claude/skills/writing-tutorials/SKILL.md b/.claude/skills/writing-tutorials/SKILL.md new file mode 100644 index 0000000000000..023b97e02a130 --- /dev/null +++ b/.claude/skills/writing-tutorials/SKILL.md @@ -0,0 +1,52 @@ +--- +name: writing-tutorials +description: Creates Medusa documentation tutorials in two phases: first builds the tutorial feature in an example project (with planning, coding, and tests), then writes the MDX documentation. Use when creating a new how-to tutorial or integration guide for the Medusa docs. Handles both feature implementation and documentation writing, but only one phase at a time. +--- + +# Writing Medusa Tutorials + +Guides an agent through creating a complete Medusa tutorial: building the feature in an example project, then writing the documentation. + +## Two-Phase Approach + +**Phase 1 — Build:** Gather requirements → plan with user → implement feature → add tests → confirm with user +**Phase 2 — Write:** Create step diagram → write per-step MD files → combine into final MDX → update sidebar → clean up + +> **CRITICAL:** Never do both phases in one session. Complete Phase 1, get user confirmation, then reload this skill for Phase 2. + +## Load Reference Files When Needed + +> **Load at least one reference file before proceeding.** + +| Task | Load | +|------|------| +| Starting Phase 1 (building) | `reference/building-phase.md` | +| Starting Phase 2 (writing) | `reference/writing-phase.md` + `reference/tutorial-conventions.md` + `reference/concept-definitions.md` | +| MDX patterns and components | `reference/tutorial-conventions.md` | +| Concept definitions (module, workflow, etc.) | `reference/concept-definitions.md` | + +## Quick Reference + +### File Locations + +| Type | Content Path | Sidebar File | +|------|-------------|--------------| +| How-to tutorial | `www/apps/resources/app/how-to-tutorials/tutorials/{name}/page.mdx` | `www/apps/resources/sidebars/how-to-tutorials.mjs` | +| Integration guide | `www/apps/resources/app/integrations/guides/{name}/page.mdx` | `www/apps/resources/sidebars/integrations.mjs` | + +### Development Skills to Load During Build + +- Backend features → `medusa-dev:building-with-medusa` +- Admin UI → `medusa-dev:building-admin-dashboard-customizations` +- Storefront → `medusa-dev:building-storefronts` +- Third-party services → `context7` MCP or skills +- Medusa API questions → `mcp__medusa__ask_medusa_question` + +## Common Mistakes + +- [ ] Jumping straight to writing documentation without building the feature first +- [ ] Writing both phases in one session without user confirmation between them +- [ ] Writing Step 1 (Medusa installation) from scratch — use the pre-written template in `tutorial-conventions.md` +- [ ] Forgetting to update the sidebar after writing the tutorial MDX +- [ ] Leaving `_step-*.md` temp files after combining into final MDX +- [ ] Making tutorial code overly complex — tutorials are educational, keep it simple diff --git a/.claude/skills/writing-tutorials/reference/building-phase.md b/.claude/skills/writing-tutorials/reference/building-phase.md new file mode 100644 index 0000000000000..6f9b6c4f1885e --- /dev/null +++ b/.claude/skills/writing-tutorials/reference/building-phase.md @@ -0,0 +1,92 @@ +# Phase 1: Building the Tutorial Feature + +Follow these steps to build the tutorial's feature in the example project before writing any documentation. + +## Step 1 — Gather Requirements + +Ask the user the following before doing anything else: + +1. **Tutorial topic** — What feature or integration is being built? (e.g., "product reviews", "PayPal integration") +2. **Tutorial type** — How-to tutorial or integration guide? +3. **Example project path** — Where is the target Medusa example project? (e.g., `~/projects/my-medusa-app`) +4. **Third-party services** — Are any external services involved? (e.g., PayPal, Segment, Stripe) +5. **Scope** — Should the tutorial include Admin UI customizations? Storefront customizations? + +Do NOT proceed until all required information is collected. + +## Step 2 — Research & Plan + +Before writing any code: + +1. Load `medusa-dev:building-with-medusa` — required for all backend work + - Also load `medusa-dev:building-admin-dashboard-customizations` if admin UI is in scope + - Also load `medusa-dev:building-storefronts` if storefront is in scope +2. Use `mcp__medusa__ask_medusa_question` for questions about Medusa APIs, modules, and patterns +3. For integrations with third-party services: use `context7` MCP or skills to retrieve their documentation + +**Write a plan covering:** +- Data models to create (custom module if needed) +- Workflows and their steps +- API routes (store and/or admin) +- Admin UI widgets/pages (if applicable) +- Storefront components/changes (if applicable) +- Seed data or configuration needed + +> **CRITICAL:** Keep it simple. Tutorial code is for learning, not production. Avoid unnecessary abstractions, overly generic utilities, or complex patterns. One clear approach beats multiple flexible ones. + +**Present the plan to the user and get explicit approval before writing any code.** + +## Step 3 — Build the Feature + +Follow the approved plan. Always follow the architecture layer order: + +``` +Custom Module (data models + CRUD) + ↓ +Workflow (business logic, mutations) + ↓ +API Route (HTTP interface) + ↓ +Admin UI / Storefront +``` + +**Useful commands:** +- Generate migration: `/medusa-dev:db-generate ` +- Run migrations: `/medusa-dev:db-migrate` +- Create admin user: `/medusa-dev:new-user ` + +Load reference files from `medusa-dev:building-with-medusa` for each component as you build it. + +## Step 4 — Add Tests + +Write tests to validate the implementation: + +- **Workflow steps** — Unit tests for each step's main logic +- **API routes** — Integration tests covering success and error cases +- **Custom module service methods** — Unit tests for any non-trivial service logic + +Place tests in: +- `integration-tests/` for API/integration tests +- `src/**/__tests__/` for unit tests + +Keep tests simple and focused on verifying the feature works as expected. These tests also serve as examples for tutorial readers. + +## Step 5 - Validate Implementation + +Before finishing up, make sure that: + +1. Build passes: `yarn build` +2. Integration and unit tests pass + +Fix all issues before wrapping up. + +## Step 6 — Wrap Up + +1. Tell the user to test the feature manually: + - Start the Medusa app and test relevant API routes + - Verify in the Admin UI (if applicable) + - Verify in the Storefront (if applicable) +2. Ask the user: **"Does everything look good? Let me know when you're ready to write the tutorial documentation."** +3. Once the user confirms, instruct them: **"Reload `/writing-tutorials` and I'll help you write the documentation."** + +> **IMPORTANT:** Do not start writing documentation until the user explicitly confirms the build is complete and working. diff --git a/.claude/skills/writing-tutorials/reference/concept-definitions.md b/.claude/skills/writing-tutorials/reference/concept-definitions.md new file mode 100644 index 0000000000000..efdff6c42dde3 --- /dev/null +++ b/.claude/skills/writing-tutorials/reference/concept-definitions.md @@ -0,0 +1,305 @@ +# Concept Definitions + +When a concept is introduced for the first time in a tutorial step, include a 1-2 sentence definition before the implementation details. Use these verbatim (or adapt minimally for context). Always follow the definition with a `` linking to further documentation. + +--- + +## Module + +> **IMPORTANT:** If the Module is a Module Provider, use the definition for the specific provider instead. DO NOT add both definitions. + +```mdx +In Medusa, you can build custom features in a [module](!docs!/learn/fundamentals/modules). A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without affecting your setup. + +In the module, you define the data models necessary for a feature and the logic to manage these data models. Later, you can build commerce flows around your module. + + + +Refer to the [Modules documentation](!docs!/learn/fundamentals/modules) to learn more. + + +``` + +--- + +## Data Model + +```mdx +A data model represents a table in the database. You create data models using Medusa's Data Model Language (DML), which simplifies defining a table's columns, relations, and indexes with straightforward methods and configurations. + + + +Learn more about data models in the [Data Models documentation](!docs!/learn/fundamentals/data-models). + + +``` + +--- + +## Service + +```mdx +A service is a TypeScript or JavaScript class that the module exports. In the service's methods, you can connect to the database to manage your data models, or connect to a third-party service, which is useful when integrating with external systems. +``` + +--- + +## Migration + +```mdx +Since data models represent tables in the database, you define how to create them in the database using migrations. A migration is a TypeScript or JavaScript file that defines database changes made by a module. +``` + +--- + +## Module Links + +```mdx +Medusa integrates modules into your application without side effects by isolating them from one another. This means you can't directly create relationships between data models in your module and data models in other modules. + +Instead, Medusa provides a mechanism to define links between data models and to retrieve and manage linked records while maintaining module isolation. Links are useful for defining associations between data models in different modules or for extending a model in another module to associate custom properties with it. + + + +Refer to the [Module Isolation documentation](!docs!/learn/fundamentals/modules/isolation) to learn more. + + +``` + +--- + +## Workflow + +```mdx +To build custom commerce features in Medusa, you create a [workflow](!docs!/learn/fundamentals/workflows). A workflow is a series of queries and actions, called steps, that complete a task. You can track the workflow's execution progress, define rollback logic, and configure other advanced features. + + + +Learn more about workflows in the [Workflows documentation](!docs!/learn/fundamentals/workflows). + + +``` + +--- + +## Workflow Hook + +```mdx +A hook is a specific point in a workflow where you can inject custom functionality. + + + +Refer to the [Workflow Hooks documentation](!docs!/learn/fundamentals/workflows/workflow-hooks) to learn more. + + +``` + +--- + +## API Route + +```mdx +An API route is created in a `route.ts` file under a sub-directory of the `src/api` directory. The path of the API route is the file's path relative to `src/api`. + + + +Refer to the [API routes](!docs!/learn/fundamentals/api-routes) documentation to learn more about them. + + +``` + +--- + +## Subscriber + +```mdx +A subscriber is an asynchronous function that runs in the background when specific events are emitted. + + + +Refer to the [Subscribers documentation](!docs!/learn/fundamentals/events-and-subscribers) to learn more. + + +``` + +--- + +## Admin Dashboard Customization (intro paragraph) + +Use this when first introducing any Admin customization in a step: + +```mdx +The Medusa Admin dashboard is customizable, allowing you to insert widgets into existing pages, or create new pages. + + + +Refer to the [Admin Development](!docs!/learn/fundamentals/admin) documentation to learn more. + + +``` + +--- + +## Admin UI Route (Page) + +Use this when creating a new admin page: + +```mdx +A UI route is a React component that specifies the content to be shown in a new page in the Medusa Admin dashboard. + + + +Refer to the [UI Routes documentation](!docs!/learn/fundamentals/admin/ui-routes) to learn more. + + +``` + +--- + +## Scheduled Job + +```mdx +A scheduled job is a function that runs at a specified interval in the background of your Medusa application. + + + +Refer to the [Scheduled Jobs documentation](!docs!/learn/fundamentals/scheduled-jobs) to learn more. + + +``` + +--- + +--- + +## Integration: Generic Module Provider Intro + +Use this paragraph when first introducing the idea of creating a module to integrate a third-party service. Place it at the top of the step that creates the module provider: + +```mdx +To integrate third-party services into Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup. + + + +Learn more about modules in [this documentation](!docs!/learn/fundamentals/modules). + + +``` + +--- + +## Integration: Notification Module Provider + +Use after the generic module intro when the provider implements the Notification Module: + +```mdx +Medusa's Notification Module delegates sending notifications to other modules, called module providers. In this step, you'll create a [Service Name] Module Provider that implements sending notifications through the [channel, e.g., email] channel. + +A Notification Module Provider's service must extend the `AbstractNotificationProviderService`. It has a `send` method that you'll implement to send notifications. The service must also have an `identifier` static property, which is a unique identifier that the Medusa application uses to register the provider in the database. + + + +Refer to the [Create Notification Module Provider](/references/notification/provider) guide for more details. + + +``` + +--- + +## Integration: Payment Module Provider + +Use after the generic module intro when the provider implements the Payment Module: + +```mdx +Medusa's [Payment Module](../../../commerce-modules/payment/page.mdx) provides an interface to process payments in your Medusa application. It delegates the actual payment processing to the underlying providers. + +A Payment Module Provider's service must extend the `AbstractPaymentProvider` class. It must also have a static `identifier` property that uniquely identifies the provider. + + + +Refer to the [Create Payment Provider](/references/payment/provider) guide for more details about the methods to implement. + + +``` + +--- + +## Integration: Fulfillment Module Provider + +Use after the generic module intro when the provider implements the Fulfillment Module: + +```mdx +Medusa's Fulfillment Module delegates processing fulfillments and shipments to other modules, called module providers. In this step, you'll create a [Service Name] Module Provider that implements all functionalities required for fulfillment. + +A Fulfillment Module Provider's service must extend the `AbstractFulfillmentProviderService` class. + + + +Refer to the [Create Fulfillment Provider](/references/fulfillment/provider) guide for more details about the methods to implement. + + +``` + +--- + +## Integration: Analytics Module Provider + +Use after the generic module intro when the provider implements the Analytics Module: + +```mdx +Medusa's [Analytics Module](../../../infrastructure-modules/analytics/page.mdx) provides an interface to track events in your Medusa application. It delegates the actual tracking to the configured Analytics Module Provider. + +An Analytics Module Provider's service must extend the `AbstractAnalyticsProviderService` class. It must also have an `identifier` static property with the unique identifier of the provider. + + + +Refer to the [Create Analytics Module Provider](/references/analytics/provider) guide for more details about the methods to implement. + + +``` + +--- + +## Integration: Auth Module Provider + +Use after the generic module intro when the provider implements the Auth Module: + +```mdx +Medusa's [Auth Module](../../../commerce-modules/auth/page.mdx) provides the interface to authenticate users. It delegates the actual authentication logic to the underlying Auth Module Provider. + +An Auth Module Provider's service must extend the `AbstractAuthModuleProvider` class. It must also have a `DISPLAY_NAME` static property for display in the UI, and an `identifier` static property with the unique identifier of the provider. + + + +Refer to the [Create Auth Module Provider](/references/auth/provider) guide for more details about the methods to implement. + + +``` + +--- + +## Integration: Custom Module (non-provider) + +Use when the integration is built as a standalone custom module rather than a built-in module provider (e.g., a CMS, search engine, or custom third-party service): + +```mdx +To integrate third-party services into Medusa, you create a custom module. A module is a reusable package with functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup. + +In this step, you'll create a custom module that provides the necessary functionalities to integrate [Service Name] with Medusa. + + + +Refer to the [Modules documentation](!docs!/learn/fundamentals/modules) to learn more. + + +``` + +--- + +## Usage Guidelines + +- Only include a definition the **first time** the concept appears in the tutorial. +- Subsequent steps that use the same concept (e.g., a second workflow) do NOT repeat the definition. +- Adapt the definition sentence minimally for context — for example, replace "a tier" with the tutorial's actual entity name. +- Always follow definitions with a `` linking to the relevant documentation page. +- For integration guides: always use the **Generic Module Provider Intro** first, then add the module-specific definition below it (Notification, Payment, etc.). diff --git a/.claude/skills/writing-tutorials/reference/tutorial-conventions.md b/.claude/skills/writing-tutorials/reference/tutorial-conventions.md new file mode 100644 index 0000000000000..40214aeb6ae60 --- /dev/null +++ b/.claude/skills/writing-tutorials/reference/tutorial-conventions.md @@ -0,0 +1,390 @@ +# Tutorial MDX Conventions + +Reference for MDX structure, components, and patterns used in Medusa tutorials. + +## Frontmatter + +```yaml +--- +sidebar_label: "Feature Name" +tags: + - name: module-name + label: "Implement Feature Name" + - server + - tutorial +products: + - product + - customer +--- +``` + +- `sidebar_label`: Short display name for the sidebar +- `tags`: Mix of string tags (`server`, `tutorial`) and object tags (`{name, label}`) for cross-linking +- `products`: Medusa Commerce Modules covered (product, cart, order, customer, promotion, payment, etc.) + +For integration guides, add the service type as a tag string (e.g., `analytics`, `notification`, `cms`). + +## Required Imports and Metadata + +```mdx +import { Github, PlaySolid } from "@medusajs/icons" +import { Prerequisites, WorkflowDiagram, CardList } from "docs-ui" + +export const metadata = { + title: `Implement X in Medusa`, +} +``` + +## Standard Section Order + +```text +# {metadata.title} + +[Intro paragraph] + +## Summary + +[Bullet list] + +You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer. + +![Overview diagram alt text](https://res.cloudinary.com/...) + + + +--- + +## Step 1: Install a Medusa Application +[pre-written template — see below] + +## Step 2: ... +... + +## Next Steps + +### Troubleshooting + +### Getting Help +``` + +Note: `## Troubleshooting` and `## Getting Help` are **subsections** (`###`) under `## Next Steps`, not top-level sections. + +## Pre-Written Step 1 Template (Always Use Verbatim) + +Copy this exactly — do not rewrite it: + +````mdx +## Step 1: Install a Medusa Application + + + +Start by installing the Medusa application on your machine with the following command: + +```bash npx2yarnExec +npx create-medusa-app@latest +``` + +You'll first be asked for the project's name. Then, when asked whether you want to install the [Next.js Starter Storefront](../../../nextjs-starter/page.mdx), choose Yes. + +Afterward, the installation process will start, which will install the Medusa application in a directory with your project's name, and the Next.js Starter Storefront in a separate directory with the `{project-name}-storefront` name. + + + +The Medusa application is composed of a headless Node.js server and an admin dashboard. The storefront is installed or custom-built separately and connects to the Medusa application through its REST endpoints, called [API routes](!docs!/learn/fundamentals/api-routes). Learn more in [Medusa's Architecture documentation](!docs!/learn/introduction/architecture). + + + +Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterward, you can log in with the new user and explore the dashboard. + + + +Check out the [troubleshooting guides](../../../troubleshooting/create-medusa-app-errors/page.mdx) for help. + + + +--- +```` + +For integration guides where a storefront may not be needed, omit the storefront-related sentences and the "Why is the storefront installed separately" note. + +## Intro Paragraph Pattern + +``` +In this tutorial, you'll learn how to implement [X] in Medusa. + +When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. The Medusa application's commerce features are built around [Commerce Modules](../../../commerce-modules/page.mdx) which are available out-of-the-box. + +Medusa doesn't provide [X] out-of-the-box, but the Medusa Framework facilitates implementing customizations like [X]. In this tutorial, you'll learn how to customize the Medusa server[, Admin dashboard, and Next.js Starter Storefront] to implement [X]. + +You can follow this guide whether you're new to Medusa or an advanced Medusa developer. +``` + +## Summary Section Pattern + +```mdx +## Summary + +By following this tutorial, you'll learn how to: + +- Install and set up Medusa. +- [Main feature: e.g., Define product review models and implement their management features in the Medusa server.] +- [Admin: e.g., Customize the Medusa Admin to allow merchants to view and manage product reviews.] +- [Storefront: e.g., Customize the Next.js Starter Storefront to display and submit product reviews.] +``` + +## CardList (GitHub + OpenAPI) + +```mdx + +``` + +If no OpenAPI specs exist, omit the second card. + +## Components + +### Prerequisites +Use only at Step 1: +```mdx + +``` + +Add extra prerequisites for integration guides (e.g., third-party account, API key). + +### WorkflowDiagram +Place immediately after introducing a workflow: +```mdx + +``` + +### Note +```mdx + +Plain note with no title. + + + +Note with a custom title. + +``` + +## Code Block Attributes + +``` +```ts title="src/modules/review/models/product-review.ts" +// backend code +``` + +```tsx title="src/app/products/[id]/page.tsx" badgeLabel="Storefront" badgeColor="blue" +// storefront code +``` + +```ts title="src/workflows/create-review.ts" highlights={createReviewHighlights} +// workflow code with line highlights +``` + +```bash npm2yarn +npm install some-package +``` + +```bash npx2yarnExec +npx create-medusa-app@latest +``` +``` + +**Badge conventions:** +- `badgeLabel="Storefront"` + `badgeColor="blue"` — Next.js storefront files +- `badgeLabel="Medusa Application"` + `badgeColor="green"` — backend files (only when both appear close together) + +## Highlights Arrays + +Define highlights as exported constants before the MDX body: + +```ts +export const workflowHighlights = [ + ["5", "input", "The workflow receives the review data as input."], + ["10", "product_id", "Retrieve the product to validate it exists."], + ["18", "review", "Create the product review record."], +] +``` + +Format: `[lineNumber, keyword/identifier, description]` + +Reference in code block: `highlights={workflowHighlights}` + +## Service Method Sub-Steps Pattern + +When a step requires implementing multiple methods on a service class (common in module provider integrations), each method gets its own lettered sub-step under the parent step. Structure: + +1. First sub-step: create the service file with the class scaffold (no methods yet), then explain the class structure below the code block +2. Subsequent sub-steps: one per method — explain what it does, show the code adding that method to the class, then explain implementation details + +**Sub-step heading format:** `### {letter}. Implement {methodName} Method` + +**Example structure for a service step:** + +````mdx +## Step 3: Create Mailchimp Module Provider + +[concept definition + module creation context] + +### a. Create Module Directory + +[directory creation instruction] + +### b. Create Service + +[1-2 sentences on what the service does] + +Create the file `src/modules/mailchimp/service.ts` with the following content: + +```ts title="src/modules/mailchimp/service.ts" highlights={serviceHighlights} +// class scaffold with constructor only, no method implementations yet +``` + +[Explanation of class structure: what it extends, static `identifier`, constructor params and what each option means] + +In the next sections, you'll implement the methods of the `MailchimpNotificationProviderService` class. + +### c. Implement validateOptions Method + +The `validateOptions` method is used to validate the options passed to the module provider. If the method throws an error, the Medusa application won't start. + +Add the `validateOptions` method to the `MailchimpNotificationProviderService` class: + +```ts title="src/modules/mailchimp/service.ts" +class MailchimpNotificationProviderService extends AbstractNotificationProviderService { + // ... + validateOptions(options: Options) { + // ... + } +} +``` + +[Explain what the method does and any important implementation details] + +### d. Implement send Method + +When the Medusa application needs to send a notification, it calls the `send` method of the module provider. + +[Continue with remaining methods...] +```` + +**Key rules:** +- Show only the new method being added in each sub-step's code block — use `// ...` to omit already-shown code +- Always add a transition sentence like "In the next sections, you'll implement the methods of the `XService` class." after introducing the scaffold +- Helper/private methods that support a required method can be nested as `####` sub-sub-steps under the parent method's `###` sub-step +- The final sub-step of a service step is always exporting the module definition (`### {letter}. Export Module Definition`) + +## Test it Out Sections + +Every major step (API routes, subscribers, admin UI, storefront) must end with a test section: + +```mdx +### Test it Out + +To test the [feature], send a request to the [endpoint]: + +```bash +curl -X POST http://localhost:9000/store/products/{id}/reviews \ + -H "Content-Type: application/json" \ + --data-raw '{ + "rating": 5, + "content": "Great product!" + }' +``` + +If successful, you'll receive a response similar to: + +```json +{ + "review": { + "id": "review_123", + "rating": 5, + "content": "Great product!" + } +} +``` +``` + +For Admin UI steps, describe where to navigate and what to look for. For storefront steps, describe the user interaction. + +## Next Steps, Troubleshooting, and Getting Help (Verbatim Template) + +Use this structure exactly. Adjust the bullet points in `## Next Steps` to match the tutorial's topic. + +`### Troubleshooting` and `### Getting Help` are subsections of `## Next Steps` — do not promote them to `##`. + +````mdx +## Next Steps + +You've now implemented [X] in Medusa. You can expand on this feature to add more features like: + +- [Idea 1, e.g., Automated emails to customers when they reach a new tier.] +- [Idea 2, e.g., More complex rules based on product categories or collections.] +- [Idea 3, e.g., Other privileges, such as early access to new products or free shipping.] + +If you're new to Medusa, check out the [main documentation](!docs!/learn) for a more in-depth understanding of the concepts you've used in this guide and more. + +To learn more about the commerce features Medusa provides, check out [Commerce Modules](../../../commerce-modules/page.mdx). + +### Troubleshooting + +If you encounter issues during your development, check out the [troubleshooting guides](../../../troubleshooting/page.mdx). + +### Getting Help + +If you encounter issues not covered in the troubleshooting guides: + +1. Visit the [Medusa GitHub repository](https://github.com/medusajs/medusa) to report issues or ask questions. +2. Join the [Medusa Discord community](https://discord.gg/medusajs) for real-time support from community members. +```` diff --git a/.claude/skills/writing-tutorials/reference/writing-phase.md b/.claude/skills/writing-tutorials/reference/writing-phase.md new file mode 100644 index 0000000000000..5fb780bb2b76a --- /dev/null +++ b/.claude/skills/writing-tutorials/reference/writing-phase.md @@ -0,0 +1,118 @@ +# Phase 2: Writing the Tutorial Documentation + +Follow these steps after the build phase is confirmed complete by the user. + +> **Prerequisites:** Building phase is done and user has confirmed the feature works. You know the example project path and all implemented features. + +Also load `reference/tutorial-conventions.md` and `reference/concept-definitions.md` before starting. + +## Step 1 — Create Step Diagram + +Map out all tutorial steps in the logical order a developer would execute them. Write this to a temp file `_step-diagram.md` in the project root. + +**Always start with Step 1 (Medusa installation) — it is always the first step.** + +Typical step order: +1. Install Medusa Application (always first — use pre-written template) +2. Create custom module + data models (if any) +3. Run database migrations (immediately after module creation) +4. Create workflow steps +5. Create workflows +6. Create API routes (store and/or admin) +7. Create subscribers or scheduled jobs (if any) +8. Admin UI customizations (widgets, pages — if applicable) +9. Storefront customizations (if applicable) + +> **Rule:** A step that creates something used by another step must come first. You can't write "Create API route" before "Create workflow" because the route uses the workflow. + +Include "Test it Out" sub-steps for each major piece (API routes, subscribers, admin UI, storefront). + +Example `_step-diagram.md`: +``` +1. Install Medusa Application +2. Create Product Review Module (data models: ProductReview) +3. Run migrations +4. Create createProductReviewWorkflow (step: createProductReviewStep) +5. Create GET /store/products/:id/reviews route +6. Create POST /store/products/:id/reviews route + - Test: Submit a review via API +7. Create GET /admin/product-reviews route + - Test: List reviews in Admin +8. Create Admin UI widget (product reviews tab on product page) + - Test: View reviews widget in Admin +9. Storefront: Display reviews on product page +10. Storefront: Add review submission form + - Test: Submit and see review in storefront +``` + +## Step 2 — Write Per-Step MD Files + +For each step in the diagram, write a separate temp file in the Medusa project root: +- `_step-01-install.md` +- `_step-02-module.md` +- `_step-03-migrations.md` +- etc. + +**Step 1 (Medusa installation):** Copy the pre-written template directly from `tutorial-conventions.md`. Do not rewrite it. + +For each other step file: +- Start with `## Step N: Step Title` +- Write 1-2 sentences explaining what this step does and why +- **First-use concept definitions:** The first time a Medusa concept is introduced (module, workflow, API route, subscriber, etc.), include its definition from `reference/concept-definitions.md` before the implementation. Do NOT repeat the definition in later steps that use the same concept. +- **Service method implementations:** When a step implements methods on a service class, give each method its own sub-step (e.g., `### b. Implement send Method`). Each sub-step must: (1) explain in 1-2 sentences what the method does and when Medusa calls it, (2) show the code for that method only, (3) explain relevant implementation details below the code block. See `tutorial-conventions.md` for the pattern. +- Show all code needed for this step with proper code block attributes (title, badgeLabel, highlights) +- End with a `### Test it Out` section showing how to verify this step works +- Follow all MDX patterns from `tutorial-conventions.md` + +Load `writing-docs` skill to apply prose quality rules while writing step content. + +> Write one step file at a time. Complete each file fully before moving to the next. + +## Step 3 — Combine Into Final MDX + +Once all step files are written, create the final tutorial file. + +**Determine the path:** +- How-to tutorial: `www/apps/resources/app/how-to-tutorials/tutorials/{name}/page.mdx` +- Integration guide: `www/apps/resources/app/integrations/guides/{name}/page.mdx` + +Create a `page.mdx` file with this structure (in order): + +``` +1. Frontmatter (sidebar_label, tags, products) +2. Imports (Github icon, Prerequisites, WorkflowDiagram, CardList from docs-ui) +3. export const metadata = { title: `...` } +4. export const highlights arrays (if any) +5. # {metadata.title} +6. Intro paragraph +7. ## Summary (bullet list) +8. Overview image placeholder +9. CardList (GitHub repo + OpenAPI specs if applicable) +10. --- +11. [All step content from per-step files, combined in order] +12. ## Next Steps +13. ## Troubleshooting +14. ## Getting Help +``` + +See `tutorial-conventions.md` for exact templates for each section. + +## Step 4 — Update Sidebar + +After writing the MDX file, verify the tutorial appears in the sidebar. + +**For how-to tutorials** — open `www/apps/resources/sidebars/how-to-tutorials.mjs`: +- Find the relevant `sub-category` that has `autogenerate_tags` matching your tutorial's tags +- If a matching category exists (e.g., `autogenerate_tags: "howTo+server"`), ensure your tutorial's frontmatter `tags` array includes `server` and `tutorial` — no manual entry needed +- If no matching category exists, add a manual `link` entry in the appropriate section + +**For integration guides** — open `www/apps/resources/sidebars/integrations.mjs`: +- Same approach: check for autogenerate tags or add a manual entry + +## Step 5 — Cleanup + +Delete all temp files from the Medusa project root: +- `_step-diagram.md` +- `_step-01-install.md`, `_step-02-module.md`, etc. (all `_step-*.md` files) + +Verify the final `page.mdx` looks complete and correct before finishing.