npm package: @ouassim-tinloof/medusa-media-groups
Description: A starter for Medusa plugins.
Author: Medusa
Latest version: 0.0.1

<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">
  Media Groups Plugin
</h1>

<h4 align="center">
  <a href="https://docs.medusajs.com">Documentation</a> |
  <a href="https://www.medusajs.com">Website</a>
</h4>

<p align="center">
  Organize and assign product images to specific variants and options in Medusa
</p>

<video src="https://github.com/user-attachments/assets/79e48f1f-b525-48f6-be10-f860d2eecaeb"></video>

## Overview

The Media Groups Plugin enables admin users to assign specific images to product variants or options (like colors). This allows for a more organized product page where selecting a variant shows only the relevant images.

This plugin leverages Medusa's native product variant images feature, providing a user-friendly interface to manage image associations directly from the product detail page.

## Features

- **Variant-specific images** - Assign images to individual product variants using Medusa's native variant images
- **Option-based grouping** - Group images by option values (e.g., assign images to all "Blue" variants at once)
- **Batch updates** - Efficient updates for multiple variants sharing the same option
- **Drag-and-drop interface** - Easily reorder images and drag between available and assigned sections
- **Thumbnail management** - First image in the list automatically becomes the variant thumbnail
- **Image ordering** - Custom image order stored in variant metadata
- **Admin widget integration** - Manage media groups directly from the product detail page

## Installation

1. Install the Media Groups plugin

```bash
yarn add @ouassim-tinloof/medusa-media-groups
```

or

```bash
npm install @ouassim-tinloof/medusa-media-groups
```

2. Configure the plugin in your `medusa-config.ts`

```typescript
module.exports = defineConfig({
  projectConfig: {
    ...
  },
  plugins: [
    {
      resolve: "@ouassim-tinloof/medusa-media-groups",
      options: {},
    },
  ],
})
```

3. Start your server

```bash
yarn dev
```

## How It Works

This plugin uses Medusa's built-in product variant images relationship. When you assign images to a variant:

1. Images are linked to variants using Medusa's `batchVariantImagesWorkflow`
2. The first image in the list is automatically set as the variant's thumbnail
3. Image order is preserved in the variant's `metadata.images_order` field

## API Reference

### Batch Update Variant Images

`POST /admin/products/:id/variants/batch/media-groups`

Updates images for multiple variants in a single request.

**Body Parameters:**

```typescript
{
  updates: Array<{
    variantId: string; // ID of the variant to update
    add?: string[]; // Array of image IDs to add
    remove?: string[]; // Array of image IDs to remove
    thumbnail?: string | null; // URL of the thumbnail image
    metadata?: Record<string, unknown>; // Additional metadata (e.g., images_order)
  }>;
}
```

## Exported Workflows

### `batchVariantImagesWorkflow`

A workflow that wraps Medusa's core `batchVariantImagesWorkflow` to handle batch updates for multiple variants.

```typescript
import { batchVariantImagesWorkflow } from "@ouassim-tinloof/medusa-media-groups/workflows";

await batchVariantImagesWorkflow(container).run({
  input: [
    { variant_id: "variant_123", add: ["img_abc"], remove: ["img_xyz"] },
    { variant_id: "variant_456", add: ["img_def"] },
  ],
});
```