medusa-strapi-plugin 0.0.12

package/README.md

@@ -0,0 +1,335 @@
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    </picture>
+  </a>
+</p>
+<h1 align="center">
+  Medusa Plugin - Strapi
+</h1>
+
+<h4 align="center">
+  <a href="https://docs.medusajs.com">Documentation</a> |
+  <a href="https://www.medusajs.com">Website</a>
+</h4>
+
+<p align="center">
+  A plugin for implementing Strapi as CMS for Medusa
+</p>
+
+## 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](https://docs.medusajs.com/) version >= 2.8.0
+- [Strapi v5](https://docs.strapi.io/) (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](https://docs.medusajs.com/create-medusa-app)
+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
+
+```bash
+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`:
+
+```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:
+
+```bash
+npx create-strapi-app@latest my-strapi-cms
+```
+
+2. Start your Strapi server:
+
+```bash
+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):
+
+```js
+// 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](https://docs.medusajs.com)
+- [Strapi Documentation](https://docs.strapi.io)
+- [Plugin Guide](./src/)
+
+---

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "medusa-strapi-plugin",
+  "version": "0.0.12",
+  "description": "Medusa plugin for Strapi as CMS",
+  "author": "devx commerce (https://devxcommerce.com)",
+  "license": "MIT",
+  "files": [
+    ".medusa/server"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./*": "./.medusa/server/src/*.js",
+    "./admin": {
+      "import": "./.medusa/server/src/admin/index.mjs",
+      "require": "./.medusa/server/src/admin/index.js",
+      "default": "./.medusa/server/src/admin/index.js"
+    }
+  },
+  "keywords": [
+    "medusa-v2",
+    "medusa",
+    "plugin",
+    "medusa-plugin",
+    "medusa-plugin-cms",
+    "medusa-plugin-integration",
+    "medusa-plugin-strapi",
+    "strapi"
+  ],
+  "scripts": {
+    "build": "medusa plugin:build",
+    "dev": "medusa plugin:develop",
+    "prepublishOnly": "medusa plugin:build",
+    "release": "yarn standard-version"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "^2.12.5",
+    "@medusajs/cli": "^2.12.5",
+    "@medusajs/core-flows": "^2.12.5",
+    "@medusajs/framework": "^2.12.5",
+    "@medusajs/icons": "^2.12.5",
+    "@medusajs/medusa": "^2.12.5",
+    "@medusajs/test-utils": "^2.12.5",
+    "@medusajs/ui": "^4.0.13",
+    "@mikro-orm/cli": "^6.4.16",
+    "@mikro-orm/core": "^6.4.16",
+    "@mikro-orm/knex": "^6.4.16",
+    "@mikro-orm/migrations": "^6.4.16",
+    "@mikro-orm/postgresql": "^6.4.16",
+    "@swc/core": "1.10.12",
+    "@types/node": "^22.13.4",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "pg": "^8.13.0",
+    "prop-types": "^15.8.1",
+    "qs": "^6.14.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "standard-version": "^9.5.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.3",
+    "vite": "=5.2.11",
+    "yalc": "^1.0.0-pre.53"
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "^2.12.5",
+    "@medusajs/cli": "^2.12.5",
+    "@medusajs/core-flows": "^2.12.5",
+    "@medusajs/framework": "^2.12.5",
+    "@medusajs/icons": "^2.12.5",
+    "@medusajs/medusa": "^2.12.5",
+    "@medusajs/test-utils": "^2.12.5",
+    "@medusajs/ui": "^4.0.13",
+    "@mikro-orm/cli": "^6.4.16",
+    "@mikro-orm/core": "^6.4.16",
+    "@mikro-orm/knex": "^6.4.16",
+    "@mikro-orm/migrations": "^6.4.16",
+    "@mikro-orm/postgresql": "^6.4.16",
+    "awilix": "^8.0.1",
+    "pg": "^8.13.0",
+    "qs": "^6.14.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+}