Medusa Integrations

https://docs.medusajs.com/resources/integrations
Admin
Medusa Integrations documentation provides guides for integrating third-party services including...
Tokens:147,959
Snippets:1,635
Trust Score:9.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install react-markdown

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

Install the dependency required to render markdown product descriptions.

```bash
npm install react-markdown
```

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

### Start Development Servers

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

Commands to start the Medusa backend and the Next.js storefront.

```bash
npm run dev
```

```bash
npm run dev
```

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

### Install Strapi Client

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

Install the Strapi client package in your Medusa backend directory.

```bash
npm install @strapi/client
```

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

### Start Development Servers

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

Commands to start the Strapi and Medusa development servers for testing the integration.

```bash
npm run develop
```

```bash
npm run dev
```

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

### Install Contentful SDKs

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

Install the required Contentful management and delivery SDKs in your backend directory.

```bash
npm install contentful contentful-management
```

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

### Install Meilisearch Dependencies

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

Install the required Meilisearch and React InstantSearch packages.

```bash
npm install @meilisearch/instant-meilisearch react-instantsearch
```

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

### Install Algolia Dependencies

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

Install the necessary Algolia search client and React InstantSearch libraries.

```bash
npm install algoliasearch react-instantsearch
```

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

### Install Meilisearch Client

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

Installs the Meilisearch JavaScript client dependency in the project root.

```bash
npm install meilisearch
```

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

### Install Medusa Application

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

Use this command to initialize a new Medusa project including the backend and storefront.

```bash
npx create-medusa-app@latest
```

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

### Start Medusa Development Server

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

Run this command in the apps/backend directory to start the application and initialize OpenTelemetry instrumentation.

```bash
npm run dev
```

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

### Start Medusa Application

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

Command to launch the Medusa development server.

```bash
npm run dev
```

```yarn
yarn dev
```

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

### Install PayPal React SDK

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

Install the necessary dependency for integrating PayPal components into the React storefront.

```bash
npm install @paypal/react-paypal-js
```

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

### Install Axios dependency

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

Install the Axios library to handle HTTP requests to the Slack API.

```bash
npm install axios
```

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

### Install Payload dependencies

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

Install the required Payload CMS packages in the storefront directory.

```bash
npm install payload @payloadcms/next @payloadcms/richtext-lexical sharp @payloadcms/db-postgres graphql
```

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

### Install Segment Node SDK

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

Install the required Segment Node SDK dependency in the backend directory.

```bash
npm install @segment/analytics-node
```

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

### Initialize Sanity CLI

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

Run this command within the storefront directory to start the Sanity configuration wizard.

```bash
npx sanity@latest init
```

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

### Install Contentful Node Apps Toolkit

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

Install the required package for verifying Contentful webhook requests.

```bash
npm install @contentful/node-apps-toolkit
```

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

### Publish plugin to local registry

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

Run this command in the plugin directory to make it available for local installation.

```bash
npx medusa plugin:publish
```

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

### Install Payload dependencies

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

Install the required Payload CMS packages and database drivers in the storefront directory.

```bash
npm install payload @payloadcms/next @payloadcms/richtext-lexical sharp @payloadcms/db-postgres graphql
```

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

### Re-install dependencies

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

Run the install command again to apply the package.json resolutions.

```bash
npm install
```

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

### Install Contentful Rich Text Package

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

Installs the necessary package for rendering Contentful rich-text fields in the storefront.

```bash
npm install @contentful/@contentful/rich-text-types
```

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

### Verify Sync Event Logs

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

Example log output confirming that the product synchronization event has been triggered.

```bash
info:    Processing products.sync-payload which has 1 subscribers
```

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

### Install Sentry Dependencies

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

Install the required Sentry and OpenTelemetry packages for Medusa instrumentation.

```bash
npm install @sentry/node @opentelemetry/api @opentelemetry/exporter-trace-otlp-grpc @sentry/opentelemetry-node @opentelemetry/core@1.x @opentelemetry/sdk-trace-base@1.x @opentelemetry/semantic-conventions@1.x
```

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

### Install Sanity Client SDK

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

Installs the Sanity JavaScript client SDK within the backend directory of the Medusa project.

```bash
cd apps/backend
npm install @sanity/client
```

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

### Install Sentry and OpenTelemetry Dependencies

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

Install the required packages for Sentry and OpenTelemetry instrumentation via npm or yarn.

```bash
npm install @sentry/node @opentelemetry/api @opentelemetry/exporter-trace-otlp-grpc @sentry/opentelemetry-node @opentelemetry/core@1.x @opentelemetry/sdk-trace-base@1.x @opentelemetry/semantic-conventions@1.x
```

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

### Install plugin in Medusa application

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

Execute this command within the backend directory to add the local plugin to the Medusa project.

```bash
npx medusa plugin:add medusa-plugin-magento
```

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

### Example Product Object Structure

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

Represents the expected structure of a product object retrieved via the Query graph method with attached Sanity data.

```json
{
  "id": "prod_123",
  "title": "Shirt",
  "sanity_product": {
    "id": "prod_123",
    "_type": "product",
    // other Sanity fields...
  }
}
```

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

