Product description

medusa-plugin-product-description

AI-powered product & category description generator plugin for MedusaJS v2.

This plugin uses AI (via OpenRouter) to generate SEO-optimized descriptions for products and categories in Spanish. It adds widgets on the product and category detail pages, plus a dedicated admin page for batch operations and cache management.

Features

• Product detail widget: "Generar Descripcion con IA" button directly on the product edit page
• Category detail widget: "Generar Descripcion de Categoria con IA" button directly on the category edit page
• Admin page "IA Descripciones": individual generation for products and categories, batch generation of ALL products/categories, and cache revalidation
• AI generation via OpenRouter (OpenAI-compatible API, supports any model: Google Gemini, GPT, Claude, etc.)
• Configurable prompts via environment variables
• Automatic date stamp: "Descripcion actualizada el DD/MM/AAAA"
• Server-side cache revalidation via STOREFRONT_URL
• Batch operations with progress bar and cost warning
• Zero hardcoded URLs — works on any Medusa installation

Prerequisites

• MedusaJS v2.13.0 or later
• Node.js v20 or later
• An OpenRouter API key (free tier available)

Installation

npm install medusa-plugin-product-description

Configuration

1. Environment Variables

Add the following to your Medusa project's .env file:

1OPENROUTER_API_KEY=sk-or-v1-your-key-here
2OPENROUTER_MODEL=google/gemma-3-12b-it:free
3OPENROUTER_SITE_URL=https://your-store.com
4OPENROUTER_APP_NAME=Your Store Admin
5STOREFRONT_URL=https://your-storefront.com
6AI_DESCRIPTION_PROMPT=Genera una descripcion atractiva, natural y optimizada para SEO sobre el producto "{productTitle}". ...
7AI_CATEGORY_PROMPT=Escribe una descripcion breve, natural y optimizada para SEO en Markdown sobre la categoria **{categoryName}**. ...

Default product prompt:

Genera una descripcion atractiva, natural y optimizada para SEO sobre el producto "{productTitle}".
Debe parecer redactada por un humano y no mostrar rastros de IA.
Incluye iconos emoji de forma moderada y utiliza formato en Markdown.

La descripcion debe estar lista para publicarse directamente, sin frases introductorias, anotaciones ni indicaciones.
90-140 palabras.

Default category prompt:

Escribe una descripcion breve, natural y optimizada para SEO en Markdown sobre la categoria **{categoryName}**.
Incluye 2-4 emojis pertinentes (sin abusar).

Requisitos:
- 90-140 palabras.
- Tono cercano, profesional y claro.
- Nada de instrucciones meta ni disculpas; texto final listo para publicar.

2. Medusa Configuration

In your medusa-config.ts, register the plugin:

1import { defineConfig } from "@medusajs/framework/config"
2
3export default defineConfig({
4  plugins: [
5    {
6      resolve: "medusa-plugin-product-description",
7      options: {},
8    },
9  ],
10})

Usage

Widgets (recommended)

The plugin injects widgets directly into the Medusa admin:

• Product detail page (/app/products/:id): A "Generar Descripcion con IA" section appears below the product details. Generate, edit, save, and revalidate — all without leaving the page.
• Category detail page (/app/categories/:id): Same widget for categories, with sibling category context for better AI results.

Admin Page: IA Descripciones

Navigate to IA Descripciones in the sidebar for advanced operations:

Individual generation:

• Enter a product or category ID, load it, generate a description, edit and save.

Batch generation:

• Generate descriptions for ALL products or ALL categories in one go.
• A progress bar shows real-time status.
• ⚠️ Warning: This calls the OpenRouter API for every entity. Use with caution — it may consume significant API credits.

Cache management:

• Revalidate products cache, categories cache, or both at once.
• Requires STOREFRONT_URL environment variable pointing to your storefront.

Next.js Revalidation Endpoint

If you're using a Next.js storefront, this plugin calls {STOREFRONT_URL}/api/revalidate?tags=... to revalidate the ISR cache. Add this endpoint:

1// frontend/src/app/api/revalidate/route.ts
2import { revalidateTag } from "next/cache"
3import { NextRequest, NextResponse } from "next/server"
4
5export async function GET(request: NextRequest) {
6  const tag = request.nextUrl.searchParams.get("tags") || "products"
7  revalidateTag(tag)
8  return NextResponse.json({ revalidated: true, tag })
9}

API Endpoints

POST /admin/ai-description

Generate a product description.

Request:

{ "productId": "prod_01JABC...", "productTitle": "Paracetamol 650mg" }

Response:

{ "description": "## Paracetamol 650mg\n\nAlivia el dolor y la fiebre con..." }

POST /admin/ai-category-description

Generate a category description. Optionally include sibling category names for context.

Request:

1{
2  "categoryId": "pcat_01JABC...",
3  "categoryName": "Analgesicos",
4  "relatedCategories": ["Antiinflamatorios", "Antigripales"]
5}

Response:

{ "description": "## Analgesicos\n\nEncuentra los mejores analgesicos..." }

POST /admin/revalidate-cache

Trigger cache revalidation on the storefront. Requires STOREFRONT_URL environment variable.

Request:

{ "tags": "products" }

Response:

{ "revalidated": true, "tags": "products" }

Development

1# Install dependencies
2npm install
3
4# Build the plugin
5npm run build
6
7# Watch mode (for local plugin development)
8npm run dev

Local Testing with a Medusa Project

1# From your plugin directory
2npm run dev
3
4# In your Medusa project directory:
5npx medusa plugin:add ../path-to/medusa-plugin-product-description

Publishing to NPM

1npx medusa plugin:build
2npm publish

To publish an update:

1npm version patch   # or minor / major
2npx medusa plugin:build
3npm publish

License

MIT