Client Context

MedusaJS v2 provides a TypeScript-first commerce engine. The project proves independent deploys for backend, storefront, and admin while sharing types—plus CMS-driven merchandising without coupling content to release trains.

The Challenge

Before

Monolithic platforms couple catalog, content, and frontend deploys—slow for campaigns and experiments.

Better

Headless needs clear module boundaries, reliable checkout, and operational signals (e.g. stock risk) without noisy false positives.

  • Separate release cadence for API vs storefront
  • Marketing-owned hero and promo content
  • Payment flows must stay predictable under load

Solution Architecture

Monorepo with Medusa backend, Next.js 14 storefront (RSC + selective client islands), and Medusa admin.

Custom subscribers for low-stock detection using Medusa’s event system with async, non-blocking alerts.

Strapi for non-product content; Stripe via Medusa payment provider with optimistic checkout UI.

ISR/SSG patterns for catalog pages with refresh strategies for freshness.

Key Implementation Decisions

  • Event-driven low-stock alerts

    Subscriber pattern keeps order path fast; notifications decoupled from core transaction commit.

  • Wishlist module

    Dedicated tables and routes demonstrating Medusa v2 module extension cleanly.

  • Metadata-driven size guides

    Category-scoped merchandising data rendered without hardcoding per product type.

  • Content via Strapi + revalidation hooks

    Editors publish without storefront deploy; webhook-driven invalidation where applicable.

Operational Impact

  • Marketing updates landing and promo surfaces without engineering gate on every copy change.
  • Ops sees stock risk earlier via automated admin/email signals.
  • Checkout remains responsive through optimistic UI and provider abstraction.

Results

  • Demonstrated production-shaped headless split: engine vs presentation vs content.
  • Extensible Medusa modules for merchandising and customer features.
  • End-to-end purchase path with Stripe and shipping rate patterns.

Technology Stack

Commerce engine
MedusaJS v2, Node.js, TypeScript, PostgreSQL
Storefront
Next.js 14 App Router, Tailwind CSS
CMS
Strapi
Payments
Stripe (Medusa provider)
Hosting
Railway (backend), Vercel (storefront)