Medusa

https://docs.medusajs.com/learn/
Admin
Medusa is a digital commerce platform with a built-in framework for customization, offering commerce...
Tokens:389,833
Snippets:2,643
Trust Score:9.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example prompts for ecommerce-storefront

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/agentic-skills

Example prompts to use with AI agents after installing the ecommerce-storefront plugin, covering building a storefront and adding a megamenu.

```bash
Build a Next.js ecommerce storefront that uses Medusa as the backend. The storefront should have product listing, product detail, cart, and checkout pages.
Add a megamenu to the storefront's header that displays product categories and subcategories. The menu should be responsive and work well on mobile devices.
```

--------------------------------

### Install learn-medusa Plugin in Claude Code

Source: https://docs.medusajs.com/learn/customization/custom-features

Start Claude Code and install the `learn-medusa` plugin from the `medusajs/medusa-agent-skills` marketplace to enable interactive learning.

```bash
claude # start claude code
/plugin marketplace add medusajs/medusa-agent-skills
/plugin install learn-medusa@medusa
```

--------------------------------

### Example prompts for medusa-dev

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/agentic-skills

Example prompts to use with AI agents after installing the medusa-dev plugin, covering features like product reviews, wishlist, admin widgets, and storefront integration.

```bash
Implement a product reviews feature. Authenticated customers can add reviews. Admin users can view and approve or reject reviews from the dashboard
Create a wishlist feature where customers can save products. I need API routes for adding/removing items and retrieving the wishlist.
Add a widget to the product detail page in the admin that allows managing related products. Admin users should be able to select which products are related using a searchable table.
Help me integrate the custom reviews API into my Next.js storefront. Show product reviews on the product detail page with pagination.
```

--------------------------------

### Returned Data Example

Source: https://docs.medusajs.com/learn/fundamentals/query

Example JSON response from the GET /customs API route, showing a list of posts with the specified fields.

```JSON
{
  "posts": [
    {
      "id": "123",
      "title": "test"
    }
  ]
}
```

--------------------------------

### Install and use learn-medusa skills with Claude Code

Source: https://docs.medusajs.com/learn/installation

Use these commands in Claude Code to install the `learn-medusa` skill and start an interactive learning experience. The prompt 'I want to learn Medusa.' begins the tutorial.

```bash
claude # start claude code
/plugin marketplace add medusajs/medusa-agent-skills
/plugin install learn-medusa@medusa

# then use the following prompt to start learning:
I want to learn Medusa.
```

--------------------------------

### Example JSON response from GET /admin/brands

Source: https://docs.medusajs.com/learn/customization/extend-features/query-linked-records

Example response showing the structure of the returned brands with their linked products. The response includes brand and product IDs, with other properties omitted for brevity.

```json
{
  "brands": [
    {
      "id": "123",
      // ...
      "products": [
        {
          "id": "prod_123",
          // ...
        }
      ]
    }
  ]
}
```

--------------------------------

### Install and use learn-medusa skills with other AI agents

Source: https://docs.medusajs.com/learn/installation

Use these commands to add the `learning-medusa` skill to other AI agents and start an interactive learning experience. The prompt 'I want to learn Medusa.' begins the tutorial.

```bash
npx skills add medusajs/medusa-agent-skills
# choose the following skill:
# - learning-medusa

# then use the following prompt in your AI agent to start learning:
I want to learn Medusa.
```

--------------------------------

### Install and use Medusa agent skills with Claude Code

Source: https://docs.medusajs.com/learn/installation

Use these commands in Claude Code to install the Medusa agent skills and the `medusa-dev` plugin, then ask Claude to build features like product reviews. The example prompt asks for a product reviews feature with customer and admin capabilities.

```bash
claude # start claude code
/plugin marketplace add medusajs/medusa-agent-skills
/plugin install medusa-dev@medusa

# Ask Claude Code to build features with the medusa-dev plugin. For example:
Help me implement a product reviews feature. Authenticated customers can add reviews. Admin users can view and approve or reject reviews from the dashboard
```

