@webupro/medusa-power-seo

SEO scoring for Medusa v2, built on @power-seo/content-analysis.

Adds a Rank Math-style score to the product page — a dial, a grouped checklist, a live Google preview — and a catalogue-wide list that answers "where do I start?". Multi-locale shops score each language separately.

Install

npm install @webupro/medusa-power-seo

// medusa-config.ts
module.exports = defineConfig({
  plugins: [{ resolve: "@webupro/medusa-power-seo", options: {} }],
})

Restart the backend. The product page gains an SEO score panel and the sidebar gains an SEO scores page.

Configuration

Configuration is environment variables, not plugin options: this plugin registers no module (it has no table of its own), and Medusa forwards plugins[].options to a plugin's modules. Every variable has a default that produces a working single-locale English install.

| Variable | Default | What it does | | --- | --- | --- | | POWER_SEO_STOREFRONT_URL | STOREFRONT_URL, else http://localhost:8000 | Origin of the canonical URL that gets graded | | POWER_SEO_PRODUCT_PATH | /{locale}/products/{handle} | Canonical path template | | POWER_SEO_SOURCE_LOCALE | en | The locale whose copy lives on the product row | | POWER_SEO_LOCALES | (source only) | Extra locales to score, comma-separated | | POWER_SEO_BRAND_SUFFIX | (none) | Appended to a generated <title>, e.g. \| LIFTED | | POWER_SEO_ADMIN_LANG | en | Admin copy language — en, hu or sk | | POWER_SEO_TRANSLATIONS_MODULE | translations | Container key of the module holding locale overlays |

A two-language Slovak shop:

POWER_SEO_STOREFRONT_URL=https://lifted.sk
POWER_SEO_SOURCE_LOCALE=sk
POWER_SEO_LOCALES=hu
POWER_SEO_BRAND_SUFFIX=| LIFTED
POWER_SEO_ADMIN_LANG=hu

Multi-locale scoring

Each locale ships its own <title> and <meta description>, so each earns its own score. The source locale is graded from the product row itself. Every other locale is an overlay read from the shop's translations module, resolved by container key, over rows of (resource_type, resource_id, locale, field, value) — the shape MedusaService generates for a Translation model. The overlay fields are title, description, seo_title, seo_description and seo_keyphrase.

Resolution order per locale, chosen so the score grades the page that actually ships: the locale's own SEO override → the locale's translated copy → the source locale. A source-locale override never outranks a translation, otherwise a Hungarian page would be graded on copy no Hungarian visitor sees.

A shop with no translations module still works — it scores its source locale, and the locale tabs never render.

What gets graded

The analyser runs 99 checks, but most grade a blog article: author schema, source quality, FAQ and TL;DR sections, citation readiness, freshness. A perfectly good product page scores 44% against the full set, which makes the raw number useless to an operator. This plugin grades the 17 checks a product detail page can actually influence and normalises over the ones that ran.

| Section | Checks | | --- | --- | | Basic SEO | title length and keyphrase, keyphrase position, meta description length and keyphrase, keyphrase in URL, description length | | Keyphrase | length, density, first-paragraph presence, distribution, even distribution | | Readability | paragraph length, sentence length | | Technical | URL length, canonical URL, product images |

Deliberately excluded: the E-E-A-T / AEO / search-intent families (article-shaped), heading / link / table-of-contents checks (owned by the storefront template, not by any admin field), image-alt and image-keyphrase (storefronts render the product title as alt, so it is never actually missing), the English-wordlist checks transition-words, word-complexity, title-sentiment, title-power-word and inclusive-language (the library takes a locale but no check reads it, so they mis-grade every other language), and text-presence (it duplicates word-count).

Keyphrase checks are skipped, not failed, until the operator sets a focus keyphrase — grading a product against a phrase nobody chose is noise.

API

| Route | Returns | | --- | --- | | GET /admin/seo-score?locale=&q=&limit= | Every published product, worst first, plus count, average, locales and the admin label pack | | GET /admin/seo-score/:id?locale= | One product with the per-check breakdown and the meta the SERP will show |

Scoring is pure and costs ~3ms per product, so the catalogue is graded per request rather than cached — a stale score is worse than a one-second wait, and there is no invalidation to get wrong. Paging stops at 2000 products.

The focus keyphrase is stored on metadata.seo_keyphrase and is editable in the source locale only; its translation belongs to the shop's translations module.

Development

npm install
npm test            # unit tests — pure, no database
npm run build       # medusa plugin:build

Licence

MIT