@zachariaz/strapi-plugin-medusa-picker

A Strapi v5 custom field plugin for browsing and selecting products, categories, and collections from a Medusa eCommerce backend.

Features

• Custom Field: Adds a "Medusa Picker" field type to Content-Type Builder (CUSTOM tab)
• Modal Picker UI: Browse and search Medusa entities with grid/list views
• Multi-select: Select multiple products, categories, or collections
• Type Filtering: Switch between Products, Categories, and Collections
• Search: Real-time search with debouncing
• Pagination: Configurable page size (15, 30, 50 items)
• Admin Settings: Configure Medusa API connection via Settings page

Requirements

• Strapi v5
• Node.js 18+
• A running Medusa v2 backend with a Publishable API Key

Installation

npm install @zachariaz/strapi-plugin-medusa-picker

Configuration

Enable the plugin in config/plugins.ts:

export default () => ({
  'medusa-picker': {
    enabled: true,
  },
});

Rebuild and restart Strapi:

npm run build
npm run develop

Connect to Medusa

1. Go to Settings → Medusa Picker in Strapi admin
2. Enter your Medusa API URL — the base URL with no trailing slash (e.g., http://localhost:9000, not http://localhost:9000/)
3. Enter your Publishable API Key — copy from Medusa Admin → Settings → Publishable API Keys (looks like pk_...)
4. Click Save
5. Click Test Connection to verify — a 200 response with {"success":true} means it's wired up

Environment Variables

These are read only when no settings have been saved yet and seed the initial values in Settings → Medusa Picker. After the first save in the admin UI, the stored values take precedence.

| Variable | Example | Maps to | |---|---|---| | MEDUSA_BACKEND_URL | http://localhost:9000 | Medusa API URL | | MEDUSA_PUBLISHABLE_API_KEY | pk_653b92fe94bafc6a174ae695... | Publishable API Key |

Example .env:

MEDUSA_BACKEND_URL=http://localhost:9000
MEDUSA_PUBLISHABLE_API_KEY=pk_653b92fe94bafc6a174ae695ecc192a63c4950498e33cc6af44c50ff67c3b562

Usage

Adding the Field

1. Go to Content-Type Builder
2. Select or create a content type
3. Click Add another field → CUSTOM tab
4. Select Medusa Picker
5. Configure field name and save

Using the Picker

1. Edit a content entry
2. Click Select from Medusa
3. Browse/search entities, switch types, select items
4. Click Select to confirm

Data Format

Selected items are stored as a JSON string:

[
  { "external_id": "prod_01H123ABC", "type": "product", "name": "Blue T-Shirt" },
  { "external_id": "pcol_01H456DEF", "type": "collection", "name": "Summer Sale" }
]

| Field | Description | |-------|-------------| | external_id | The entity's ID in the external commerce system (e.g. Medusa product ID) | | type | product, collection, or category | | name | Cached display name |

Storefront Usage

The storefront should use the stored external_id values to fetch full entity data directly from the commerce backend:

const references = await strapi.find('api::page.page', { populate: ['medusa_field'] });
const productIds = references
  .filter(r => r.type === 'product')
  .map(r => r.external_id);

const products = await medusa.products.list({ id: productIds });

Development

npm install
npm run build    # Build for production
npm run watch    # Watch mode for development
npm run verify   # Verify plugin structure

Local Development with Strapi

npm run watch:link
# In your Strapi project:
# yalc add @zachariaz/strapi-plugin-medusa-picker
# npm run develop

License

MIT