--------------------------------

### Start Medusa application

Source: https://docs.medusajs.com/learn/build

Start the Medusa application from the .medusa/server directory after setting NODE_ENV to production.

```bash
npm run start
```

--------------------------------

### Install Jest dependencies

Source: https://docs.medusajs.com/learn/debugging-and-testing/testing-tools

Install Jest, its types, and the SWC compiler for Jest.

```bash
npm install --save-dev jest @types/jest @swc/jest
```

--------------------------------

### Install form-data package

Source: https://docs.medusajs.com/learn/debugging-and-testing/testing-tools/integration-tests/api-routes

Run this command to install the form-data library, which is required for creating FormData objects in test requests.

```bash
npm install form-data
```

--------------------------------

### Data migration script for Blog Module

Source: https://docs.medusajs.com/learn/fundamentals/data-models/write-migration

Example data migration script that checks if the Blog Module is installed and runs a workflow to migrate data. The script must be placed in src/migration-scripts and export an async function.

```typescript
import { MedusaModule } from "@medusajs/framework/modules-sdk"
import { ExecArgs } from "@medusajs/framework/types"
import { BLOG_MODULE } from "../modules/blog"
import { createWorkflow } from "@medusajs/framework/workflows-sdk"

export default async function migrateBlogData({ container }: ExecArgs) {
  // Check that the blog module exists
  if (!MedusaModule.isInstalled(BLOG_MODULE)) {
    return
  }

  await migrateBlogDataWorkflow(container).run({})
}

const migrateBlogDataWorkflow = createWorkflow(
  "migrate-blog-data",
  () => {
    // Assuming you have these steps
    createDefaultSiteStep()

    assignBlogDataToSiteStep()
  }
)
```

--------------------------------

### Install the Index Module package

Source: https://docs.medusajs.com/learn/fundamentals/query/index-module

Run this command in your Medusa project to install the @medusajs/index package.

```bash
npm install @medusajs/index
```

--------------------------------

### Example prompts: We're switching from WooCommerce. Move our products and customers over to Medusa.

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/docs-mcp-server/migrate-from-woocommerce

A prompt to trigger the migration tool for moving products and customers from WooCommerce to Medusa.

```bash
We're switching from WooCommerce. Move our products and customers over to Medusa.
```

--------------------------------

### Create start-storefront.sh with npm

Source: https://docs.medusajs.com/learn/installation/docker

Shell script for the storefront service that starts the Next.js Starter Storefront development server using npm. Requires LF line endings.

```shell
#!/bin/sh
cd /server/apps/storefront

echo "Starting Next.js Starter Storefront development server..."
npm run dev
```

--------------------------------

### Start Medusa Application

Source: https://docs.medusajs.com/learn/customization/customize-admin/route

Run the development server to test the UI route.

```bash
npm run dev
```

--------------------------------

### Run the prep command

Source: https://docs.medusajs.com/learn/resources/contribution-guidelines/docs

Generates sidebar files and prepares data for development or production. Run this before starting the development server if you change sidebar items.

```bash
npm run prep
```

--------------------------------

### Set start command for worker mode

Source: https://docs.medusajs.com/learn/deployment/general

Use this start command if your hosting provider doesn't support setting a current-working directory. It changes to the .medusa/server directory, installs dependencies, and runs the start command.

```bash
cd .medusa/server && npm install && npm run start
```

--------------------------------

### Set Start Command for Server Mode

Source: https://docs.medusajs.com/learn/deployment/general

Start command for the Medusa application in server mode. It changes to the .medusa/server directory, installs dependencies, runs predeploy to run migrations and sync links, then starts the application.

```bash
cd .medusa/server && npm install && npm run predeploy && npm run start
```

--------------------------------

### Create start-storefront.sh with pnpm

Source: https://docs.medusajs.com/learn/installation/docker

Shell script for the storefront service that starts the Next.js Starter Storefront development server using pnpm. Requires LF line endings.

