Integrate Strapi (CMS) with Medusa

In this tutorial, you'll learn how to integrate Strapi with Medusa.

When you install a Medusa application, you get a fully-fledged commerce platform with a Framework for customization. Medusa also facilitates integrating third-party services that enrich your application with features specific to your unique business use case.

By integrating Strapi, you can manage your products' content with powerful content management capabilities, including custom fields, media, localization, and more.

Summary#

By following this tutorial, you'll learn how to:

• Install and set up Medusa.
• Install and set up Strapi.
• Integrate Strapi with Medusa to interact with Strapi's API.
• Implement two-way synchronization of product data between Medusa and Strapi:
  • Handle product events to sync data from Medusa to Strapi.
  • Handle Strapi webhooks to sync data from Strapi to Medusa.
• Display product data from Strapi in the Next.js Starter Storefront.

You can follow this tutorial whether you're new to Medusa or an advanced Medusa developer, but you're expected to have knowledge in Strapi, as its concepts are not explained in the tutorial.

Step 1: Install a Medusa Application#

Start by installing the Medusa application on your machine with the following command:

npx create-medusa-app@latest

First, you'll be asked for the project's name. Then, when prompted about installing the Next.js Starter Storefront, choose "Yes."

Afterwards, the installation process will start, which will install the Medusa application as a monorepository in a directory with your project's name. The backend is installed in the apps/backend directory, and the Next.js Starter Storefront is installed in the apps/storefront directory.

Once the installation finishes successfully, the Medusa Admin dashboard will open with a form to create a new user. Enter the user's credentials and submit the form. Afterwards, you can log in with the new user and explore the dashboard.

Step 2: Set Up Strapi#

In this step, you'll install and set up Strapi to manage your product content.

a. Install Strapi#

In a separate directory from your Medusa application, run the following command to create a new Strapi project:

npx create-strapi@latest my-strapi-app

You can pick the default options during the installation process. Once the installation is complete, navigate to the newly created directory:

cd my-strapi-app

b. Setup Strapi#

Next, you'll start Strapi and create a new admin user.

Run the following command to start Strapi:

npm run dev

This command starts Strapi in development mode and opens the admin panel setup page in your default browser.

On this page, you can create a new admin user to log in to the Strapi admin panel. You'll return to the admin panel later to manage settings and content.

c. Define Product Content Type#

In this section, you'll define a content type for products in Strapi. These products will be synced from Medusa, allowing you to manage their content using Strapi's CMS features.

You'll use schema.json files to define content types.

Product schema.json

To create the schema for the Product content type, create the file src/api/product/content-types/product/schema.json with the following content:

{
  "kind": "collectionType",
  "collectionName": "products",
  "info": {
    "singularName": "product",
    "pluralName": "products",
    "displayName": "Product",
    "description": "Products from Medusa"
  },
  "options": {
    "draftAndPublish": false
  },
  "pluginOptions": {},
  "attributes": {
    "medusaId": {
      "type": "string",
      "required": true,
      "unique": true
    },
    "title": {
      "type": "string",
      "required": true
    },
    "subtitle": {
      "type": "string"
    },
    "description": {
      "type": "richtext"
    },
    "handle": {
      "type": "uid",
      "targetField": "title"
    },
    "images": {
      "type": "media",
      "multiple": true,
      "required": false,
      "allowedTypes": ["images"]
    },
    "thumbnail": {
      "type": "media",
      "multiple": false,
      "required": false,
      "allowedTypes": ["images"]
    },
    "locale": {
      "type": "string",
      "default": "en"
    },
    "variants": {
      "type": "relation",
      "relation": "oneToMany",
      "target": "api::product-variant.product-variant",
      "mappedBy": "product"
    },
    "options": {
      "type": "relation",
      "relation": "manyToMany",
      "target": "api::product-option.product-option",
      "inversedBy": "product"
    }
  }
}

You define the following fields for the Product content type:

