What changed in Medusa 2.0? A fully modular commerce core

Medusa 2.0 is not a cosmetic update — it is a redesign of the platform’s internal architecture. The Medusa team removed cross-domain dependencies, moved shared logic into workflow engines, and reorganized the entire backend into modular, isolated components.

In practical terms, parts of the system that previously lived inside the core have been extracted into independent domain modules, each with its own lifecycle. This prevents the backend from growing as a single, monolithic codebase and ensures that changes remain contained within their domain.

Each module is published as its own NPM package and maintained independently, which not only stabilizes the ecosystem but also makes upgrades far less risky.

How the modular core works in Medusa 2.0

At the center of Medusa 2.0 is domain-driven modularity. Every major business area — cart, payments, catalog, inventory, customers, promotions — is implemented as a discrete module with explicit inputs, outputs and versioning rules.

A module in Medusa 2.0:

• owns its domain logic,
• exposes a clear API,
• operates independently of other modules,
• can be replaced or extended without rewriting the core.

This domain separation brings several operational benefits:

• no hidden coupling between modules,
• no global “core injections”,
• clear validation of inter-module dependencies,
• minimal side effects when upgrading a single module.

It is a structural shift away from systems where plugins hook into the central engine, often creating conflicts, unpredictable overrides and performance bottlenecks.

Modules and responsibilities: how developers work with individual domains

In Medusa 2.0, modules are the building blocks of the backend. Developers can choose to:

• use a module as-is,
• override specific behavior via extensions,
• replace the entire module with a custom implementation.

This gives engineering teams the ability to work on one area at a time. For example, a team responsible for promotions can iterate on its module independently from checkout or inventory. This is rarely possible in monolithic commerce engines, where any change tends to affect multiple areas at once.

Workflows in Medusa 2.0: replacing cross-domain logic with a consistent engine

One of the biggest architectural advances in Medusa 2.0 is the introduction of workflows — a flexible system for handling multi-step processes that involve more than one module.

Instead of embedding cross-domain logic inside the core, workflows provide a standardized, explicit structure for processes such as:

• checkout confirmation,
• inventory adjustments,
• order fulfillment,
• payment authorization,
• customer lifecycle actions.

This ensures that domain modules stay clean and focused. The workflow engine orchestrates the sequence, handles errors predictably, and keeps side effects under control.

As a result, Medusa 2.0 allows modules to remain independent while still enabling complex, multi-domain operations.

The role of Medusa packages: @medusajs/medusa, @medusajs/framework and @medusajs/admin-sdk

Medusa 2.0 introduces a clearer separation between development layers. Each official package has a dedicated purpose:

@medusajs/medusa
The entry point for running a Medusa server. It provides the configuration base, server bootstrap, and default module setup. It is intentionally lightweight.

@medusajs/framework
The actual development framework — here you build modules, extend logic, create workflows and define domain structures. This is where most backend engineering happens.

@medusajs/admin-sdk
A structured SDK designed for building admin interfaces, powering both custom admin panels and UI tools that interact with backend modules.

By separating runtime, framework logic and UI tooling, Medusa 2.0 prevents accidental couplings and encourages a cleaner development workflow.

Plugins vs modules: a clearer developer experience

In the previous version of Medusa, the plugin system served multiple responsibilities. In Medusa 2.0 the intent is explicit:

• modules define business domains,
• plugins integrate external services (payments, taxes, logistics, analytics).

This distinction makes the backend architecture predictable. Developers no longer worry about plugins overriding core logic or introducing unexpected behavior. Instead, integration logic lives where it belongs — outside the domain model.

Scalability benefits: selective deployment, selective scaling

A modular architecture naturally supports selective scaling. Since each module has its own logic and API surface, you can scale:

• the order service separately from catalog services,
• pricing logic independently from checkout,
• workflows without affecting transactional endpoints.

In cloud environments, this creates a microservices-like deployment strategy without the complexity normally associated with microservices. Teams gain granular control over performance, resource allocation and monitoring.

Modules also make bottleneck diagnosis significantly easier. When every module has a predictable API boundary, performance audits are no longer a guessing game.

How Medusa 2.0 improves engineering workflow and collaboration

Larger headless commerce projects often involve several teams working in parallel. Medusa 2.0 supports this through:

• domain ownership — each team works on its module,
• non-blocking upgrades — modules evolve independently,
• simplified testing — modules can be tested in isolation,
• reduced release risk — changes no longer affect unrelated domains.

This structure shortens lead times and aligns well with modern DevOps practices. Teams can iterate quickly without coordinating every detail of the deployment with other departments.

Is Medusa 2.0 harder or easier for developers?

Despite the added structure, Medusa 2.0 does not increase complexity. Instead, it removes ambiguity and enforces patterns that make development predictable.

Developers benefit from:

• consistent module lifecycle rules,
• explicit domain boundaries,
• a clear override and replacement strategy,
• a stable upgrade path,
• cleaner codebases and less technical debt over time.

Legacy commerce engines often struggle with compatibility issues between extensions and core logic. Medusa avoids this by keeping responsibilities separate from the start.

Why Medusa 2.0’s modular architecture matters

Medusa 2.0 marks a shift from patching an expanding plugin ecosystem to building a well-defined modular platform. By isolating domains, introducing workflow-driven processes and giving each module its own lifecycle, Medusa offers engineering teams a system that grows with the project — not against it.

For companies building headless commerce at scale, this means:

• lower operational risk,
• faster delivery cycles,
• predictable architecture,
• reduced long-term maintenance cost,
• easier migrations and incremental adoption.

Planning to adopt Medusa 2.0 in your project?

The U11d team designs, builds and maintains modular commerce architectures based on Medusa 2.0. We support audits, migrations, module development, workflow design and custom integrations with external services.

If you want to move toward a modular, future-proof stack — let’s discuss how we can help you build it.