```shell
#!/bin/sh
cd /server/apps/storefront

echo "Starting Next.js Starter Storefront development server..."
pnpm dev
```

--------------------------------

### Example prompt: Migrate my WooCommerce store's products to Medusa.

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/docs-mcp-server/migrate-from-woocommerce

A prompt to trigger the migration tool for WooCommerce products.

```bash
Migrate my WooCommerce store's products to Medusa.
```

--------------------------------

### Create start-storefront.sh with yarn

Source: https://docs.medusajs.com/learn/installation/docker

Shell script for the storefront service that starts the Next.js Starter Storefront development server using yarn. Requires LF line endings.

```shell
#!/bin/sh
cd /server/apps/storefront

echo "Starting Next.js Starter Storefront development server..."
yarn dev
```

--------------------------------

### Test the GET API Route with npm run dev and curl

Source: https://docs.medusajs.com/learn/fundamentals/api-routes

Start the Medusa application with npm run dev, then send a GET request to /hello-world using curl. The expected response is a JSON object with the message field.

```bash
npm run dev
```

```bash
curl http://localhost:9000/hello-world
```

```json
{
  "message": "[GET] Hello world!"
}
```

--------------------------------

### Example prompts: Import our WooCommerce catalog into Medusa.

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/docs-mcp-server/migrate-from-woocommerce

A prompt to trigger the migration tool for importing a WooCommerce catalog.

```bash
Import our WooCommerce catalog into Medusa.
```

--------------------------------

### Create database and tables with npx medusa db:setup

Source: https://docs.medusajs.com/learn/introduction/from-v1-to-v2

Run this command to create the database and tables for your v2 project. This will not take into account entities and data customizations from your v1 project.

```bash
npx medusa db:setup
```

--------------------------------

### Set ADMIN_CORS environment variable examples

Source: https://docs.medusajs.com/learn/configurations/medusa-config

Examples of setting the ADMIN_CORS environment variable to allow different origins. The first allows localhost ports starting with 700, the second allows any origin ending with vercel.app, and the third allows all HTTP requests.

```bash
# Allow different ports locally starting with 700
ADMIN_CORS=/http:\/\/localhost:700\d+$/

# Allow any origin ending with vercel.app. For example, admin.vercel.app
ADMIN_CORS=/vercel\.app$/

# Allow all HTTP requests
ADMIN_CORS=/http:\/\/.+/

```

--------------------------------

### Example prompt for submitting feedback

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/docs-mcp-server/submit-feedback

Example prompt to ask your AI agent to submit feedback about outdated documentation on creating a custom payment provider.

```bash
Submit feedback that the documentation on how to create a custom payment provider is outdated and needs to be updated.
```

--------------------------------

### Validate module options in a loader

Source: https://docs.medusajs.com/learn/fundamentals/modules/options

Perform validation in a loader to throw an error early when the application starts. The example throws a `MedusaError` if the `apiKey` option is missing.

```ts
import { LoaderOptions } from "@medusajs/framework/types"
import { MedusaError } from "@medusajs/framework/utils"

// recommended to define type in another file
type ModuleOptions = {
  apiKey?: string
}

export default async function validationLoader({
  options,
}: LoaderOptions<ModuleOptions>) {
  if (!options.apiKey) {
    throw new MedusaError(
      MedusaError.Types.INVALID_DATA,
      "Hello Module requires an apiKey option."
    )
  }
}
```

--------------------------------

### Create start.sh with npm

Source: https://docs.medusajs.com/learn/installation/docker

Shell script for the backend service that runs database migrations, seeds the database, and starts the Medusa development server using npm. Requires LF line endings.

```shell
#!/bin/sh
cd /server/apps/backend

echo "Running database migrations..."
npx medusa db:migrate

echo "Seeding database..."
npm run seed || echo "Seeding failed, continuing..."

echo "Starting Medusa development server..."
npm run dev
```

--------------------------------

