npm package: @ouassim-tinloof/medusa-manual-product-sorting
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">
  Manual Product Sorting 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">
  Manually sort and organize products within categories in Medusa
</p>

<video controls src="https://github.com/user-attachments/assets/60fb3fea-00e4-44b7-95dc-0aaaef14e0a6">
</video>

## Overview

The Manual Product Sorting Plugin enables admin users to manually organize and reorder products within categories using an intuitive drag-and-drop interface. This is particularly useful for merchandising, promotional campaigns, or when you want to highlight specific products in a category.

## Features

- **Drag-and-drop sorting** for products within categories
- **Real-time updates** with optimistic UI for instant feedback
- **Persistent ordering** stored in product metadata
- **Category-specific sorting** - different order for each category
- **Admin widget integration** on category detail pages
- **Internationalization support** with 25+ languages
- **Efficient updates** - only saves products with changed positions

## Installation

1. Install the Manual Product Sorting plugin

```bash
yarn add @ouassim-tinloof/medusa-manual-product-sorting
```

or

```bash
npm install @ouassim-tinloof/medusa-manual-product-sorting
```

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

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

3. Start your server

```bash
yarn dev
```

## Events

### `products.sorted`

Emitted when products are successfully sorted within a category.

**Event Data:**

```typescript
{
  products: ProductTypes.UpsertProductDTO[];
  id: string; // category ID
}
```

## Using the Rank Attribute

After sorting products in the admin UI, the plugin stores the sort order in the product's metadata under the `rank` property. This allows you to fetch products in their custom sorted order.

### How Rank is Stored

The rank is stored in the product metadata as a nested object:

```typescript
{
  metadata: {
    rank: {
      [categoryId]: "00",  // Zero-padded string
      [collectionId]: "01",
      // ... different ranks for different categories/collections
    }
  }
}
```

Each category or collection has its own rank value, allowing the same product to have different positions across different categories.

### Using Rank in Storefront

You can use the rank attribute in your storefront to display products in the order set by your merchandising team:

```typescript
// Fetch products from a category in their custom order
const products = await medusa.products.list({
  category_id: categoryId,
  order: `metadata.rank.${categoryId}`,
});

// Display products in the sorted order
products.forEach((product) => {
  // Render product
});
```