Toward Medusa 2.0

Medusa is a set of tools for developers to create digital commerce applications. Often, these are e-commerce sites, but they can also be marketplaces, enterprise OMS systems, B2B commerce platforms, and much more. When we started Medusa, we wanted to build something to avoid the frustrating and painful hacky workarounds we had encountered with other commerce platforms. And now, thousands of companies are using Medusa, including fast-moving startups and some of the world’s largest companies. It’s hard to explain how happy and proud we are to share our work with you, and our top priority continues to be improving your experience.

Companies reach for Medusa to manage complex workflows that SaaS providers and other open-source tools can’t handle. Examples of complexity we have seen include gathering customer data across different channels to deliver personalized experiences. Or fulfilling thousands of daily orders from hundreds of distribution centers in the way that best aligns with business strategies. Or creating a seamless B2B purchasing experience for highly configurable products. The complexity companies experience is especially common when multiple systems have to work together to deliver a customer experience or automate a business flow.

Many companies try to tame their complexity by building applications from scratch that tie systems together and define customizations; however, building the foundation for such applications takes focus from serving customers best. Medusa has proven to be a much better starting point for businesses to accomplish their customizations than anywhere else. Medusa already has standards for defining data models, custom business logic, and much more, all while being flexible and easy to work with. Instead of reinventing these standards, Medusa users can focus on defining the logic that gives customers the best experience and optimizes operations.

Medusa 2.0 doubles down on ensuring Medusa is the best foundation for building custom digital commerce applications. This is achieved through a focus on supporting custom workflows involving multiple systems directly in Medusa. Today's digital commerce happens with help from different systems, whether point solutions, marketing tools, ERP systems, or custom-built internal systems. With many tools in a stack, a key challenge becomes aligning them and making them work together. Most tools and services have APIs and say they are composable. But they can merely only participate in a composable stack. No tool, except Medusa, helps businesses easily build the foundation for such a stack. And with Medusa 2.0, we will continue to make this much easier.

Two key changes in Medusa’s architecture will address this:

The outcome is that Medusa becomes a hub where your company’s systems can interact. With Medusa’s customization tools, it will be straightforward to build integrations, customer experiences, or internal business workflows from that central hub.

Medusa's architecture has, from the beginning, been modular. The main Medusa package ships with a service for handling products, another for handling carts, another for handling discounts, and so on. The services provide great separation of concerns and make it easy to use them in customizations. All services, however, must run within the same server and database. This is not bad in itself, but it requires that Medusa stores a copy of your data from across your tools internally to make its features work. We are eliminating this dependency and thereby making Medusa pluggable with existing tools. For example, if you have product data in an existing PIM system, you can integrate it deeply with Medusa. When a customer adds a product to their cart, we will fetch product information directly from the PIM system, and you can set up tax and discount rules for the products despite them not being part of Medusa's database.

We are moving services into standalone packages like

Copy to clipboard
@medusajs/product

and

Copy to clipboard
@medusajs/pricing

to achieve this. These modules work independently of the rest of Medusa and can be used within any Node environment, including compatible serverless runtimes. Simultaneously, within the Medusa package, we are defining interfaces to the modules to make Medusa's default API work with the new standalone modules. This work happens behind the

Copy to clipboard
medusa_v2

feature flag.

Soon, we will introduce Workflows - a new, powerful primitive for digital commerce applications with Workflows. A Workflow is a sequence of queries and actions across your system that achieve a task. Medusa will ship a wide range of Workflows to create products, add to a cart, and other operations available in Medusa’s API today.

Workflows are customizable, so you can inject custom logic into core workflows. For example, you can run custom validation when customers update their shipping addresses. Or add rules governing who can add given products to a cart. Or create a product entry in your CMS system whenever a new product is created.

Given that Medusa may be mutating data in external systems - like a PIM for your product data - we are building error handling into Workflows. Medusa will automatically retry failed attempts to update data, and if the issue is permanent, Medusa’s Workflows will compensate for any previous data changes that may have happened.

Developers will also be able to create custom Workflows, which opens the door for a broad range of use cases and makes Medusa the best place to build integrations between your systems.

Consider integrating purchase orders from your ERP with your warehouse management system's inbounds. You can easily build custom services for your ERP and WMS and then construct a workflow that processes the purchase order and forwards it to the WMS. Doing this through Medusa creates opportunities for better customer experiences, like decorating products with an expected restock date for your customers to know when their favorite product will become available. This is easy because your product data is readily available through Medusa. Additionally, with the workflows, you won't have to worry about stale data between systems as retries and compensations are built-in. This is just one example of how custom Workflows can be used. As you add more connections between systems in your stack and Medusa, the opportunities for what is possible with Workflows expand exponentially.

The Workflow primitive joins Medusa’s existing tools like API Routes for custom API request handlers, Admin Extensions to build dashboard UI extensions, EventBus and Subscribers for Pub/Sub, Services for custom business logic and connections to external systems, and, of course, Medusa’s commerce logic for core commerce functionality.

Medusa comes packed with many great defaults that would take years for internal teams in digital commerce businesses to build and even more effort to continue to improve. With Workflows and Medusa 2.0, we will lower the bar for adopting Medusa into your stack. You can, for instance, start using Medusa’s Workflows to integrate your systems and, at your own pace, adopt the commerce modules that make sense for you.

It’s important to note that while the architectural changes we have planned will enable more complex use cases, Medusa will still be simple to set up. Our default API will have minimal breaking changes, and we are committed to making the upgrade path for existing Medusa projects smooth and painless.

Over the next couple of months, we will ship many new standalone commerce modules. Each of them will be a key milestone toward shipping Medusa 2.0, and we are excited to hear your feedback and inputs as they are made available.

You can expect our Workflows to be released very soon. The Workflow tools can be used independently of Medusa 2.0, so you will not have to wait long before using this new, powerful primitive. The timeline for when Medusa 2.0 is still TBD - sign up for our newsletter and follow Medusa on X to stay tuned.