1. medusaId: A unique identifier that maps to the Medusa product ID.
2. title: The product's title.
3. subtitle: A subtitle for the product.
4. description: A rich text field for the product's description.
5. handle: A unique identifier for the product used in URLs.
6. images: A media field to store multiple images of the product.
7. thumbnail: A media field to store a single thumbnail image of the product.
8. locale: A string field to support localization.
9. variants: A one-to-many relation to the Product Variant content type, which you'll define later.
10. options: A many-to-many relation to the Product Option content type, which you'll define later.

Product Lifecycle Hooks

Next, you'll handle product deletion by deleting associated product variants and options.

Create the file src/api/product/content-types/product/lifecycles.ts with the following content:

export default {
  async beforeDelete(event) {
    const { where } = event.params
    
    // Find the product with its relations
    const product = await strapi.db.query("api::product.product").findOne({
      where: {
        id: where.id,
      },
      populate: {
        variants: true,
        options: true,
      },
    })

    if (product) {
      // Delete all variants
      if (product.variants && product.variants.length > 0) {
        for (const variant of product.variants) {
          await strapi.documents("api::product-variant.product-variant").delete({
            documentId: variant.documentId,
          })
        }
      }

      // Delete all options (their values will
      // be cascade deleted by the option lifecycle)
      if (product.options && product.options.length > 0) {
        for (const option of product.options) {
          await strapi.documents("api::product-option.product-option").delete({
            documentId: option.documentId,
          })
        }
      }
    }
  },
}

You define a beforeDelete lifecycle hook that deletes all associated product variants and options when a product is deleted.

Product Controllers

Next, you'll create custom controllers to handle product management.

Create the file src/api/product/controllers/product.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreController("api::product.product")

This code creates a core controller for the Product content type using Strapi's factory method.

Product Services

Next, you'll create custom services to handle product management.

Create the file src/api/product/services/product.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreService("api::product.product")

This code creates a core service for the Product content type using Strapi's factory method.

Product Routes

Next, you'll create custom routes to handle product management.

Create the file src/api/product/routes/product.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreRouter("api::product.product")

This code creates a core router for the Product content type using Strapi's factory method.

c. Define Product Variant Content Type#

Next, you'll define a content type for product variants in Strapi.

Product Variant schema.json

To create the schema for the Product Variant content type, create the file src/api/product-variant/content-types/product-variant/schema.json with the following content:

{
  "kind": "collectionType",
  "collectionName": "product_variants",
  "info": {
    "singularName": "product-variant",
    "pluralName": "product-variants",
    "displayName": "Product Variant",
    "description": "Product variants from Medusa"
  },
  "options": {
    "draftAndPublish": false
  },
  "pluginOptions": {},
  "attributes": {
    "medusaId": {
      "type": "string",
      "required": true,
      "unique": true
    },
    "title": {
      "type": "string",
      "required": true
    },
    "sku": {
      "type": "string"
    },
    "images": {
      "type": "media",
      "multiple": true,
      "required": false,
      "allowedTypes": ["images"]
    },
    "thumbnail": {
      "type": "media",
      "multiple": false,
      "required": false,
      "allowedTypes": ["images"]
    },
    "locale": {
      "type": "string",
      "default": "en"
    },
    "product": {
      "type": "relation",
      "relation": "manyToOne",
      "target": "api::product.product",
      "inversedBy": "variants"
    },
    "option_values": {
      "type": "relation",
      "relation": "manyToMany",
      "target": "api::product-option-value.product-option-value",
      "inversedBy": "variants"
    }
  }
}

You define the following fields for the Product Variant content type:

1. medusaId: A unique identifier that maps to the Medusa product variant ID.
2. title: The variant's title.
3. sku: The stock keeping unit for the variant.
4. images: A media field to store multiple images of the variant.
5. thumbnail: A media field to store a single thumbnail image of the variant.
6. locale: A string field to support localization.
7. product: A many-to-one relation to the Product content type.
8. option_values: A many-to-many relation to the Product Option Value content type, which you'll define later.

Product Variant Controllers

Next, you'll create custom controllers to handle product variant management.

Create the file src/api/product-variant/controllers/product-variant.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreController("api::product-variant.product-variant")

This code creates a core controller for the Product Variant content type using Strapi's factory method.

Product Variant Services

Next, you'll create custom services to handle product variant management.

Create the file src/api/product-variant/services/product-variant.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreService("api::product-variant.product-variant")

This code creates a core service for the Product Variant content type using Strapi's factory method.

Product Variant Routes

Next, you'll create custom routes to handle product variant management.

Create the file src/api/product-variant/routes/product-variant.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreRouter("api::product-variant.product-variant")

This code creates a core router for the Product Variant content type using Strapi's factory method.

d. Define Product Option Content Type#

Next, you'll define a content type for product options in Strapi.

Product Option schema.json

To create the schema for the Product Option content type, create the file src/api/product-option/content-types/product-option/schema.json with the following content:

{
  "kind": "collectionType",
  "collectionName": "product_options",
  "info": {
    "singularName": "product-option",
    "pluralName": "product-options",
    "displayName": "Product Option",
    "description": "Product options from Medusa"
  },
  "options": {
    "draftAndPublish": false
  },
  "pluginOptions": {},
  "attributes": {
    "medusaId": {
      "type": "string",
      "required": true,
      "unique": true
    },
    "title": {
      "type": "string",
      "required": true
    },
    "locale": {
      "type": "string",
      "default": "en"
    },
    "products": {
      "type": "relation",
      "relation": "manyToMany",
      "target": "api::product.product",
      "inversedBy": "options"
    },
    "values": {
      "type": "relation",
      "relation": "oneToMany",
      "target": "api::product-option-value.product-option-value",
      "mappedBy": "option"
    }
  }
}

You define the following fields for the Product Option content type:

1. medusaId: A unique identifier that maps to the Medusa product option ID.
2. title: The option's title.
3. locale: A string field to support localization.
4. products: A many-to-many relation to the Product content type.
5. values: A one-to-many relation to the Product Option Value content type, which you'll define later.

Product Option Lifecycle Hooks

Next, you'll handle option deletion by deleting associated option values.

Create the file src/api/product-option/content-types/product-option/lifecycles.ts with the following content:

export default {
  async beforeDelete(event) {
    const { where } = event.params
    
    // Find the option with its values
    const option = await strapi.db.query("api::product-option.product-option").findOne({
      where: {
        id: where.id,
      },
      populate: {
        values: true,
      },
    })

    if (option && option.values && option.values.length > 0) {
      // Delete all option values
      for (const value of option.values) {
        await strapi.documents("api::product-option-value.product-option-value").delete({
          documentId: value.documentId,
        })
      }
    }
  },
}

You define a beforeDelete lifecycle hook that deletes all associated option values when an option is deleted.

Product Option Controllers

Next, you'll create custom controllers to handle managing product options.

Create the file src/api/product-option/controllers/product-option.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreController("api::product-option.product-option")

This code creates a core controller for the Product Option content type using Strapi's factory method.

Product Option Services

Next, you'll create custom services to handle managing product options.

Create the file src/api/product-option/services/product-option.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreService("api::product-option.product-option")

This code creates a core service for the Product Option content type using Strapi's factory method.

Product Option Routes

Next, you'll create custom routes to handle managing product options.

Create the file src/api/product-option/routes/product-option.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreRouter("api::product-option.product-option")

This code creates a core router for the Product Option content type using Strapi's factory method.

e. Define Product Option Value Content Type#

The last content type you'll define is for product option values in Strapi.

Product Option Value schema.json

To create the schema for the Product Option Value content type, create the file src/api/product-option-value/content-types/product-option-value/schema.json with the following content:

{
  "kind": "collectionType",
  "collectionName": "product_option_values",
  "info": {
    "singularName": "product-option-value",
    "pluralName": "product-option-values",
    "displayName": "Product Option Value",
    "description": "Product option values from Medusa"
  },
  "options": {
    "draftAndPublish": false
  },
  "pluginOptions": {},
  "attributes": {
    "medusaId": {
      "type": "string",
      "required": true,
      "unique": true
    },
    "value": {
      "type": "string",
      "required": true
    },
    "locale": {
      "type": "string",
      "default": "en"
    },
    "option": {
      "type": "relation",
      "relation": "manyToOne",
      "target": "api::product-option.product-option",
      "inversedBy": "values"
    },
    "variants": {
      "type": "relation",
      "relation": "manyToMany",
      "target": "api::product-variant.product-variant",
      "mappedBy": "option_values"
    }
  }
}

You define the following fields for the Product Option Value content type:

1. medusaId: A unique identifier that maps to the Medusa product option value ID.
2. value: The option value's title.
3. locale: A string field to support localization.
4. option: A many-to-one relation to the Product Option content type.
5. variants: A many-to-many relation to the Product Variant content type.

Product Option Value Controllers

Next, you'll create custom controllers to handle managing product option values.

Create the file src/api/product-option-value/controllers/product-option-value.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreController("api::product-option-value.product-option-value")

This code creates a core controller for the Product Option Value content type using Strapi's factory method.

Product Option Value Services

Next, you'll create custom services to handle managing product option values.

Create the file src/api/product-option-value/services/product-option-value.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreService("api::product-option-value.product-option-value")

This code creates a core service for the Product Option Value content type using Strapi's factory method.

Product Option Value Routes

Next, you'll create custom routes to handle managing product option values.

Create the file src/api/product-option-value/routes/product-option-value.ts with the following content:

import { factories } from "@strapi/strapi"

export default factories.createCoreRouter("api::product-option-value.product-option-value")

This code creates a core router for the Product Option Value content type using Strapi's factory method.

You now have all the customizations in Strapi ready. You'll return to Strapi later after you set up the integration with Medusa.

Step 3: Integrate Strapi with Medusa#

In this step, you'll integrate Strapi with Medusa by creating a Strapi Module.

A module is a reusable package that provides functionalities related to a single feature or domain. Medusa integrates the module into your application without implications or side effects on your setup.

a. Install Strapi Client#

First, you'll install the Strapi client in your Medusa application to interact with Strapi's API.

In your apps/backend directory, run the following command to install the Strapi client:

npm install @strapi/client

b. Create Module Directory#

A module is created under the src/modules directory of your Medusa application. So, create the directory src/modules/strapi.

c. Create Strapi Client Loader#

Next, you'll create the Strapi client when the Medusa server starts by creating a loader.

A loader is an asynchronous function that runs when the Medusa server starts. Loaders are useful for setting up connections to third-party services and reusing those connections throughout your module.

To create the loader that initializes the Strapi client, create the file src/modules/strapi/loaders/init-client.ts with the following content:

import { LoaderOptions } from "@medusajs/framework/types"
import { asValue } from "@medusajs/framework/awilix"
import {
  MedusaError,
  ContainerRegistrationKeys,
} from "@medusajs/framework/utils"
import { strapi } from "@strapi/client"

export type ModuleOptions = {
  apiUrl: string
  apiToken: string
  defaultLocale?: string
}

export default async function initStrapiClientLoader({
  container,
  options,
}: LoaderOptions<ModuleOptions>) {
  if (!options?.apiUrl || !options?.apiToken) {
    throw new MedusaError(
      MedusaError.Types.INVALID_DATA,
      "Strapi API URL and token are required"
    )
  }

  const logger = container.resolve(
    ContainerRegistrationKeys.LOGGER
  )

  try {
    // Create Strapi client instance
    const strapiClient = strapi({
      baseURL: options.apiUrl,
      auth: options.apiToken,
    })

    // Register the client in the container
    container.register({
      strapiClient: asValue(strapiClient),
    })

    logger.info("Strapi client initialized successfully")
  } catch (error) {
    logger.error(`Failed to initialize Strapi client: ${error}`)
    throw error
  }
}

A loader file must export an asynchronous function that receives an object with the following properties:

1. container: The module container that allows you to resolve and register module and Framework resources.
2. options: The options passed to the module during its registration. You define the following options for the Strapi Module:
   • apiUrl: The URL of the Strapi API.
   • apiToken: The API token to authenticate requests to Strapi.
   • defaultLocale: An optional default locale for content.

In the loader function, you create a Strapi client instance using the provided API URL and token. Then, you register the client in the module container so that it can be resolved and used in the module's service.

d. Create Strapi Module Service#

Next, you'll create the main service of the Strapi Module.

A module has a service that contains its logic. The Strapi Module's service will contain the logic to create, update, retrieve, and delete data in Strapi.

Create the file src/modules/strapi/service.ts with the following content:

import type { StrapiClient } from "@strapi/client"
import { Logger } from "@medusajs/framework/types"
import { ModuleOptions } from "./loaders/init-client"

type InjectedDependencies = {
  logger: Logger
  strapiClient: StrapiClient
}

export default class StrapiModuleService {
  protected readonly options_: ModuleOptions
  protected readonly logger_: any
  protected readonly client_: StrapiClient

  constructor(
    { logger, strapiClient }: InjectedDependencies, 
    options: ModuleOptions
  ) {
    this.options_ = options
    this.logger_ = logger
    this.client_ = strapiClient
  }

  // TODO add methods
}

The constructor of a module's service receives the following parameters:

1. The module's container.
2. The module's options.

You resolve the Logger and the Strapi client that you registered in the loader. You also store the module options for later use.

In the next sections, you'll add methods to this service to handle managing data in Strapi.

Format Errors Method

First, you'll add a helper method to format errors from Strapi.

In src/modules/strapi/service.ts, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  formatStrapiError(error: any, context: string): string {
    // Handle Strapi client HTTP response errors
    if (error?.response) {
      const response = error.response
      const parts = [context]
      
      if (response.status) {
        parts.push(`HTTP ${response.status}`)
      }
      
      if (response.statusText) {
        parts.push(response.statusText)
      }
      
      // Add request URL if available
      if (response.url) {
        parts.push(`URL: ${response.url}`)
      }
      
      // Add request method if available
      if (error.request?.method) {
        parts.push(`Method: ${error.request.method}`)
      }
      
      return parts.join(" - ")
    }
    
    // If error has a response with Strapi error structure
    if (error?.error) {
      const strapiError = error.error
      const parts = [context]
      
      if (strapiError.status) {
        parts.push(`Status ${strapiError.status}`)
      }
      
      if (strapiError.name) {
        parts.push(`[${strapiError.name}]`)
      }
      
      if (strapiError.message) {
        parts.push(strapiError.message)
      }
      
      if (strapiError.details && Object.keys(strapiError.details).length > 0) {
        parts.push(`Details: ${JSON.stringify(strapiError.details)}`)
      }
      
      return parts.join(" - ")
    }
    
    // Fallback for non-Strapi errors
    return `${context}: ${error.message || error}`
  }
}

This method takes an error object and a context string as parameters. It formats the error based on the structure of Strapi client errors, making it easier to log and debug issues related to Strapi API requests.

You'll use this method in other service methods to handle errors consistently.

Upload Images Method

Next, you'll add a method to upload images to Strapi.

In src/modules/strapi/service.ts, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  async uploadImages(imageUrls: string[]): Promise<number[]> {
    const uploadedIds: number[] = []

    for (const imageUrl of imageUrls) {
      try {
        // Fetch the image from the URL
        const imageResponse = await fetch(imageUrl)
        if (!imageResponse.ok) {
          this.logger_.warn(`Failed to fetch image: ${imageUrl}`)
          continue
        }

        const imageBuffer = await imageResponse.arrayBuffer()
        
        // Extract filename from URL or generate one
        const urlParts = imageUrl.split("/")
        const filename = urlParts[urlParts.length - 1] || `image-${Date.now()}.jpg`

        // Create a Blob from the buffer
        const blob = new Blob([imageBuffer], {
          type: imageResponse.headers.get("content-type") || "image/jpeg",
        })

        // Upload to Strapi using the files API
        const result = await this.client_.files.upload(blob, {
          fileInfo: {
            name: filename,
          },
        })
        
        if (result && result[0] && result[0].id) {
          uploadedIds.push(result[0].id)
        }
      } catch (error) {
        this.logger_.error(this.formatStrapiError(error, `Failed to upload image ${imageUrl}`))
      }
    }

    return uploadedIds
  }
}

This method takes an array of image URLs, fetches each image, and uploads it to Strapi using the Strapi client's files API. It returns an array of uploaded image IDs.

You'll use this method later when creating or updating products and product variants in Strapi.

Delete Images Method

Next, you'll add a method to delete images from Strapi. This will be useful when reverting changes if a failure occurs.

In src/modules/strapi/service.ts, add the following import at the top of the file:

import { MedusaError } from "@medusajs/framework/utils"

Then, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  async deleteImage(imageId: number): Promise<void> {
    try {
      await this.client_.files.delete(imageId)
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        this.formatStrapiError(error, `Failed to delete image ${imageId} from Strapi`)
      )
    }
  }
}

This method takes an image ID as a parameter and deletes the corresponding image from Strapi using the Strapi client's files API. If the deletion fails, it throws a MedusaError with a formatted error message.

Create Document Type Method

Next, you'll add a method to create a document of a content type in Strapi, such as a product or product variant.

In src/modules/strapi/service.ts, add the following enum type before the StrapiModuleService class:

export enum Collection {
  PRODUCTS = "products",
  PRODUCT_VARIANTS = "product-variants",
  PRODUCT_OPTIONS = "product-options",
  PRODUCT_OPTION_VALUES = "product-option-values",
}

Then, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  async create(collection: Collection, data: Record<string, unknown>) {
    try {
      return await this.client_.collection(collection).create(data)
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        this.formatStrapiError(error, `Failed to create ${collection} in Strapi`)
      )
    }
  }
}

This method takes the following parameters:

1. collection: The collection (content type) in which to create the document. It uses the Collection enum.
2. data: An object containing the data for the document to be created.

In the method, you create the document and return it.

Update Document Method

Next, you'll add a method to update a document of a content type in Strapi. This will be useful to implement two-way synching between Medusa and Strapi.

In src/modules/strapi/service.ts, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  async update(collection: Collection, id: string, data: Record<string, unknown>) {
    try {
      return await this.client_.collection(collection).update(id, data)
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        this.formatStrapiError(error, `Failed to update ${collection} in Strapi`)
      )
    }
  }
}

This method takes the following parameters:

1. collection: The collection (content type) in which the document exists. It uses the Collection enum.
2. id: The ID of the document to be updated.
3. data: An object containing the data to update the document with.

In the method, you update the document and return it.

Delete Document Method

Next, you'll add a method to delete a document of a content type from Strapi. You'll use this method when a document is deleted in Medusa, or when reverting document creation in case of failures.

In src/modules/strapi/service.ts, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  async delete(collection: Collection, id: string) {
    try {
      return await this.client_.collection(collection).delete(id)
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        this.formatStrapiError(error, `Failed to delete ${collection} in Strapi`)
      )
    }
  }
}

This method takes the following parameters:

1. collection: The collection (content type) in which the document exists. It uses the Collection enum.
2. id: The ID of the document to be deleted.

In the method, you delete the document.

Retrieve Document by Medusa ID Method

Next, you'll add a method to retrieve a document of a content type from Strapi by its Medusa ID. This will be useful to retrieve a document in case you need to revert changes.

In src/modules/strapi/service.ts, add the following method to the StrapiModuleService class:

export default class StrapiModuleService {
  // ...
  async findByMedusaId(
    collection: Collection, 
    medusaId: string | string[], 
    populate?: string[]
  ) {
    try {
      const result = await this.client_.collection(collection).find({
        filters: {
          medusaId: {
            $in: Array.isArray(medusaId) ? medusaId : [medusaId],
          },
        },
        populate,
      })

      return result.data
    }
    catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        this.formatStrapiError(error, `Failed to find ${collection} in Strapi`)
      )
    }
  }
}

This method takes the following parameters:

1. collection: The collection (content type) in which the document exists. It uses the Collection enum.
2. medusaId: A single Medusa ID or an array of Medusa IDs of the documents to be retrieved.
3. populate: An optional array of relations to populate in the retrieved document.

In the method, you retrieve the documents and return the results.

e. Export Module Definition#

The final piece of a module is its definition, which you export in an index.ts file at the module's root directory. This definition tells Medusa the name of the module, its service, and optionally its loaders.

To create the module's definition, create the file src/modules/strapi/index.ts with the following content:

import { Module } from "@medusajs/framework/utils"
import StrapiModuleService from "./service"
import initStrapiClientLoader from "./loaders/init-client"

export const STRAPI_MODULE = "strapi"

export default Module(STRAPI_MODULE, {
  service: StrapiModuleService,
  loaders: [initStrapiClientLoader],
})

You use Module from the Modules SDK to create the module's definition. It accepts two parameters:

1. The module's name, which is strapi.
2. An object with a required service property indicating the module's service. You also pass the loader you created to ensure it's executed when the application starts.

Aside from the module definition, you export the module's name as STRAPI_MODULE for later reference.

f. Add Module to Medusa's Configurations#

Once you finish building the module, add it to Medusa's configurations to start using it.

In medusa-config.ts, add a modules property and pass an array with your custom module:

module.exports = defineConfig({
  // ...
  modules: [
    {
      resolve: "./modules/strapi",
      options: {
        apiUrl: process.env.STRAPI_API_URL || "http://localhost:1337/api",
        apiToken: process.env.STRAPI_API_TOKEN || "",
        defaultLocale: process.env.STRAPI_DEFAULT_LOCALE || "en",
      },
    },
  ],
})

Each object in the modules array has a resolve property, whose value is either a path to the module's directory or an npm package's name.

You also pass an options property with the module's options. You'll set the values of these options next.

g. Set Environment Variables#

Before you can use the Strapi Module, you need to set the environment variables it requires.

One of these options is an API token that has permissions to manage the content types you created in Strapi.

To retrieve the API token from Strapi, run the following command in the Strapi project directory to start the Strapi server:

Then:

1. Log in to the Strapi admin panel at http://localhost:1337/admin.
2. Go to Settings -> API Tokens.
3. Click on "Create new API Token".

4. In the API token form:
   • Set a name for the token, such as "Medusa".
   • Set the type to "Custom", and:
     • For each content type you created (products, product variants, product options, and product option values), expand its permissions section and enable all the permissions (create, read, update, delete, find).
     • Also enable the permissions for "Upload" to allow image uploads.
5. Click on "Save".

Then, copy the generated API token.

Finally, set the following environment variables in your Medusa project's .env file:

STRAPI_API_URL=http://localhost:1337/api
STRAPI_API_TOKEN=your_generated_api_token

Make sure to replace your_generated_api_token with the actual API token you copied from Strapi.

Step 4: Create Virtual Read-Only Link to Strapi Products#

Medusa's Module Links feature allows you to virtually link data models from external services to modules in your Medusa application. Then, when you retrieve data from Medusa, you can also retrieve the linked data from the third-party service automatically.

In this step, you'll define a virtual read-only link between the product content type in Strapi and the Product model in Medusa. Later, you'll be able to retrieve products from Strapi when retrieving products in Medusa.

a. Define the Link#

To define a virtual read-only link, create the file src/links/product-strapi.ts with the following content:

import { defineLink } from "@medusajs/framework/utils"
import ProductModule from "@medusajs/medusa/product"
import { STRAPI_MODULE } from "../modules/strapi"

export default defineLink(
  {
    linkable: ProductModule.linkable.product,
    field: "id",
  },
  {
    linkable: {
      serviceName: STRAPI_MODULE,
      alias: "strapi_product",
      primaryKey: "product_id",
    },
  },
  {
    readOnly: true,
  }
)

The defineLink function accepts three parameters:

• An object of the first data model that is part of the link. In this case, it's the Product model from Medusa's Product Module.
• An object of the second data model that is part of the link. In this case, it's the product content type from the Strapi Module. You set the following properties:
  • serviceName: the name of the Strapi Module, which is strapi.
  • alias: an alias for the linked data model, which is strapi_product. You'll use this alias to reference the linked data model in queries.
  • primaryKey: the primary key of the linked data model, which is product_id. Medusa will look for this field in the retrieved Products from Strapi to match it with the id field of the Product model.
• An object with the readOnly property set to true, indicating that this link is read-only. This means you can only retrieve the linked data, but you don't manage the link in the database.