Medusa

https://docs.medusajs.com/resources/
Admin
Medusa is an open-source commerce platform that provides modular commerce modules, workflows, and...
Tokens:8,898,804
Snippets:41,670
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Navigate and start development server

Source: https://docs.medusajs.com/resources/medusa-cli/commands/new

After creating the project, navigate to the project directory and start the development server. The example shows the commands for yarn, pnpm, and npm.

```terminal
❯cd my-medusa-store
❯yarn dev
```

```terminal
❯cd my-medusa-store
❯pnpm dev
```

```terminal
❯cd my-medusa-store
❯npm run dev
```

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

### startAuthMfa Example

Source: https://docs.medusajs.com/resources/references/auth/startAuthMfa/index.html.md

Starts MFA setup for an auth identity using the specified provider. Available from Medusa v2.15.3. Use only for complex customizations; for common cases, use available workflows.

```ts
const mfaSetup = await authModuleService.startAuthMfa({
  auth_identity_id: "authusr_123",
  provider: "totp",
  label: "My App",
  issuer: "MyCompany"
})
```

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

### Setup database with db:setup

Source: https://docs.medusajs.com/resources/medusa-cli/commands/db

Creates the database and runs all migrations. Use after dropping the database to reinitialize it. Replace `<db_name>` with your database name.

```bash
npx medusa db:setup --db <db_name>
```

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

### Example response for starting MFA enrollment

Source: https://docs.medusajs.com/resources/commerce-modules/auth/mfa/index.html.md

Example JSON response from the start enrollment request. It contains the new factor in `pending` status, the `secret`, and the `otpauth_url` that the client typically renders as a QR code.

```json
{
  "mfa_factor": { "id": "authmfa_...", "status": "pending", ... },
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/My%20Store:user@example.com?secret=..."
}
```

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

### Navigate and start development server

Source: https://docs.medusajs.com/resources/medusa-cli/commands/new/index.html.md

Commands to navigate into the newly created project directory and start the development server.

```bash
cd my-medusa-store
npm run dev
```

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

### start(data, sharedContext?)

Source: https://docs.medusajs.com/resources/references/auth/mfa-module-provider/index.html.md

Documentation for the start method of the AuthMfaProvider interface, which initiates the MFA setup process.

```APIDOC
## start(data, sharedContext?)

### Description
Starts the multi-factor authentication (MFA) setup process for an authentication identity. This method generates a secret, creates a pending MFA factor, and returns the MFA details along with the secret and OTP authentication URL.

### Method
start

### Parameters

#### data (AuthMfaStartDTO) - Required
- **auth_identity_id** (string) - Required - The ID of the authentication identity to set up multi-factor authentication (MFA) for.
- **provider** (AuthMfaProviderMethod) - Required - The multi-factor authentication (MFA) provider to use.
- **label** (string | null) - Optional - Optional label for the multi-factor authentication (MFA) configuration.
- **issuer** (string) - Optional - The issuer name for time-based one-time password (TOTP) apps.
- **metadata** (Record<string, unknown> | null) - Optional - Additional metadata for the multi-factor authentication (MFA) setup.

#### sharedContext (Context) - Optional
- **transactionManager** (TManager) - Optional - An instance of a transaction manager of type `TManager`, which is a typed parameter passed to the context to specify the type of the `transactionManager`.
- **manager** (TManager) - Optional - An instance of a manager, typically an entity manager, of type `TManager`, which is a typed parameter passed to the context to specify the type of the `manager`.
- **isolationLevel** (string) - Optional - A string indicating the isolation level of the context. Possible values are `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, or `SERIALIZABLE`.
- **enableNestedTransactions** (boolean) - Optional - A boolean value indicating whether nested transactions are enabled.
- **eventGroupId** (string) - Optional - A string indicating the ID of the group to aggregate the events to be emitted at a later point.
- **transactionId** (string) - Optional - A string indicating the ID of the current transaction.
- **runId** (string) - Optional - A string indicating the ID of the current run.
- **messageAggregator** (IMessageAggregator) - Optional - An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.
- **requestId** (string) - Optional - A string indicating the ID of the current request.
- **idempotencyKey** (string) - Optional - A string indicating the idempotencyKey of the current workflow execution.
- **parentStepIdempotencyKey** (string) - Optional - A string indicating the idempotencyKey of the parent workflow execution.
- **preventReleaseEvents** (boolean) - Optional - preventReleaseEvents
- **isCancelling** (boolean) - Optional - A boolean value indicating whether the current workflow execution is being cancelled.
- **cancelingFromParentStep** (boolean) - Optional - Weither or not a sub workflow cancellation is being triggered from a parent step. If true, the parent step will not be triggered by the sub workflow.

