Where Shopify gives you a managed platform with extension points, Medusa JS gives you the platform itself. The core runs on PostgreSQL and Redis — standard infrastructure — and every commerce concern is a module you can configure, extend or completely replace: swap the pricing module for your ERP-driven logic, replace inventory with a 3PL-backed implementation, keep the rest stock. This guide covers the architecture, the development workflow, the storefront layer, and the honest decision criteria versus SaaS platforms. The Medusa documentation is the canonical reference.

Medusa JS — core and modules, React admin with auto-generated APIs, Next.js starter storefront and plugin ecosystem by CodeAtoZ

The Medusa JS core is a Node.js application exposing two auto-generated REST APIs — the Store API for storefronts and the Admin API for back-office — over a set of commerce modules: products, carts, orders, pricing, promotions, inventory, fulfilment, payments, customers, and regions. Modules are isolated with explicit interfaces, which is what makes them swappable: implement the module interface and Medusa wires your version in place of the default. Setup is one command and the standard infra pair:

npx create-medusa-app@latest my-store
# Prompts: project name, PostgreSQL connection, admin user
# Optionally scaffolds the Next.js storefront alongside

cd my-store
npm run dev
# Admin dashboard: http://localhost:9000/app
# Store API:       http://localhost:9000/store
# Admin API:       http://localhost:9000/admin

The official Medusa JS Next.js starter ships a complete storefront — product pages, cart, checkout with Stripe, customer accounts — built on the Store API, and because the API is plain REST, any frontend from this series works: Astro, Remix patterns, Nuxt. Customisation happens in TypeScript: custom services and API routes for new capabilities, subscribers reacting to events (order.placed → ERP push), and the Workflows API for multi-step business logic with rollback semantics — the Medusa JS answer to “what happens when step three of five fails”. Plugins cover payments (Stripe, PayPal, Adyen), search (Algolia, Meilisearch) and notifications — browse the catalogue in the Medusa plugin directory. The Workflows documentation covers the orchestration model — it is the feature that separates Medusa from “Express with a product table”.

Production Medusa JS needs three pieces: the server (Railway, Render, Fly.io, or any Node host), PostgreSQL (managed — Neon, Supabase, RDS), and Redis for the event bus and caching. Run the worker mode separately from the API server at scale so background jobs (notification sending, workflow steps) never compete with request latency. Front it with the same edge patterns as any headless build — cache product reads at the CDN, never cache carts — and the result competes with any SaaS on performance while keeping per-order economics flat. Our headless commerce team builds and operates Medusa JS stacks for teams that want commerce as code; see the headless architecture guide for where Medusa fits the broader decision tree.