Medusa

https://docs.medusajs.com/
Admin
Medusa is an open-source, headless commerce platform designed for building highly customizable and...
Tokens:11,601,809
Snippets:55,182
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Navigate to project 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 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"
})
```

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

### Example Response for Start Enrollment

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

Example JSON response from the start enrollment request. Contains the pending MFA factor, 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=..."
}
```

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

### Recreate database with db:setup

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

Runs db:setup to create the database and run all migrations after dropping it manually.

```bash
❯yarn medusa db:setup --db <db_name>
```

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

### GET /hello-world

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

Example of a GET API route that reads a query parameter from the request.

```APIDOC
## [GET] /hello-world

### Description
Access query parameters in the `query` property of the `MedusaRequest` object. The example returns a message using the `name` query parameter.

### Method
GET

### Endpoint
/hello-world

### Parameters
#### Query Parameters
- **name** (string) - Optional - The name to include in the response message.

### Request Example
GET /hello-world?name=John

### Response
#### Success Response (200)
- **message** (string) - The response message containing the provided name.

#### Response Example
{
  "message": "Hello John"
}
```

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

### Install InstantSearch Adapter and Libraries

Source: https://docs.medusajs.com/resources/instantsearch

Install the adapter and InstantSearch libraries in your storefront project. Use the package manager that matches your project (yarn, pnpm, or npm). The example shows the yarn command for a Next.js storefront.

```bash
yarn add @medusajs/instantsearch-adapter react-instantsearch instantsearch.js
```

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

### 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
```

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

### Example response from GET /customs route

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

Example JSON response returned by the GET /customs API route after applying the middleware. It shows a list of posts with the default fields id and title.

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

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

### Example Response for Get Index Details

Source: https://docs.medusajs.com/api/admin/index/get-index-details.md

Example response body for the Get Index Details endpoint. Shows the structure of the metadata array with fields like id, entity, status, fields, updated_at, and last_synced_key.

```json
{
  "metadata": [
    {
      "id": "string",
      "entity": "string",
      "status": "pending",
      "fields": ["string"],
      "updated_at": "2019-08-24T14:15:22Z",
      "last_synced_key": "string"
    }
  ]
}
```

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

### Start Next.js Starter Storefront

Source: https://docs.medusajs.com/resources/how-to-tutorials/tutorials/invoice-generator/index.html.md

Commands to start the Next.js Starter Storefront from the apps/storefront directory. Run npm run dev after changing into that directory.

```bash
cd apps/storefront
```

```bash
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.
```

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

### Create demo-products.ts script (initial setup)

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

Create the file src/scripts/demo-products.ts with the initial setup: resolving the Sales Channel Module service, Logger, and Query, and initializing default data. The script is incomplete with a TODO to seed products.

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

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
}
```

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

### Claude Code prompt to start learning

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

Prompt to start the interactive learning experience in Claude Code after installing the plugin.

```bash
I want to learn Medusa.
```

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

### Example prompt: Migrate products

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

Example prompt to trigger the migration tool for Shopify products.

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

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

### Create start-storefront.sh for storefront

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

Creates a separate script for the storefront service that starts the Next.js Starter Storefront development server. Apply the same LF line endings requirement as in the previous step.

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

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

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

### Start Medusa application

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

Start the Medusa application from the .medusa/server directory. This command is run after installing dependencies and setting NODE_ENV.

```bash
yarn run start
```

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

### Run database setup commands

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

Commands to create the database and tables for the v2 project. Run the setup command with your package manager, then start the application with the dev command.

```bash
yarn medusa db:setup
```

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

### JSON output of environments get (--json)

Source: https://docs.medusajs.com/cloud/cli/commands/environments/index.html.md

Example JSON output of the `mcloud environments get --json` command.

```json
{
  "id": "<environment-id>",
  "project_id": "<project-id>",
  "handle": "<environment-handle>",
  "name": "Production",
  "type": "production",
  "default_subdomain": "trusting-soft-form",
  "custom_subdomain": "acme",
  "default_domain": "trusting-soft-form.medusajs.app",
  "custom_domain": "acme.com",
  "created_at": "2024-10-10T08:24:32.382Z",
  "updated_at": "2024-10-10T08:24:32.382Z",
  "external_id": "main",
  "status": "ready",
  "metadata": null,
  "project": {
    "id": "<project-id>",
    "name": "My Store",
    "handle": "<project-handle>",
    "region": "us-east-1",
    "organization_id": "<organization-id>",
    "repository": "myuser/my-repo",
    "root_path": "/apps/backend",
    "status": "ready",
    "created_by": "<user-id>",
    "created_at": "2024-10-10T08:24:32.382Z",
    "updated_at": "2024-10-10T08:24:32.382Z",
    "deleted_at": null,
    "metadata": {
      "arch": "arm64"
    },
    "builds": [],
    "environments": []
  },
  "builds": [],
  "deployments": [],
  "variables": [],
  "configuration": {
    "read_replica_database_url": "postgresql://<user>:<password>@<host>/<database>?channel_binding=require&sslmode=require",
    "tent_handle": "<tent-handle>",
    "s3_file_url": "https://s3.us-east-1.amazonaws.com/<bucket>",
    "s3_endpoint": "https://s3.us-east-1.amazonaws.com",
    "upstash_external_id": "<upstash-id>"
  },
  "rules": null,
  "active_deployment": null
}
```

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

### 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
```
Tokens:
Raw