docs: customer tiers tutorial (#14122)

* docs: customer tiers tutorial * fix lint error
2025-11-26 10:07:28 +02:00
parent 1e761345be
commit 458dc9d22b
16 changed files with 8411 additions and 7 deletions
@@ -0,0 +1,447 @@
+# Medusa Tutorial Structure Rules
+
+## Overview
+
+This file defines the structure and formatting requirements for creating Medusa tutorials in the `/app/how-to-tutorials/tutorials/` directory. All tutorials must follow this structure to ensure consistency and quality.
+
+## File Structure
+
+### 1. Frontmatter (Required)
+
+Every tutorial must start with YAML frontmatter containing:
+
+```yaml
+---
+sidebar_label: "Tutorial Name"  # Display name in sidebar
+tags:
+    - name: product_name         # Product tags (e.g., cart, order, customer)
+      label: "Implement Feature"
+    - server                      # Always include if server-side code
+    - tutorial                   # Always include
+    - nextjs                     # Include if storefront customization
+products:
+  - product_name                 # Array of product names used
+---
+```
+
+**Additional frontmatter options:**
+
+- `keywords`: Array of keywords for SEO (optional)
+- `ogImage`: Export for Open Graph image (optional)
+
+### 2. Imports
+
+After frontmatter, include necessary imports:
+
+- `Github`, `PlaySolid` from `@medusajs/icons` (if needed)
+- `Prerequisites`, `WorkflowDiagram`, `CardList`, `Card` from `docs-ui`
+- Other necessary components
+
+### 3. Metadata Export
+
+```typescript
+export const metadata = {
+  title: `Implement Feature Name in Medusa`,
+  // Optional: openGraph and twitter metadata
+}
+```
+
+### 4. Title Section
+
+```markdown
+# {metadata.title}
+
+In this tutorial, you'll learn how to [brief description].
+```
+
+### 5. Context Paragraph
+
+Include 1-2 paragraphs explaining:
+
+- What Medusa provides out-of-the-box
+- What the tutorial will teach
+- Context about the feature being implemented
+
+### 6. Summary Section
+
+```markdown
+## Summary
+
+By following this tutorial, you will learn how to:
+
+- Install and set up Medusa.
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+```
+
+### 7. Visual Elements
+
+- Include diagrams/images when helpful (use Cloudinary URLs)
+- Use `WorkflowDiagram` component for workflow visualizations
+- Use `CardList` or `Card` components for GitHub links and OpenAPI specs
+
+### 8. Step Structure
+
+#### Step 1: Install a Medusa Application (Always Required)
+
+```markdown
+## Step 1: Install a Medusa Application
+
+<Prerequisites items={[
+  {
+    text: "Node.js v20+",
+    link: "https://nodejs.org/en/download"
+  },
+  {
+    text: "Git CLI tool",
+    link: "https://git-scm.com/downloads"
+  },
+  {
+    text: "PostgreSQL",
+    link: "https://www.postgresql.org/download/"
+  }
+]} />
+
+Start by installing the Medusa application on your machine with the following command:
+
+\`\`\`bash
+npx create-medusa-app@latest
+\`\`\`
+
+[Instructions about installation...]
+
+<Note title="Why is the storefront installed separately">
+
+[Explanation]
+
+</Note>
+
+<Note title="Ran into Errors">
+
+Check out the [troubleshooting guides](../../../troubleshooting/create-medusa-app-errors/page.mdx) for help.
+
+</Note>
+```
+
+#### Subsequent Steps
+
+Each step should:
+
+- Have a clear, descriptive title: `## Step N: [Title]`
+- Start with context explaining what will be done
+- Break into subsections (a, b, c) if needed
+- Include code examples with proper formatting
+- Include Notes and Tips where helpful
+- End with "Test it Out" sections when applicable
+
+### 9. Code Block Formatting
+
+#### Basic Code Block
+
+```markdown
+\`\`\`ts title="src/path/to/file.ts"
+[code]
+\`\`\`
+```
+
+#### Code Block with Highlights
+
+```markdown
+export const highlights = [
+  ["line_number", "variable_name", "Description of what this does"],
+]
+
+\`\`\`ts title="src/path/to/file.ts" highlights={highlights}
+[code]
+\`\`\`
+```
+
+#### Code Block with Collapsible Lines
+
+```markdown
+\`\`\`ts title="src/path/to/file.ts" collapsibleLines="1-10" expandButtonLabel="Show Imports"
+[code]
+\`\`\`
+```
+
+#### Badge Labels
+
+- Use `badgeLabel="Storefront" badgeColor="blue"` for storefront code
+- Use `badgeLabel="Medusa Application" badgeColor="green"` for server code
+
+#### Example
+
+```markdown
+\`\`\`ts title="src/lib/data/cart.ts" badgeLabel="Storefront" badgeColor="blue"
+[code]
+\`\`\`
+```
+
+### 10. Workflow Diagrams
+
+When documenting workflows, use the `WorkflowDiagram` component:
+
+```markdown
+<WorkflowDiagram
+  workflow={{
+    name: "workflowName",
+    steps: [
+      {
+        type: "step",
+        name: "stepName",
+        description: "Description of step",
+        link: "/references/path/to/step",
+        depth: 1
+      },
+      {
+        type: "when",
+        condition: "Condition description",
+        steps: [...],
+        depth: 1
+      }
+    ]
+  }}
+/>
+```
+
+### 11. Notes and Tips
+
+Use consistently:
+
+- `<Note>` for general notes
+- `<Note title="Title">` for titled notes
+- `<Note title="Tip">` for tips
+- `<Note title="Reminder" forceMultiline>` for reminders
+
+### 12. Links to Documentation
+
+Use the special link syntax:
+
+- `!docs!/path/to/doc` for documentation links
+- `!api!/path/to/api` for API reference links
+- `!user-guide!/path/to/guide` for user guide links
+- `!ui!/path/to/component` for UI component links
+- `!cloud!/path/to/doc` for cloud documentation
+
+### 13. Test Sections
+
+Include "Test it Out" sections after major implementations:
+
+```markdown
+### Test it Out
+
+To test out [feature], start the Medusa application:
+
+\`\`\`bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm run dev
+\`\`\`
+
+[Additional testing instructions...]
+```
+
+### 14. Next Steps Section
+
+End every tutorial with:
+
+```markdown
+## Next Steps
+
+You've now implemented [feature] in Medusa. [Optional: suggest related features or improvements]
+
+If you're new to Medusa, check out the [main documentation](!docs!/learn), where you'll get a more in-depth understanding of all the concepts you've used in this guide and more.
+
+To learn more about the commerce features that Medusa provides, check out Medusa's [Commerce Modules](../../../commerce-modules/page.mdx).
+```
+
+### 15. Optional Sections
+
+#### Troubleshooting
+
+```markdown
+### Troubleshooting
+
+If you encounter issues during your development, check out the [troubleshooting guides](../../../troubleshooting/page.mdx).
+```
+
+#### Getting Help
+
+```markdown
+### 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.
+```
+
+## Code Organization Guidelines
+
+### File Paths
+
+- Always use absolute paths or paths relative to the workspace root
+- Use `src/` prefix for source files
+- Specify file paths clearly in code block titles
+
+### Naming Conventions
+
+- Use descriptive variable and function names
+- Follow TypeScript/JavaScript conventions
+- Use camelCase for variables and functions
+- Use PascalCase for components and classes
+
+### Code Comments
+
+- Add comments explaining complex logic
+- Use highlights arrays to explain important lines
+- Include context about why code is structured a certain way
+
+## Content Guidelines
+
+### Clarity
+
+- Write in second person ("you'll learn", "you'll create")
+- Use active voice
+- Be specific and concrete
+- Avoid jargon without explanation
+
+### Completeness
+
+- Include all necessary code
+- Explain each step thoroughly
+- Provide context for decisions
+- Include error handling where relevant
+
+### Consistency
+
+- Use consistent terminology throughout
+- Follow the same structure for similar steps
+- Use the same formatting for code blocks
+- Maintain consistent tone
+
+## Common Patterns
+
+### Module Creation Steps
+
+1. Create module directory
+2. Create data models
+3. Create module service
+4. Export module definition
+5. Add module to config
+6. Generate migrations
+
+### Workflow Creation Steps
+
+1. Create workflow steps
+2. Create workflow
+3. Create API route (if needed)
+4. Add middleware (if needed)
+5. Test
+
+### Storefront Customization Steps
+
+1. Add types/interfaces
+2. Add data fetching functions
+3. Create components
+4. Integrate into existing pages
+5. Test
+
+## Checklist for Tutorial Creation
+
+- [ ] Frontmatter with all required fields
+- [ ] Metadata export
+- [ ] Title section
+- [ ] Context paragraph
+- [ ] Summary section
+- [ ] Step 1: Install Medusa Application
+- [ ] Subsequent steps with clear titles
+- [ ] Code blocks with proper formatting
+- [ ] Highlights arrays for important code
+- [ ] Notes and Tips where helpful
+- [ ] Test sections after major implementations
+- [ ] Workflow diagrams for workflows
+- [ ] Links to documentation using special syntax
+- [ ] Next Steps section
+- [ ] Optional: Troubleshooting section
+- [ ] Optional: Getting Help section
+- [ ] All code examples are complete and runnable
+- [ ] File paths are correct
+- [ ] Badge labels for storefront vs server code
+- [ ] Consistent formatting throughout
+
+## Special Considerations
+
+### Storefront vs Server Code
+
+- Always use badge labels to distinguish storefront and server code
+- Storefront code: `badgeLabel="Storefront" badgeColor="blue"`
+- Server code: `badgeLabel="Medusa Application" badgeColor="green"`
+
+### Workflow Documentation
+
+- Always include WorkflowDiagram for complex workflows
+- Explain each step clearly
+- Show the flow of data
+- Include compensation functions when relevant
+
+### API Routes
+
+- Show request/response examples
+- Include authentication requirements
+- Show middleware configuration
+- Include validation schemas
+
+### Admin Customizations
+
+- Show UI route or widget creation
+- Include configuration exports
+- Show how to test in admin dashboard
+
+## Examples of Good Tutorial Structure
+
+### Example Step
+
+```markdown
+## Step 2: Create Custom Module
+
+In this step, you'll create a custom module to [purpose].
+
+<Note>
+
+Refer to the [Modules documentation](!docs!/learn/fundamentals/modules) to learn more.
+
+</Note>
+
+### Create Module Directory
+
+Modules are created under the `src/modules` directory. So, create the directory `src/modules/custom-module`.
+
+### Create Data Models
+
+[Explanation of data models...]
+
+\`\`\`ts title="src/modules/custom-module/models/model.ts"
+[code]
+\`\`\`
+
+[Explanation of code...]
+
+### Test it Out
+
+To test [feature]:
+
+\`\`\`bash npm2yarn badgeLabel="Medusa Application" badgeColor="green"
+npm run dev
+\`\`\`
+
+[Testing instructions...]
+```
+
+## Final Notes
+
+- Always prioritize clarity and completeness
+- Include all necessary context
+- Test all code examples
+- Follow the established patterns
+- Maintain consistency with existing tutorials
+- Update this file if new patterns emerge
@@ -543,7 +543,7 @@ To create the workflow, create the file `src/workflows/sync-products.ts` with th
 import { 
  createWorkflow, 
  transform, 
-  WorkflowResponse
+  WorkflowResponse,
 } from "@medusajs/framework/workflows-sdk"
 import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 import { syncProductsStep, SyncProductsStepInput } from "./steps/sync-products"
@@ -559,11 +559,11 @@ export const syncProductsWorkflow = createWorkflow(
  "sync-products",
  ({ filters, limit, offset }: SyncProductsWorkflowInput) => {
    const productFilters = transform({
-      filters
+      filters,
    }, (data) => {
      return {
        status: ProductStatus.PUBLISHED,
-        ...data.filters
+        ...data.filters,
      }
    })
    const { data, metadata } = useQueryGraphStep({
@@ -523,7 +523,7 @@ To create the workflow, create the file `src/workflows/sync-products.ts` with th
 import { 
  createWorkflow, 
  transform, 
-  WorkflowResponse
+  WorkflowResponse,
 } from "@medusajs/framework/workflows-sdk"
 import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
 import { syncProductsStep, SyncProductsStepInput } from "./steps/sync-products"
@@ -539,11 +539,11 @@ export const syncProductsWorkflow = createWorkflow(
  "sync-products",
  ({ filters, limit, offset }: SyncProductsWorkflowInput) => {
    const productFilters = transform({
-      filters
+      filters,
    }, (data) => {
      return {
        status: ProductStatus.PUBLISHED,
-        ...data.filters
+        ...data.filters,
      }
    })
    const { data, metadata } = useQueryGraphStep({
@@ -6717,5 +6717,6 @@ export const generatedEditDates = {
  "references/core_flows/Payment/Workflows_Payment/functions/core_flows.Payment.Workflows_Payment.validateRefundPaymentExceedsCapturedAmountStep/page.mdx": "2025-11-05T12:22:20.221Z",
  "references/core_flows/Product/Workflows_Product/functions/core_flows.Product.Workflows_Product.batchImageVariantsWorkflow/page.mdx": "2025-11-05T12:22:20.639Z",
  "references/core_flows/Product/Workflows_Product/functions/core_flows.Product.Workflows_Product.batchVariantImagesWorkflow/page.mdx": "2025-11-05T12:22:20.671Z",
-  "app/storefront-development/guides/react-native-expo/page.mdx": "2025-11-06T07:18:45.347Z"
+  "app/storefront-development/guides/react-native-expo/page.mdx": "2025-11-06T07:18:45.347Z",
+  "app/how-to-tutorials/tutorials/customer-tiers/page.mdx": "2025-11-25T08:24:24.566Z"
 }
@@ -763,6 +763,10 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/how-to-tutorials/tutorials/category-images/page.mdx",
    "pathname": "/how-to-tutorials/tutorials/category-images"
  },
+  {
+    "filePath": "/www/apps/resources/app/how-to-tutorials/tutorials/customer-tiers/page.mdx",
+    "pathname": "/how-to-tutorials/tutorials/customer-tiers"
+  },
  {
    "filePath": "/www/apps/resources/app/how-to-tutorials/tutorials/first-purchase-discounts/page.mdx",
    "pathname": "/how-to-tutorials/tutorials/first-purchase-discounts"
@@ -2477,6 +2477,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
              "title": "Extend Module",
              "children": []
            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "ref",
+              "title": "Implement Customer Tiers",
+              "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers",
+              "children": []
+            },
            {
              "loaded": true,
              "isPathHref": true,
@@ -13541,6 +13549,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
              "title": "Extend Module",
              "children": []
            },
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "ref",
+              "title": "Implement Customer Tiers",
+              "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers",
+              "children": []
+            },
            {
              "loaded": true,
              "isPathHref": true,
@@ -460,6 +460,15 @@ const generatedgeneratedHowToTutorialsSidebarSidebar = {
          "description": "Learn how to use prices from external systems for products.",
          "children": []
        },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "title": "Customer Tiers",
+          "path": "/how-to-tutorials/tutorials/customer-tiers",
+          "description": "Learn how to implement customer tiers in your Medusa store.",
+          "children": []
+        },
        {
          "loaded": true,
          "isPathHref": true,
@@ -829,6 +829,14 @@ const generatedgeneratedToolsSidebarSidebar = {
                  "title": "Create Order Returns",
                  "children": []
                },
+                {
+                  "loaded": true,
+                  "isPathHref": true,
+                  "type": "ref",
+                  "title": "Customer Tiers",
+                  "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers",
+                  "children": []
+                },
                {
                  "loaded": true,
                  "isPathHref": true,
@@ -120,6 +120,13 @@ While tutorials show you a specific use case, they also help you understand how
        description:
          "Learn how to use prices from external systems for products.",
      },
+      {
+        type: "link",
+        title: "Customer Tiers",
+        path: "/how-to-tutorials/tutorials/customer-tiers",
+        description:
+          "Learn how to implement customer tiers in your Medusa store.",
+      },
      {
        type: "link",
        title: "First-Purchase Discounts",
@@ -15,6 +15,10 @@ export const customer = [
    "title": "Extend Customer",
    "path": "https://docs.medusajs.com/resources/commerce-modules/customer/extend"
  },
+  {
+    "title": "Implement Customer Tiers",
+    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers"
+  },
  {
    "title": "Implement First-Purchase Discount",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts"
@@ -3,6 +3,10 @@ export const nextjs = [
    "title": "Megamenu and Category Banner",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images"
  },
+  {
+    "title": "Customer Tiers",
+    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers"
+  },
  {
    "title": "First-Purchase Discount",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts"
@@ -19,6 +19,10 @@ export const promotion = [
    "title": "Extend Promotion",
    "path": "https://docs.medusajs.com/resources/commerce-modules/promotion/extend"
  },
+  {
+    "title": "Implement Customer Tiers",
+    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers"
+  },
  {
    "title": "Implement First-Purchase Discount",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts"
@@ -67,6 +67,10 @@ export const server = [
    "title": "Product Category Images",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images"
  },
+  {
+    "title": "Customer Tiers",
+    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers"
+  },
  {
    "title": "First-Purchase Discount",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts"
@@ -35,6 +35,10 @@ export const tutorial = [
    "title": "Product Category Images",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/category-images"
  },
+  {
+    "title": "Customer Tiers",
+    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/customer-tiers"
+  },
  {
    "title": "First-Purchase Discount",
    "path": "https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts"