Strapi plugin

What You'll Achieve

After completing this setup, you'll have:

• ✅ Automatic sync between Medusa and Strapi
• ✅ Rich content management for products in Strapi
• ✅ Extended product data with custom fields and media
• ✅ Unified API to query products with CMS content
• ✅ Scalable architecture for omnichannel commerce

Features

• 🔄 Seamless integration between Medusa and Strapi
• 📝 Flexible content management for your e-commerce store
• 🖼️ Rich media management for product images and assets
• 🚀 Extend product information with custom fields and content
• 📱 Headless architecture for omnichannel commerce
• 🔄 Automatic synchronization between Medusa and Strapi

Requirements

This plugin requires:

• Medusa version >= 2.8.0
• Strapi v5 (latest stable)
• Node.js >= 18.x
• A running Medusa application
• A running Strapi application

Prerequisites

Before starting, make sure you have:

1. A Medusa application set up and running
   • If you don't have one, follow the Medusa quickstart guide
2. A Strapi application set up and running
   • If you don't have one, create it with: npx create-strapi-app@latest my-strapi-cms
3. Basic knowledge of:
   • Medusa concepts (products, variants, collections, categories)
   • Strapi content types and API tokens
   • Environment variables

Quick Start Guide

⏱️ Estimated time: 15-30 minutes
🎯 Difficulty: Beginner to Intermediate
📋 You'll need: Medusa app, Strapi app, and basic terminal knowledge

Step 1: Install the Plugin

npm install @devx-commerce/strapi @strapi/client
# or
yarn add @devx-commerce/strapi @strapi/client

Step 2: Configure Medusa

Add the plugin to your medusa-config.js:

const { defineConfig } = require("@medusajs/medusa"); // or "@medusajs/framework/utils"

module.exports = defineConfig({
  // ... other config
  plugins: [
    // ... other plugins,
    {
      resolve: "@devx-commerce/strapi",
      options: {
        base_url: process.env.STRAPI_URL,
        api_key: process.env.STRAPI_API_KEY,
      },
    },
  ],
});

Step 3: Set Up Strapi

3.1 Create or Configure Your Strapi Project

1. Install Strapi if you haven't already:

npx create-strapi-app@latest my-strapi-cms

2. Start your Strapi server:

cd my-strapi-cms
npm run develop

3.2 Create an API Token

• Go to Settings > API Tokens
• Create a new full access token
• Copy the token to use in your Medusa configuration

3.3 Create Content Types

You have two options to create the content types:

Option A: Using Schema Files (Recommended)

This method is less error-prone and ensures exact field matching:

• Copy the schema files from the strapi-schemas/ directory in this plugin to your Strapi project
• Place them in src/api/[content-type-name]/content-types/[content-type-name]/schema.json

Required content types and their locations:

• Product: src/api/product/content-types/product/schema.json
• Product Variant: src/api/product-variant/content-types/product-variant/schema.json
• Category: src/api/category/content-types/category/schema.json
• Collection: src/api/collection/content-types/collection/schema.json

After adding the schema files, restart your Strapi server to apply the changes.

Option B: Using Strapi Admin Panel (Manual)

If you prefer to create content types manually through the Strapi admin interface:

1. Start your Strapi server: npm run develop or yarn develop
2. Access Strapi Admin: Go to http://localhost:1337/admin
3. Navigate to Content-Type Builder in the sidebar

Create Product Content Type:

1. Click "Create new collection type"
2. Display name: "Product"
3. API ID (singular): "product"
4. Add these fields:
   • title (Text, Required)
   • systemId (Text, Required, Unique)
   • handle (Text)
   • productType (Text)
5. Save the content type

Create Product Variant Content Type:

1. Click "Create new collection type"
2. Display name: "Product Variant"
3. API ID (singular): "product-variant" ⚠️ Important: Use hyphen, not underscore
4. Add these fields:
   • title (Text, Required)
   • systemId (Text, Required, Unique)
   • sku (Text)
5. Add relation field:
   • Field name: "product"
   • Relation type: Many-to-One
   • Target: Product
6. Save the content type

Create Category Content Type:

1. Click "Create new collection type"
2. Display name: "Category"
3. API ID (singular): "category"
4. Add these fields:
   • title (Text, Required)
   • systemId (Text, Required, Unique)
   • handle (Text)
5. Save the content type

Create Collection Content Type:

1. Click "Create new collection type"
2. Display name: "Collection"
3. API ID (singular): "collection"
4. Add these fields:
   • title (Text, Required)
   • systemId (Text, Required, Unique)
   • handle (Text)
5. Save the content type

Complete Product Relations:

After creating Product Variant, go back to the Product content type and add:

• Field name: "variants"
• Relation type: One-to-Many
• Target: Product Variant

⚠️ Critical Notes for Manual Creation:

• Content type names must be exact: product, product-variant, category, collection
• Field names must match exactly: title, systemId, handle, productType, sku
• systemId field must be set as Required and Unique
• Relations must be properly configured between Product and Product Variant

Required fields summary:

• Product: title, systemId (unique), handle, productType, variants (relation)
• Product Variant: title, systemId (unique), sku, product (relation)
• Category: title, systemId (unique), handle
• Collection: title, systemId (unique), handle

Step 4: Configure Environment Variables

Add these variables to your Medusa .env file:

STRAPI_URL=http://localhost:1337/api
STRAPI_API_KEY=your-api-token-here

Step 5: Start Your Applications

1. Start Strapi: npm run develop (in your Strapi directory)
2. Start Medusa: npm run dev (in your Medusa directory)
3. Check the logs for "Connected to Strapi" message

Step 6: Test the Integration

1. Create a test product in Medusa Admin (http://localhost:9000/app)
2. Check Strapi Admin (http://localhost:1337/admin) to see if the product appears
3. Add rich content to the product in Strapi
4. Query the product from your storefront to see the combined data

How It Works

After installation and setup, the plugin will automatically:

• Create and update products, collections & categories in Strapi when they are modified in Medusa
• Sync product, collection & category metadata between Medusa and Strapi
• Allow extending product data with Strapi's content types

Usage

Once the plugin is set up, you can use Strapi's admin panel to add rich content to your products and use the Strapi API to fetch this content for your storefront.

Example of fetching product content from Medusa (with Strapi fields):

// In your storefront using the Medusa JS SDK
import { sdk } from "@medusajs/js-sdk";

const medusa = sdk({
  baseUrl: MEDUSA_BASE_URL,
  publishableApiKey: STOREFRONT_PUBLISHABLE_API_KEY,
});

async function getProductContent(productId) {
  const { product } = await medusa.store.product.retrieve(productId, {
    fields: "cms_product.*",
  });
  return product;
}

// Alternative: Fetch product with Strapi content using query parameters
async function getProductWithStrapiContent(productId) {
  const { product } = await medusa.store.product.retrieve(productId, {
    fields: "+metadata.strapiId,+metadata.strapiSyncedAt",
  });

  // If you need to fetch additional Strapi content directly
  if (product.metadata?.strapiId) {
    // Use Strapi's API directly for rich content
    const strapiResponse = await fetch(
      `${STRAPI_BASE_URL}/products/${product.metadata.strapiId}`,
      {
        headers: {
          Authorization: `Bearer ${STRAPI_API_KEY}`,
        },
      },
    );
    const strapiContent = await strapiResponse.json();
    return { ...product, strapiContent: strapiContent.data };
  }

  return product;
}

Troubleshooting

Common Issues

1. Content Type Validation Errors If you see errors about missing content types or fields, ensure you've:

• Copied all schema files from strapi-schemas/ to the correct locations in your Strapi project
• Restarted your Strapi server after adding the schema files
• Used the exact field names specified in the schemas

2. HTTP 400/404 Errors The plugin now provides detailed error logging. Check your Medusa logs for:

• Full Strapi error responses
• Specific field validation errors
• Content type existence issues

3. Product Variant Naming Ensure your Strapi content type is named product-variant (with hyphen), not just Variant.

4. Missing Fields The plugin expects these exact field names:

• Products: title, systemId, handle, productType
• Product Variants: title, systemId, sku
• Categories: title, systemId, handle
• Collections: title, systemId, handle

Documentation

• Medusa Documentation
• Strapi Documentation
• Plugin Guide

---