### Returns
- **AuthMfaStartResponse** - The response containing the MFA factor details, the generated secret, and the OTP authentication URL.
```

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

### Example prompts for building storefront features

Source: https://docs.medusajs.com/resources/storefront-development/index.html.md

Example prompts to use with the plugin's skills. The first prompt asks for a full storefront with product listing, detail, cart, and checkout pages; the second asks for a responsive megamenu in the header.

```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 Medusa ecommerce-storefront plugin in Claude Code

Source: https://docs.medusajs.com/resources/storefront-development

Install the Medusa ecommerce-storefront plugin in Claude Code. Start Claude Code, add the plugin marketplace, then install the ecommerce-storefront skill.

```Terminal
❯claude # start claude code
❯/plugin marketplace add medusajs/medusa-agent-skills
❯/plugin install ecommerce-storefront@medusa
```

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

### Change to storefront directory

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/first-purchase-discounts/index.html.md

Navigate to the Next.js Starter Storefront directory in the project.

```bash
cd apps/storefront
```

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

### Install @medusajs/draft-order plugin

Source: https://docs.medusajs.com/resources/commerce-modules/order/draft-orders

Install the Draft Orders Plugin in your Medusa application. The plugin is available starting v2.10.0; for earlier versions, install it manually. Requires a Medusa application version >= v2.4.0.

```bash
yarn add @medusajs/draft-order
```

```bash
pnpm add @medusajs/draft-order
```

```bash
npm add @medusajs/draft-order
```

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

### setCalculatedShippingPricingContext hook: minimal example

Source: https://docs.medusajs.com/resources/references/medusa-workflows/calculateShippingOptionsPricesWorkflow/index.html.md

A minimal example of consuming the hook, with a TODO placeholder for custom logic. Use this as a starting point for implementing your own context.

```typescript
import { calculateShippingOptionsPricesWorkflow } from "@medusajs/medusa/core-flows"

calculateShippingOptionsPricesWorkflow.hooks
  .setCalculatedShippingPricingContext(
    (async ({}, { container }) => {
      //TODO
    })
  )
```

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

### Install Medusa with create-medusa-app

Source: https://docs.medusajs.com/resources/integrations/guides/algolia

Run this command in your terminal to install the Medusa application. You will be prompted for the project name and whether to install the Next.js Starter Storefront; choose "Yes" to include it. The installation creates a monorepository with the backend in `apps/backend` and the storefront in `apps/storefront`.

```Terminal
❯npx create-medusa-app@latest
```

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

### start

Source: https://docs.medusajs.com/resources/references/auth/mfa-module-provider/index.html.md

Method to initiate the MFA setup flow for an auth identity.

```APIDOC
## start

### Description
Initiates the MFA setup flow for an auth identity. It typically creates a pending factor and returns the data the user needs in order to complete the setup, such as a TOTP secret and `otpauth_url` that can be rendered as a QR code.

### Method
start

### Parameters

No parameters are documented in the source.
```

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

### Install Medusa app with Next.js Starter

Source: https://docs.medusajs.com/resources/nextjs-starter/index.html.md

Run this command to install both the Medusa application and the Next.js Starter storefront in a monorepo. You'll be prompted for the project name. The backend is placed in apps/backend and the storefront in apps/storefront. After installation, the admin opens at http://localhost:9000/app and the storefront runs at http://localhost:8000.