### Query example: useQuery with sdk.admin.product.list()

Source: https://docs.medusajs.com/learn/fundamentals/admin/tips

Shows how to send a GET request using the useQuery hook and the configured SDK. The widget displays a list of products and handles loading state.

```TypeScript
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { Container } from "@medusajs/ui"
import { useQuery } from "@tanstack/react-query"
import { sdk } from "../lib/sdk"

const ProductWidget = () => {
  const { data, isLoading } = useQuery({
    queryFn: () => sdk.admin.product.list(),
    queryKey: ["products"],
  })
  
  return (
    <Container className="divide-y p-0">
      {isLoading && <span>Loading...</span>}
      {data?.products && (
        <ul>
          {data.products.map((product) => (
            <li key={product.id}>{product.title}</li>
          ))}
        </ul>
      )}
    </Container>
  )
}

export const config = defineWidgetConfig({
  zone: "product.list",
})

export default ProductWidget
```

--------------------------------

### Access module options in a loader

Source: https://docs.medusajs.com/learn/fundamentals/modules/options

The object that a module's loaders receive as a parameter has an `options` property holding the module's options. The example logs the options when the application starts.

```ts
import {
  LoaderOptions,
} from "@medusajs/framework/types"

// recommended to define type in another file
type ModuleOptions = {
  capitalize?: boolean
}

export default async function helloWorldLoader({
  options,
}: LoaderOptions<ModuleOptions>) {
  
  console.log(
    "[BLOG MODULE] Just started the Medusa application!",
    options
  )
}
```

--------------------------------

### Set breadcrumb for a nested UI route

Source: https://docs.medusajs.com/learn/fundamentals/admin/ui-routes

For a nested UI route, the breadcrumb will display starting from the parent route to the nested route. This example shows a nested route under the previous one.

```tsx
import { Container, Heading } from "@medusajs/ui"

const NestedCustomPage = () => {
  return (
    <Container className="divide-y p-0">
      <div className="flex items-center justify-between px-6 py-4">
        <Heading level="h2">This is my nested custom route</Heading>
      </div>
    </Container>
  )
}

export default NestedCustomPage

export const handle = {
  breadcrumb: () => "Nested Custom Route",
}
```

--------------------------------

### Access VITE_ environment variable in a widget

Source: https://docs.medusajs.com/learn/fundamentals/admin/environment-variables

Use import.meta.env.VITE_MY_API_KEY to access an environment variable starting with VITE_ in a Medusa admin widget. The example displays the API key in a Container with a Heading.

```tsx
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { Container, Heading } from "@medusajs/ui"

const ProductWidget = () => {
  return (
    <Container className="divide-y p-0">
      <div className="flex items-center justify-between px-6 py-4">
        <Heading level="h2">API Key: {import.meta.env.VITE_MY_API_KEY}</Heading>
      </div>
    </Container>
  )
}

export const config = defineWidgetConfig({
  zone: "product.details",
})

export default ProductWidget
```

--------------------------------

### Prompt the migration agent to migrate Shopify products

Source: https://docs.medusajs.com/learn/introduction/build-with-llms-ai/docs-mcp-server/migrate-from-shopify

Example prompts to trigger the migration tool. The tool detects intentage and applies the appropriate migration approach.

```bash
Migrate my Shopify store's products to Medusa.
```

```bash
Import our Shopify catalog into Medusa.
```

```bash
We're switching from Shopify. Move our products and customers over to Medusa.
```

--------------------------------

### Example workflow with store and retentionTime options

Source: https://docs.medusajs.com/learn/debugging-and-testing/debug-workflows

This workflow stores its executions by setting 'store: true' and 'retentionTime: 99999' in the createWorkflow options. Requires the Redis Workflow Engine to be installed and configured.

