- What exactly is MedusaJS?
- How the architecture fits together
- Core features
- Twenty-two modules, and counting
- Workflows: the underrated feature
- Getting started
- Integrations and plugins
- Who is actually running it
- Wondering whether Medusa is the right foundation for your store?
- Medusa vs. the alternatives
- The honest trade-offs
- Where Medusa is in 2026
- Should you use it?
- Where to learn more
- The bottom line
- Thinking about building on MedusaJS?
Most commerce platforms make the same trade with you: they hand you speed on day one and take away control on day ninety. Shopify gets you selling by the weekend, then meets your third custom requirement with “that’s not supported.” Magento will bend to almost anything, but you pay for it in PHP, infrastructure, and time.
MedusaJS was built for teams that refuse this tradeoff. It’s an open-source, MIT-licensed commerce platform, written in Node.js and TypeScript, that handles the complex parts of commerce, carts, orders, pricing, promotions, inventory, fulfillment, and tax, as independent modules you plug into a clean API. The project currently sits at version 2.18.0, released on 23 July 2026, and it’s the first open-source commerce platform to reach 35,700 GitHub stars.
Quick Answer
MedusaJS is a headless, modular commerce platform built on Node.js and TypeScript. The backend is completely separated from the storefront, and features like carts, pricing, inventory, and tax exist as independent modules you can use standalone, combine, or replace. It’s open source under the MIT license, with no licence fees, no revenue share, and no per-transaction platform cut, which makes it a fit for teams that want Shopify-like speed without giving up Magento-level customization.
What exactly is MedusaJS?
Medusa is a headless, modular commerce platform. “Headless” means the backend, business logic, data, checkout rules, is completely separated from the frontend your customers actually interact with. “Modular” goes a step further: the backend isn’t a single lump of code. It’s a bundle of compatible modules you can choose, replace, or discard one by one.
These features make it fit for almost everything, from a single direct-to-consumer brand site to a multi-vendor marketplace. It also works for a B2B ordering portal or a POS system used across many businesses at once. Everything runs on the same underlying commerce foundation.
Headless
Build your storefront in Next.js, Remix, Astro, Nuxt, a native mobile app, or a kiosk UI. Medusa doesn’t care, because it only ever speaks HTTP.
Modular
Features are organised into individual modules, cart, product, order, pricing, with no database-level syncing between them. Use them standalone, combine them, or swap one for your own implementation.
Open source
MIT licensed, roughly 35.7k stars and 5,000 forks on GitHub. No licence fees, no revenue share, no per-transaction platform cut.
Customization-focused
A built-in framework for adding custom logic, data models, API routes, and integrations. Extension is the intended path, not a workaround.
TypeScript-native
Built on Node.js and Express, with types throughout and modern tooling your team already knows.
How the architecture fits together
Medusa’s request path is deliberately simple, and understanding it explains most of the platform’s design decisions. A request flows through four layers:
1. API routes (HTTP layer)
An Express-based entry point. Storefronts, the admin dashboard, and third-party systems all come in here; nothing reaches the internals directly.
2. Workflows
Where your opinionated business logic lives. API routes invoke workflows rather than calling services ad hoc.
3. Modules
Domain-specific components that own their data and expose a service. Workflows orchestrate them.
4. Data store
PostgreSQL, the only officially supported primary database.
Modules come in two types. Commerce modules handle the various e-commerce aspects and third-party integrations, Stripe for payments, ShipStation for fulfillment, and so on. Infrastructure modules handle system-level concerns: caching (Redis), events, file storage (S3), notifications (SendGrid), analytics (PostHog), locking, and workflow orchestration.
The advantage is that each concern is isolated. Change payment providers and only the payment module is affected, nothing else. Redesign the storefront completely and no backend code gets touched, because all the storefront does is talk to the API layer. With monolithic products, changing one part of the system usually means testing the whole thing, not just the part that changed.
Core features
Medusa works as three components: a backend server, an admin dashboard, and an optional storefront.
Backend server. The Node.js server handles core commerce features: inventory, product variants, and product details, plus cart and checkout functions like totals, shipping, and payment methods. It maintains orders and related tasks such as fulfillment, returns, and exchanges, along with customer profiles and order history. The setup supports third-party integrations like payment gateways, shipment couriers, and CMS platforms such as Contentful or Strapi. Extensibility is a first-class feature here, custom API endpoints, custom workflows, and custom data models, and this is exactly the kind of build our Node.js development team handles when a client needs the backend extended beyond the defaults. Caching for expensive operations like price selection and tax calculation is already available and can be extended to your own data.
Admin dashboard. A ready-made, merchant-facing React dashboard for tracking products, orders, and customers. Medusa 2.0 brought a more unified and interactive interface, dark mode, a Vite-based build for faster development, and more injection zones for inserting custom UI elements. It runs at localhost:9000/app.
Storefront. Optional, and genuinely optional. Medusa provides a Next.js starter with Stripe checkout, Algolia search, and TailwindCSS, plus themeable storefronts driven by CSS variables and integrations with tools like Sanity for visual editing and Resend for transactional email. Or you skip all of it and build against the Store API yourself.
Twenty-two modules, and counting
This is where Medusa has moved fastest. The commerce module catalogue has grown to 22 modules: API Key, Auth, Cart, Currency, Customer, Fulfillment, Inventory, Loyalty, Order, Payment, Pricing, Product, Promotion, Region, Sales Channel, Settings, Stock Location, Store, Store Credit, Tax, Translation, and User.
Three of the newer additions are worth calling out, because each one used to be a custom build:
Loyalty
Gift cards as purchasable products, physical or digital, with issuing, redemption, and tracking through the dashboard, plus checkout integration so customers can pay with them.
Store Credit (v2.14.0+)
Customer credit accounts with full credit and debit transaction history, real-time balance calculation, and cart integration. The audit trail is built in rather than bolted on.
Translation
Locale management and multi-language content across 14 data models today, products, variants, options, categories, collections, tags, types, customer groups, regions, shipping options, and tax rates, configurable from the admin dashboard and extensible to your own models. Support for all commerce modules is on the roadmap.
For anyone who evaluated Medusa a year ago and shelved it over a gap in loyalty, store credit, or i18n, that list is the reason to look again.
Workflows: the underrated feature
Workflows are Medusa’s answer to a problem every commerce team eventually hits: multi-step operations that span systems and must not be half-completed. “Reserve inventory, charge payment, create fulfillment, notify the ERP” is four systems and four chances to fail.
A Medusa workflow stitches these steps together with built-in retry logic, compensation (rollback) on failure, and step-by-step status tracking. Workflows can be triggered through API calls, schedules, or webhooks, and they can work with any module in the application.
Operationally, this matters as much as it does architecturally. Admins get a view of all registered workflows, real-time execution monitoring for each step, error logs with retry options, and the ability to trigger workflows manually from the dashboard. Custom React widgets can surface workflow data wherever the team needs it. The practical effect: when an order gets stuck, someone non-technical can see which step failed and retry it, instead of filing a ticket and waiting for an engineer to read the logs.
Getting started
Prerequisites: Node.js v20+ (LTS releases only, if you install the Next.js starter storefront, use Node v24 LTS or lower), PostgreSQL installed and running, the Git CLI, and npm or Yarn. Redis for caching and Docker for containerised setups are optional.
Scaffold a project with a single command:
npx create-medusa-app@latest my-medusa-store
The CLI prompts for a project name, an admin email, and whether to install the Next.js starter storefront, then provisions a PostgreSQL database automatically. You get a monorepo:
my-medusa-store/
├── apps/
│ ├── backend/ # Medusa server + admin dashboard
│ │ ├── src/ # your custom code
│ │ ├── medusa-config.ts
│ │ └── .medusa/ # generated files
│ └── storefront/ # Next.js starter (if selected)
Apart from the backend and admin dashboard at localhost:9000 (admin /app), the storefront, if installed, is accessed via localhost:8000. From there, the path is to configure integrations via environment variables, add custom API routes and modules, extend the admin with widgets and UI routes, and build the storefront against the Store API. Teams that would rather hand this extension work to a specialist can lean on our custom software development practice to wire up integrations and custom modules without slowing the roadmap down.
Common early snags.
CORS errors
Almost always a configuration mismatch between your storefront URL and the backend’s CORS settings.
Body parser issues
Some custom endpoints need explicit bodyParser.json() middleware.
Database connection failures
Verify PostgreSQL credentials and that the service is actually running.
Integrations and plugins
Payments: Stripe, PayPal, and Paystack for African markets.
Search: Algolia, MeiliSearch.
CMS: Strapi, Contentful, Sanity.
Email: Resend for transactional mail.
Analytics: PostHog, Vercel Analytics.
Custom plugins: A plugin generator for bespoke features such as loyalty schemes or custom authentication flows.
Who is actually running it
Tekla migrated from WooCommerce to Medusa and reported a 70% increase in conversion rates, with automated RMA handling and multi-currency support.
Matt Sleeps moved their mattress store off Laravel onto Medusa, improving both performance and conversion.
Aseel built a custom multi-vendor marketplace on Medusa’s infrastructure.
Visionary Technologies automated B2B order processes and loyalty programs.
Foraged is a multi-vendor marketplace built for scale.
The pattern across these is consistent: none of them wanted a themed template. They wanted a commerce core they could wire into their own operational reality.
Wondering whether Medusa is the right foundation for your store?
Elsner can walk through your catalog complexity, integration list, and team setup, then tell you honestly whether Medusa fits or a simpler platform gets you there faster.
Medusa vs. the alternatives
Here’s how MedusaJS stacks up against the two platforms it gets compared to most often.
| Feature | MedusaJS | Shopify | WooCommerce |
|---|---|---|---|
| Architecture | Headless, modular | Hosted, limited customization | WordPress-based, plugin-heavy |
| Open source | Yes (MIT) | No | Yes |
| Customization | High: APIs, modules, plugins | Limited: Liquid, apps | Moderate: PHP, plugins |
| Frontend flexibility | Any framework | Shopify themes only | WordPress themes |
| Scalability | High: Node.js, horizontal | High: managed for you | Moderate: server-dependent |
| Cost | Free, self-hosted | Subscription + transaction fees | Free + hosting costs |
| Learning curve | Moderate, developer-focused | Low, user-friendly | Moderate, WordPress knowledge |
Medusa’s sweet spot is Shopify-like time to launch with Magento-like depth of customization, minus vendor lock-in and per-transaction fees. That said, if your requirements genuinely fit inside a hosted theme, our Shopify development team can usually get you live faster and with less engineering overhead than a self-hosted build.
The honest trade-offs
Flexibility is not free. It’s worth being clear about the cost before you commit.
It requires technical expertise. Medusa isn’t plug-and-play. Setting up complex integrations takes real engineering time, and non-technical teams won’t get a store live on their own.
Documentation has gaps. It’s comprehensive at the surface, but developers regularly hit edge cases, payment provider setup being the recurring example, where the docs thin out and community threads are outdated.
The community is smaller than Shopify or WordPress. You won’t find many people who have already solved your exact problem. The team is responsive on Discord and X, but that’s different from a decade of accumulated Stack Overflow answers.
You own the infrastructure. Self-hosting means you handle deployment, scaling, patching, backups, and security hardening. Medusa Cloud exists if you’d rather not, but then you’re back to paying someone, just without the lock-in.
None of these are dealbreakers for a team with Node.js engineers. All of them are dealbreakers for a team without one.
Where Medusa is in 2026
Development has stayed brisk. 2.16.0, 2.17.0, and 2.18.0 all shipped between June and July 2026 alone. Recent momentum has focused on a few areas.
Module expansion: Four new modules, Loyalty, Store Credit, Translation, and Settings, were added to the existing catalogue, bringing the total to 22.
Migration tooling: Shopify-to-Medusa migration in a single prompt was the big announcement from Medusa in August 2026, aimed squarely at companies that had outgrown hosted platforms.
AI-assisted development: Documentation and tooling built for AI agents working in Medusa codebases, including the Bloom assistant.
Performance work: Stream-based CSV processing cut import memory usage dramatically, from roughly 4GB to 500MB on a 62,000-row import.
Regional payments: Paystack integration opening up African markets.
Should you use it?
If the fit looks right on paper but you’re not sure your catalog and integration list justify the build, our ecommerce development team can scope it against your actual requirements before you commit engineering time.
Where to learn more
Documentation: docs.medusajs.com
Source: github.com/medusajs/medusa
Community: The Medusa Discord for troubleshooting, GitHub Discussions and Issues for bugs and proposals, and @medusajs on X for release announcements.
Contributing: The project actively accepts community contributions through GitHub.
Key takeaways
- MedusaJS is a headless, modular, MIT-licensed commerce platform on Node.js and TypeScript, currently at version 2.18.0 with 35,700 GitHub stars.
- The architecture runs on four layers: API routes, workflows, modules, and a PostgreSQL data store, which is why swapping one piece rarely breaks another.
- The module catalogue has grown to 22, with Loyalty, Store Credit, and Translation closing gaps that used to require custom builds.
- Workflows give multi-step operations retry logic, rollback on failure, and step-by-step visibility, so a stuck order doesn’t need an engineer to diagnose.
- The trade-off is real: technical expertise, thinner documentation in places, and a smaller community than Shopify or WordPress.
- Medusa fits teams that want a fully custom storefront, their own infrastructure, or deep integration with an existing ERP or PIM. It’s the wrong tool if you need a store live this week with no engineering team.
The bottom line
Medusa’s bet is that commerce is not one product but a set of composable services, and that teams building serious storefronts would rather assemble those services themselves than negotiate with a vendor’s roadmap. Nineteen months after 2.0 shipped, that bet is looking sound: 22 commerce modules, a release every few weeks, and a migration story pointed directly at the platforms it competes with.
Medusa demands more than Shopify. In return, it stops you from compromising. If you’ve got the team to make that trade-off, start with create-medusa-app, wire up a minimum viable product with a section of your catalog, and see how far you can go before the platform stops you with a no.
Thinking about building on MedusaJS?
Elsner’s Node.js and commerce engineers can scope your Medusa build, from module selection to storefront integration, and tell you honestly what it will take to get it into production.