### Navigate to Storefront Directory

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

Command to change the working directory to the Next.js storefront.

```bash
cd apps/storefront
```

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

### Install Algolia JavaScript Client

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

Run this command in the root directory of your Medusa application to install the necessary dependency.

```bash
npm install algoliasearch
```

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

### Create a new Medusa plugin project

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

Run this command in a directory separate from your main Medusa application to initialize the plugin structure.

```bash
npx create-medusa-app@latest medusa-plugin-magento --plugin
```

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

### Initialize Search Client

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

Export the search client initialized with environment variables.

```typescript
export const { searchClient } = instantMeiliSearch(
  process.env.NEXT_PUBLIC_MEILISEARCH_HOST || "",
  process.env.NEXT_PUBLIC_MEILISEARCH_API_KEY || ""
)
```

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

### Install Sanity Peer Dependencies

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

Use this command to manually resolve installation errors related to missing or incompatible peer dependencies.

```bash
yarn add next-sanity@9.8.15 @sanity/client@^6.22.4 @sanity/icons@^3.4.0 @sanity/types@^3.62.0 @sanity/ui@^2.8.10 next@^15.0.0 react@^19.0.0 react-dom@^19.0.0 sanity@^3.62.0 styled-components@^6.1
```

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

### Create GET API route for Sanity documents

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

Defines an admin-protected GET route to retrieve a Sanity document and its corresponding studio URL by ID.

```typescript
import { 
  MedusaRequest, 
  MedusaResponse,
} from "@medusajs/framework/http"
import SanityModuleService from "src/modules/sanity/service"
import { SANITY_MODULE } from "../../../../../modules/sanity"

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  const { id } = req.params

  const sanityModule: SanityModuleService = req.scope.resolve(
    SANITY_MODULE
  )
  const sanityDocument = await sanityModule.retrieve(id)

  const url = sanityDocument ? 
    await sanityModule.getStudioLink(
      sanityDocument._type,
      sanityDocument._id,
      { explicit_type: true }
    )
    : ""

  res.json({ sanity_document: sanityDocument, studio_url: url })
}
```

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

### Sync Terminal Output

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

Example log message indicating successful synchronization of products.

```bash
info: Synced 4 products to Contentful
```

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

### Navigate to Strapi directory

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

Change the current working directory to the newly created Strapi project folder.

```bash
cd my-strapi-app
```

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

### Fetch Store and Shipping Profile Data

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

Use useQueryGraphStep to retrieve necessary store configuration and shipping profiles for product creation.

```ts
const { data: stores } = useQueryGraphStep({
  entity: "store",
  fields: ["supported_currencies.*", "default_sales_channel_id"],
  pagination: {
    take: 1,
    skip: 0,
  },
})

const { data: shippingProfiles } = useQueryGraphStep({
  entity: "shipping_profile",
  fields: ["id"],
  pagination: {
    take: 1,
    skip: 0,
  },
}).config({ name: "get-shipping-profiles" })

// TODO retrieve existing products
```

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

### Manage Locale Cookies

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

Functions to get and set the selected locale in browser cookies for the storefront.

```typescript
export const getLocale = async () => {
  const cookies = await nextCookies()
  return cookies.get("_medusa_locale")?.value
}

export const setLocale = async (locale: string) => {
  const cookies = await nextCookies()
  cookies.set("_medusa_locale", locale, {
    maxAge: 60 * 60 * 24 * 7,
  })
}
```

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

### Initialize Migrate Products Workflow

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

Define the workflow structure and input parameters for migrating products from Magento.

```ts
import { 
  createWorkflow, transform, WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"
import { 
  CreateProductWorkflowInputDTO, 
  CreateProductOptionDTO, 
  UpsertProductDTO,
} from "@medusajs/framework/types"
import { 
  createProductsWorkflow, 
  createProductOptionsWorkflow,
  updateProductsWorkflow, 
  useQueryGraphStep,
} from "@medusajs/medusa/core-flows"
import { getMagentoProductsStep } from "./steps/get-magento-products"
import { MagentoAttribute } from "../modules/magento/types"

type MigrateProductsFromMagentoWorkflowInput = {
  currentPage: number
  pageSize: number
}

export const migrateProductsFromMagentoWorkflowId = 
  "migrate-products-from-magento"

export const migrateProductsFromMagentoWorkflow = createWorkflow(
  {
    name: migrateProductsFromMagentoWorkflowId,
    retentionTime: 10000,
    store: true,
  },
  (input: MigrateProductsFromMagentoWorkflowInput) => {
    const { pagination, products, attributes } = getMagentoProductsStep(
      input
    )
    // TODO prepare data to create and update products
  }
)
```

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

### Verify Module Connection

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

Expected terminal output upon successful module initialization.

```bash
info:    Connected to Contentful
```

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

### Get Variant Option Values

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

Retrieves all option values for a variant, using Strapi labels where available.

