01Context
What this was
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.
02Problem
What was broken
Before
Monolithic platforms couple catalog, content, and frontend deploys-slow for campaigns and experiments.
What had to change
Headless needs clear module boundaries, reliable checkout, and operational signals (e.g. stock risk) without noisy false positives.
- 01Separate release cadence for API vs storefront
- 02Marketing-owned hero and promo content
- 03Payment flows must stay predictable under load
03Solution
What I built
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.
04Decisions
Key implementation decisions
- 01
Event-driven low-stock alerts
Subscriber pattern keeps order path fast; notifications decoupled from core transaction commit.
- 02
Wishlist module
Dedicated tables and routes demonstrating Medusa v2 module extension cleanly.
- 03
Metadata-driven size guides
Category-scoped merchandising data rendered without hardcoding per product type.
- 04
Content via Strapi + revalidation hooks
Editors publish without storefront deploy; webhook-driven invalidation where applicable.
05Impact
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.
06Results
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.
07Stack
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)