@jsm406/medusa-product-reviews

Product review + moderation plugin for Medusa v2.

This package is a maintained fork of @lambdacurry/medusa-product-reviews.

The upstream plugin crashes on Medusa 2.14+ because it pins zod@3 while Medusa's own helpers (createFindParams, createOperatorMap, …) were upgraded to Zod v4 in 2.14. Mixing both versions breaks .merge() during middleware evaluation. This fork fixes that incompatibility and removes the dependency on the upstream-only @lambdacurry/medusa-plugins-sdk.

Original code © Lambda Curry. See License / Attribution.

Why this fork?

• Compatible with Medusa 2.14, 2.15 and 2.16+ (Zod v4 under the hood).
• Backend schemas import { z } from "@medusajs/framework/zod" so they share the same Zod instance Medusa uses — no more b._zod.def.shape crash.
• Admin types are vendored locally; no more @lambdacurry/medusa-plugins-sdk dependency.
• Same feature set: product reviews, ratings, stats, admin responses, moderation workflow, store + admin SDK.

Features

• Product reviews with 1–5 star ratings
• Review statistics and analytics (per-product aggregate + rating distribution)
• Moderation workflow (approved / pending / flagged)
• Admin response management (create / update / delete)
• Store + Admin SDK for both Next.js / storefront clients and the Medusa Admin UI customisations

Prerequisites

• Medusa >= 2.14.0 backend (works down to 2.13.x; 2.14+ recommended)
• PostgreSQL with a Medusa-compatible schema

Installation

pnpm add @jsm406/medusa-product-reviews
# or
yarn add @jsm406/medusa-product-reviews
# or
npm install @jsm406/medusa-product-reviews

Register the plugin

Add it to your Medusa app's medusa-config.ts:

import { defineConfig } from '@medusajs/medusa';

module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: '@jsm406/medusa-product-reviews',
      options: {
        defaultReviewStatus: 'approved', // OPTIONAL. Default: 'approved'
      },
    },
  ],
});

Run migrations

pnpm medusa db:migrate

SDK Usage

This plugin ships its own SDK (MedusaPluginsSDK) — a thin extension of @medusajs/js-sdk that adds productReviews to both the admin and store namespaces. No external @lambdacurry/* packages required.

Setup (e.g. in a Next.js storefront)

import { MedusaPluginsSDK } from '@jsm406/medusa-product-reviews/admin';

export const sdk = new MedusaPluginsSDK({
  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
  auth: { type: 'session' },
});

Storefront operations

// List reviews for a product
const { product_reviews, count } = await sdk.store.productReviews.list({
  product_id: 'prod_123',
  limit: 10,
  offset: 0,
});

// Create / update a review
await sdk.store.productReviews.upsert({
  reviews: [
    {
      order_id: 'order_123',
      order_line_item_id: 'item_abc',
      rating: 5,
      content: 'Excelente producto',
      images: [{ url: 'https://...' }],
    },
  ],
});

// Stats
const { product_review_stats } = await sdk.store.productReviews.listStats({
  product_id: 'prod_123',
  limit: 1,
  offset: 0,
});

Admin operations

// List all reviews (with filters)
const { product_reviews } = await sdk.admin.productReviews.list({
  status: 'pending',
  limit: 50,
  offset: 0,
});

// Approve / flag a review
await sdk.admin.productReviews.updateStatus('rev_123', 'approved');

// Manage admin responses
await sdk.admin.productReviews.createResponse('rev_123', {
  content: 'Gracias por tu compra',
});

await sdk.admin.productReviews.updateResponse('rev_123', {
  content: 'Gracias por tu compra, vuelve pronto!',
});

await sdk.admin.productReviews.deleteResponse('rev_123');

Endpoints

Admin

| Method | Path | Description | |--------|--------------------------------------------|--------------------------| | GET | /admin/product-reviews | List all reviews | | PUT | /admin/product-reviews/:id/status | Update review status | | POST | /admin/product-reviews/:id/response | Add an admin response | | PUT | /admin/product-reviews/:id/response | Update admin response | | DELETE | /admin/product-reviews/:id/response | Delete admin response |

Store

| Method | Path | Description | |--------|-------------------------------|-----------------------| | GET | /store/product-reviews | List reviews | | POST | /store/product-reviews | Create / update review | | GET | /store/product-review-stats | Review statistics |

Module Options

| Option | Type | Default | Description | |-----------------------|-------------------------------------------------|--------------|------------------------------------------------------------------------------| | defaultReviewStatus | 'pending' \| 'approved' \| 'flagged' | 'approved' | Status assigned to a new review when the customer submits it. |

Local Development

A running PostgreSQL is required. The CLI defaults to DB_USERNAME=postgres, DB_PASSWORD=postgres if env vars aren't set.

# Build the plugin output
pnpm build

# Watch mode (rebuild + republish to yalc on every change)
pnpm dev

# Publish to local yalc registry for testing in your Medusa app
pnpm dev:publish

# Generate DB migrations
pnpm db:generate

Then in your Medusa app:

pnpm medusa plugin:add @jsm406/medusa-product-reviews
pnpm install   # if you use yarn/pnpm workspaces
pnpm dev

Publishing this fork

# Bump version
npm version patch   # or minor / major

# Build output to .medusa/server
pnpm medusa plugin:build

# Publish to npm (requires `npm login` first)
npm publish --access public

To be listed in the Medusa integrations page, the keywords field already includes medusa-plugin-integration and medusa-v2.

License / Attribution

This package is licensed under the MIT License.

The original source code is © Lambda Curry (https://github.com/lambda-curry/medusa-plugins), licensed under MIT. See the upstream repository for the canonical implementation and full history. This fork is an independent, drop-in replacement published under the same MIT terms.

Changes from upstream

1. Zod v4 compatibility (Medusa 2.14+):
   • All backend Zod schemas now import { z } from "@medusajs/framework/zod" to share the same Zod instance as Medusa's helpers. This is the upstream codemod approach: https://docs.medusajs.com/learn/codemods/replace-zod-imports.
   • zod dependency bumped from 3.25.76 → ^4.0.0 so the admin bundle can keep using its own Zod for browser-side form validation without colliding with Medusa's Zod v4 in the backend runtime.
2. Removed dependency on @lambdacurry/medusa-plugins-sdk. The SDK and admin types are vendored under src/admin/sdk.ts and src/admin/types.ts.
3. Package renamed from @lambdacurry/medusa-product-reviews to @jsm406/medusa-product-reviews. No code-level migration is needed beyond updating the resolve: string in medusa-config.ts.