```TypeScript
import { 
  createStep, 
  createWorkflow, 
  StepResponse, 
  WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"

const step1 = createStep(
  "step-1",
  async () => {
    const message = "Hello from step 1!"

    return new StepResponse(
      message
    )
  }
)

export const myWorkflow = createWorkflow(
  {
    name: "my-workflow",
    retentionTime: 99999,
    store: true,
  },
  () => {
    const response = step1()

    return new WorkflowResponse({
      response,
    })
  }
)
```

--------------------------------

### Resolve Module with Generated Types

Source: https://docs.medusajs.com/learn/fundamentals/generated-types

Use the generated types to get auto-completion and type checking when resolving modules from the Medusa container. For example, if you have a Brand Module, you can access its methods with type safety.

```ts
const brandModuleService = req.scope.resolve("brand")

// brandModuleService has the correct type, so you can access its methods with auto-completion and type checking
const brand = await brandModuleService.retrieveBrand("brand_123")
```

--------------------------------

### Query with Generated Types

Source: https://docs.medusajs.com/learn/fundamentals/generated-types

Use the generated types to get auto-completion and type checking when querying data models with Query. For example, if you have a Brand data model, you can access its properties with type safety.

```ts
const { data: [brand] } = await query.graph({
  entity: "brand",
  fields: ["*"],
  filters: {
    id: "brand_123",
  },
})

// brands has the correct type, so you can access its properties with auto-completion and type checking
console.log(brand.name)
```

--------------------------------

### Sample output from custom logger

Source: https://docs.medusajs.com/learn/debugging-and-testing/logging/custom-logger

Example logs displayed when using the custom logger implementation that logs to the console with prefixes.

```bash
INFO: Watching filesystem to reload dev server on file change
WARN: Local Event Bus installed. This is not recommended for production.
```

--------------------------------

### Export the validation loader in the module's definition file

Source: https://docs.medusajs.com/learn/fundamentals/modules/options

Export the loader in the module's definition file so it runs when the Medusa application starts. The example shows importing the loader and adding it to the `loaders` array.

```ts
// other imports...
import validationLoader from "./loaders/validate"

export const BLOG_MODULE = "blog"

export default Module(BLOG_MODULE, {
  // ...
  loaders: [validationLoader],
})
```

--------------------------------

### Run migrations and start application

Source: https://docs.medusajs.com/learn/fundamentals/query/index-module

Commands to run the database migrations and start the Medusa application, required before the Index Module can sync the custom data model.

```bash
npx medusa db:migrate
```

```bash
npm run dev
```

--------------------------------

### Create demo-products.ts script

Source: https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/seed-data

Initial script file that resolves the sales channel, logger, and query, and initializes default data. The TODO comment is replaced in subsequent steps.

```typescript
import { ExecArgs } from "@medusajs/framework/types"
import { faker } from "@faker-js/faker"
import { 
  ContainerRegistrationKeys, 
  Modules, 
  ProductStatus,
} from "@medusajs/framework/utils"
import { 
  createInventoryLevelsWorkflow,
  createProductsWorkflow,
} from "@medusajs/medusa/core-flows"

export default async function seedDummyProducts({
  container,
}: ExecArgs) {
  const salesChannelModuleService = container.resolve(
    Modules.SALES_CHANNEL
  )
  const logger = container.resolve(
    ContainerRegistrationKeys.LOGGER
  )
  const query = container.resolve(
    ContainerRegistrationKeys.QUERY
  )

  const defaultSalesChannel = await salesChannelModuleService
    .listSalesChannels({
      name: "Default Sales Channel",
    })

  const sizeOptions = ["S", "M", "L", "XL"]
  const colorOptions = ["Black", "White"]
  const currency_code = "eur"
  const productsNum = 50

  // TODO seed products
}
```

--------------------------------

### Create integration-tests/setup.js

Source: https://docs.medusajs.com/learn/debugging-and-testing/testing-tools

Setup file that clears MikroORM metadata. For Medusa versions before v2.11.0, change the require to '@mikro-orm/core'.

```js
const { MetadataStorage } = require("@medusajs/framework/mikro-orm/core")

MetadataStorage.clear()
```
Tokens:
Raw