medusa

Medusa is an open-source commerce framework built on Node.js and TypeScript that gives developers modular, composable building blocks for building any type of digital commerce application — from direct-to-consumer storefronts and B2B portals to multi-vendor marketplaces and point-of-sale systems — without reinventing foundational commerce logic.

At its core, Medusa provides independently installable npm packages for every commerce domain: products, inventory, carts, orders, payments, promotions, regions, and more. These modules communicate through a Remote Query abstraction and a Link modules system, allowing developers to define cross-module relations without coupling module internals. A saga-style workflow engine adds orchestration on top, enabling complex, compensatable multi-step operations like order fulfillment or refund processing.

The platform ships with a React-based admin dashboard, a TypeScript storefront SDK, and a CLI for scaffolding new projects. It supports both managed hosting via Medusa Cloud — with GitHub integration, PR previews, and autoscaling — and fully self-hosted deployments on any Node.js infrastructure with PostgreSQL and Redis.

Medusa is MIT-licensed and backed by a community of over 14,000 Discord members and an active release cadence with multiple versions shipped monthly. It is suitable for small teams building their first store as well as enterprise engineering teams building multi-region, multi-warehouse commerce platforms.

What You Get

• Modular Commerce Modules - Install only what you need: standalone npm packages for products, cart, order, inventory, payments, promotions, regions, and more, each independently configurable and replaceable.
• Workflow Engine with Compensation - Define multi-step commerce operations (checkout, fulfillment, returns) as typed, compensatable sagas using createWorkflow and createStep — retryable, subscribable, and executable in background jobs.
• Remote Query and Link Modules - Federate data across modules without tight coupling using a Remote Query abstraction, and define cross-module relationships via Link modules to avoid a monolithic schema.
• React Admin Dashboard - A fully featured admin panel built with React, Vite, and React Router for managing products, orders, customers, inventory, promotions, and settings, extensible via the Admin SDK.
• Multi-Region and Multi-Channel - Native support for multiple currencies, region-specific tax rules, localized pricing, and separate sales channels with distinct product sets and pricing policies per channel.
• Advanced Promotions Engine - Build complex promotional rules including customer-specific pricing, B2B tiered discounts, free-shipping campaigns, time-bound offers, and combinable discount codes in pure code.
• TypeScript Storefront SDK - A typed JS/TS SDK for building custom storefronts that connects to Medusa’s REST API without requiring hand-rolled HTTP calls.
• Plugin and Subscriber System - Extend the platform with custom modules, event subscribers, scheduled jobs, and API routes via a file-based convention that auto-discovers and registers resources at startup.

Common Use Cases

• Global DTC brand with multi-region pricing - A fashion retailer uses Medusa to manage ten currencies, localized VAT rules, and region-specific shipping methods across North America, Europe, and Southeast Asia without building a custom pricing engine.
• B2B distributor portal with tiered pricing - An industrial supplier deploys Medusa to serve wholesale clients with company-specific price lists, bulk order workflows, purchase order approvals, and custom payment terms managed in code.
• Multi-vendor marketplace - A startup builds a marketplace where multiple vendors list products, manage their own inventory, and receive split payouts — using Medusa’s modular architecture to compose vendor-scoped logic.
• Headless replatform from Shopify - A brand migrating off Shopify adopts Medusa as the commerce backend while keeping a custom Next.js storefront, using the JS SDK to connect the two without a bespoke API layer.
• POS and in-store fulfilment - A retail chain uses Medusa’s orders and inventory modules to power an in-store POS system that syncs stock in real time with warehouse locations.
• Subscription and recurring order platform - A DTC food brand builds subscription logic on top of Medusa’s order and payment modules, scheduling recurring charges and managing pause/cancel flows through the workflow engine.

Under The Hood