```typescript
export function getVariantOptionValues(
  variant: HttpTypes.StoreProductVariant,
  product: HttpTypes.StoreProduct
): Array<{ optionTitle: string; value: string }> {
  if (!variant.options || variant.options.length === 0) {
    return []
  }

  return variant.options
    .filter((opt) => opt.option_id && opt.id)
    .map((opt) => {
      const option = product.options?.find((o) => o.id === opt.option_id)
      const optionTitle = option
        ? getOptionTitle(option, product)
        : ""
      const value = getOptionValueText(
        { id: opt.id, option_id: opt.option_id!, value: opt.value! },
        product
      )
      return { optionTitle, value }
    })
    .filter((opt) => opt.optionTitle && opt.value)
}
```

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

### Execute Product Creation and Update Workflows

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

Use the createProductsWorkflow and updateProductsWorkflow to process the migration data. Ensure the workflow returns a WorkflowResponse containing pagination parameters.

```ts
createProductsWorkflow.runAsStep({
  input: {
    products: productsToCreate,
  },
})

updateProductsWorkflow.runAsStep({
  input: {
    products: productsToUpdate,
  },
})

return new WorkflowResponse(pagination)
```

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

### Execute Magento product retrieval request

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

Sends a GET request to the Magento REST API with authorization headers.

```ts
const { items: products, ...pagination }: MagentoPaginatedResponse<MagentoProduct> = await fetch(
  `${this.options.baseUrl}/rest/${this.options.storeCode}/V1/products?${searchQuery}`, 
  {
    headers: {
      "Authorization": `Bearer ${this.accessToken.token}`,
    },
  }
).then((res) => res.json())
.catch((err) => {
  console.log(err)
  throw new MedusaError(
    MedusaError.Types.INVALID_DATA, 
    `Failed to get products from Magento: ${err.message}`
  )
})

// TODO prepare products
```

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

### Create product options in Strapi step

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

Implements a workflow step that iterates through product options and creates them in Strapi, with a compensation function to handle rollbacks on failure.

```ts
import { createStep, StepResponse } from "@medusajs/framework/workflows-sdk"
import { STRAPI_MODULE } from "../../modules/strapi"
import StrapiModuleService, { Collection } from "../../modules/strapi/service"

export type CreateOptionsInStrapiInput = {
  options: {
    id: string
    title: string
  }[]
}

export const createOptionsInStrapiStep = createStep(
  "create-options-in-strapi",
  async ({ options }: CreateOptionsInStrapiInput, { container }) => {
    const strapiService: StrapiModuleService = container.resolve(STRAPI_MODULE)

    const results: Record<string, any>[] = []

    try {
      for (const option of options) {
        const strapiOption = await strapiService.create(
          Collection.PRODUCT_OPTIONS, 
          {
            medusaId: option.id,
            title: option.title,
          }
        )

        results.push(strapiOption.data)
      }
    } catch (error) {
      // If error occurs during loop,
      // pass results created so far to compensation
      return StepResponse.permanentFailure(
        strapiService.formatStrapiError(
          error, 
          "Failed to create options in Strapi"
        ),
        { results }
      )
    }

    return new StepResponse(
      results,
      results
    )
  },
  async (compensationData, { container }) => {
    if (!compensationData) {
      return
    }

    const strapiService: StrapiModuleService = container.resolve(STRAPI_MODULE)

    // Delete all created options
    for (const result of compensationData) {
      await strapiService.delete(Collection.PRODUCT_OPTIONS, result.documentId)
    }
  }
)
```

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

### Configure Contentful Environment Variables

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

Add these variables to your .env file to authenticate and connect to your Contentful space.

```plain
CONTENTFUL_MANAGEMNT_ACCESS_TOKEN=CFPAT-...
CONTENTFUL_DELIVERY_TOKEN=eij...
CONTENTFUL_SPACE_ID=t2a...
CONTENTFUL_ENVIRONMENT=master
```

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

### Retrieve product images in Product Template

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

Call the utility function to get images before the component return statement.

```tsx
const ProductTemplate: React.FC<ProductTemplateProps> = ({
  product,
  region,
  countryCode,
}) => {
  // ...
  const productImages = getProductImages(product)
  // ...
}
```

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

### Create a new Strapi project

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

Run this command in a directory separate from your Medusa application to initialize a new Strapi project.

```bash
npx create-strapi@latest my-strapi-app
```

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

### Create API Route for Locales

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

Exposes a GET endpoint at /store/locales that returns formatted locale data from Contentful.

```typescript
import {
  MedusaRequest,
  MedusaResponse,
} from "@medusajs/framework/http"
import { CONTENTFUL_MODULE } from "../../../modules/contentful"
import ContentfulModuleService from "../../../modules/contentful/service"

export const GET = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  const contentfulModuleService: ContentfulModuleService = req.scope.resolve(
    CONTENTFUL_MODULE
  )

  const locales = await contentfulModuleService.getLocales()
  const defaultLocaleCode = await contentfulModuleService.getDefaultLocaleCode()

  const formattedLocales = locales.items.map((locale) => {
    return {
      name: locale.name,
      code: locale.code,
      is_default: locale.code === defaultLocaleCode,
    }
  })

  res.json({
    locales: formattedLocales,
  })
}
```
Tokens:
Raw