```bash
npx create-medusa-app@latest --with-nextjs-starter
```

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

### Start the backend and storefront for testing localized product details

Source: https://docs.medusajs.com/resources/integrations/guides/contentful/index.html.md

Run the backend and Next.js storefront in separate terminals to test the implementation, then navigate to the site and select a different locale to see localized product titles and descriptions.

```bash
npm run dev

npm run dev
```

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

### start() method: create pending factor

Source: https://docs.medusajs.com/resources/references/auth/mfa-module-provider

Initiates the MFA setup flow by creating a pending factor and returning the secret and otpauth_url needed to complete setup.

```TypeScript
class MyAuthMfaProvider implements AuthMfaProvider {
  // ...
  async start(
    data: AuthTypes.AuthMfaStartDTO,
    sharedContext?: Context
  ): Promise<AuthTypes.AuthMfaStartResponse> {
    const secret = this.generateSecret_()
    const factor = await this.authMfaFactorService_.create(
      {
        auth_identity_id: data.auth_identity_id,
        provider: this.method,
        status: "pending",
        provider_metadata: { secret },
      },
      sharedContext
    )

    return {
      mfa: await this.serializeFactor_(factor),
      secret,
      otpauth_url: this.buildOtpAuthUrl_(secret, data),
    }
  }
}
```

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

### Start the Medusa application to test the webhook listener

Source: https://docs.medusajs.com/resources/integrations/guides/contentful/index.html.md

Use this command to launch the Medusa app, enabling you to test the webhook integration by updating a product's title in Contentful and observing the synchronized change in Medusa before moving on to further customizations. Requires a prior setup of the integration as described in the guide; expects npm installed and dependencies available in the project root, outputting logs indicating the server is running, and allowing interruption with Ctrl+C when done testing. Note that failure to see the update suggests troubleshooting steps may be necessary, referencing provided resources if needed; ensure no conflicting processes are using the default port, as startup may fail otherwise, and remember to restart after any subsequent code changes to ensure the latest version is tested, as stale builds can lead to unexpected behavior; additionally, verify network permissions if accessing remotely, and consult the troubleshooting guide if encountering issues during development, as unresolved errors may require checking logs for clues; finally, consider deploying to a cloud service for production use, though this command is intended for local development only, and remember to revert any test changes before continuing with further development tasks, as lingering edits could interfere with upcoming steps; moreover,

```npm run dev
```bash

```
```

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

### Start Medusa and Storefront, and Verify Order Placed Log

Source: https://docs.medusajs.com/resources/integrations/guides/resend/index.html.md

Commands to start the Medusa application and the Next.js Starter Storefront, followed by the expected log message after placing an order. The first two commands are run in different directories: the Medusa app root and the storefront's `apps/storefront` directory. The log confirms the `order.placed` event was processed by its subscriber.

```bash
npm run dev
```

```bash
npm run dev
```

```bash
info:    Processing order.placed which has 1 subscribers
```

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

### Start product import from an API route

Source: https://docs.medusajs.com/resources/references/medusa-workflows/importProductsAsChunksWorkflow

Example of starting the importProductsAsChunksWorkflow from an API route. The workflow returns a transaction ID that must be used to confirm the import afterwards.

```typescript
import type {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { importProductsAsChunksWorkflow } from "@medusajs/medusa/core-flows"

export async function POST(
  req: MedusaRequest,
  res: MedusaResponse
) {
  const { result, transaction } = await importProductsAsChunksWorkflow(req
      .scope)
    .run({
      input: {
        filename: "products.csv",
        fileKey: "products.csv",
      }
    })

  res.send(result)
}
```

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

### Start Strapi development server

Source: https://docs.medusajs.com/resources/integrations/guides/strapi

Starts Strapi in development mode and opens the admin panel setup page in your default browser, where you can create a new admin user.

```Terminal
❯npm run dev
```
Tokens:
Raw