Architecture Medusa employs a sophisticated monorepo architecture organized around loosely-coupled, independently deployable commerce modules, each encapsulating a specific domain — product, cart, order, payment, inventory, promotion — that communicate through a Remote Query abstraction and a Link modules registry rather than direct imports. The central MedusaAppLoader coordinates module initialization, link resolution, and HTTP route loading using a plugin-like registration pattern, while a Turborepo build graph manages incremental compilation across more than fifty packages. A saga-style workflow engine built on a distributed transaction manager sits atop the modules layer, allowing developers to compose compensatable, retryable operations from typed steps — a design that cleanly separates transactional coordination from domain logic. This three-tier structure of framework, modules, and extension points makes it possible to replace or extend any commerce primitive without forking the core.

Tech Stack The backend runs on Node.js with TypeScript using Express as the HTTP adapter, supported by a custom file-system router that auto-discovers route and middleware files at startup. MikroORM (superseding TypeORM) handles persistence against PostgreSQL, while Redis backs the caching layer, event bus, and workflow engine state store. The admin dashboard is a Vite-bundled React 18 SPA using React Router 6 and a bespoke design system, distributed as a separately installable package. Turborepo orchestrates incremental builds with remote caching across the monorepo, with Rollup and tsup handling individual package bundling for npm distribution. The test infrastructure spans Jest for unit tests and a dedicated integration test workspace that runs against live PostgreSQL instances, supplemented by Vitest for browser-adjacent code.

Code Quality With more than three hundred and fifty spec files and a sizeable integration test suite, Medusa demonstrates serious testing investment across unit, integration, and end-to-end scenarios. TypeScript is enforced throughout with strict compiler settings, and a custom ESLint plugin codifies project-specific conventions across the monorepo. The workflows SDK is thoroughly documented with inline JSDoc examples, and GitHub Actions CI leverages Turbo’s remote cache to keep feedback loops fast. Error handling uses structured, typed error responses with explicit HTTP status mappings. Minor coupling exists at the type-import level between packages, but module boundaries are generally well-enforced through the DI container and the Remote Query pattern rather than direct service calls.

What Makes It Unique The createWorkflow / createStep composable saga system is Medusa’s most technically distinctive contribution — developers define compensatable multi-step commerce operations as typed, registerable workflows that can be retried, subscribed to, and executed as background jobs, a capability absent from every other open-source e-commerce framework. The Link modules system, which allows arbitrary cross-module relations to be declared as first-class platform entities without coupling module internals, combined with the Remote Query abstraction for federated cross-module data fetching, represents a genuinely novel approach to modular commerce composition. This architecture enables teams to build highly customized commerce platforms while remaining on a stable, community-maintained core — without the maintenance burden of a full fork.

Self-Hosting

Medusa is released under the MIT License, which grants full rights to use, modify, distribute, and commercialize the software without any copyleft obligations. Self-hosters can run Medusa in production for any commercial purpose, embed it in proprietary products, and modify the source without being required to publish their changes. There are no enterprise modules withheld from the open-source release — every commerce feature, including the admin dashboard, workflow engine, and all modules, is available under MIT.

Running Medusa yourself requires a Node.js runtime, a PostgreSQL database, and Redis for caching and the event bus. For production workloads you are responsible for database provisioning and backups, Redis cluster management, horizontal scaling of the Node.js application layer, monitoring and alerting, and applying framework upgrades via the documented migration guides published with each release. The platform uses Turborepo and a CLI to simplify local development, but production infrastructure setup — SSL termination, load balancing, secrets management — falls entirely on the operator. Teams without dedicated infrastructure experience should budget time for this operational overhead.

Medusa Cloud provides a managed alternative with GitHub-integrated deployments, automatic PR preview environments, autoscaling infrastructure, a managed Redis-backed key-value store, and zero-downtime deployments. The trade-off compared to self-hosting is reduced infrastructure control and a dependency on the managed platform’s pricing and availability. For teams that want the full flexibility of the open-source framework without the operational burden, Medusa Cloud is the officially supported path; for teams with existing infrastructure and DevOps capacity, self-hosting is fully viable and widely practiced within the community.