Product reviews

@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

1pnpm add @jsm406/medusa-product-reviews
2# or
3yarn add @jsm406/medusa-product-reviews
4# or
5npm install @jsm406/medusa-product-reviews

Register the plugin

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

1import { defineConfig } from '@medusajs/medusa';
2
3module.exports = defineConfig({
4  // ...
5  plugins: [
6    {
7      resolve: '@jsm406/medusa-product-reviews',
8      options: {
9        defaultReviewStatus: 'approved', // OPTIONAL. Default: 'approved'
10      },
11    },
12  ],
13});

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)

1import { MedusaPluginsSDK } from '@jsm406/medusa-product-reviews/admin';
2
3export const sdk = new MedusaPluginsSDK({
4  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
5  auth: { type: 'session' },
6});

Storefront operations

1// List reviews for a product
2const { product_reviews, count } = await sdk.store.productReviews.list({
3  product_id: 'prod_123',
4  limit: 10,
5  offset: 0,
6});
7
8// Create / update a review
9await sdk.store.productReviews.upsert({
10  reviews: [
11    {
12      order_id: 'order_123',
13      order_line_item_id: 'item_abc',
14      rating: 5,
15      content: 'Excelente producto',
16      images: [{ url: 'https://...' }],
17    },
18  ],
19});
20
21// Stats
22const { product_review_stats } = await sdk.store.productReviews.listStats({
23  product_id: 'prod_123',
24  limit: 1,
25  offset: 0,
26});

Admin operations

1// List all reviews (with filters)
2const { product_reviews } = await sdk.admin.productReviews.list({
3  status: 'pending',
4  limit: 50,
5  offset: 0,
6});
7
8// Approve / flag a review
9await sdk.admin.productReviews.updateStatus('rev_123', 'approved');
10
11// Manage admin responses
12await sdk.admin.productReviews.createResponse('rev_123', {
13  content: 'Gracias por tu compra',
14});
15
16await sdk.admin.productReviews.updateResponse('rev_123', {
17  content: 'Gracias por tu compra, vuelve pronto!',
18});
19
20await sdk.admin.productReviews.deleteResponse('rev_123');

Endpoints

Admin

Store

Module Options

Local Development

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

1# Build the plugin output
2pnpm build
3
4# Watch mode (rebuild + republish to yalc on every change)
5pnpm dev
6
7# Publish to local yalc registry for testing in your Medusa app
8pnpm dev:publish
9
10# Generate DB migrations
11pnpm db:generate

Then in your Medusa app:

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

Publishing this fork

1# Bump version
2npm version patch   # or minor / major
3
4# Build output to .medusa/server
5pnpm medusa plugin:build
6
7# Publish to npm (requires `npm login` first)
8npm 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.