Medusa: an open-core commerce platform you extend with TypeScript

The gap Medusa fills: commerce primitives instead of a finished store

Most commerce software asks you to bend your business into its data model. Medusa takes the opposite position. The README describes it as "a commerce platform with a built-in framework for customization that allows you to build custom commerce applications without reinventing core commerce logic." The intended audience is listed explicitly: advanced B2B or DTC stores, marketplaces, distributor platforms, point-of-sale systems and service businesses. What those have in common is that a standard cart-to-checkout flow is not the hard part. The hard part is pricing rules, fulfillment logic, inventory behaviour and whatever internal system has to agree with the order record.

So the unit of adoption is not a theme or a plugin. It is an application. You get the primitives (products, carts, orders, inventory, fulfillment, payments) and you write the parts that are specific to you. The README points to a commerce modules page in the docs and an architecture overview, which is where the real detail lives; the README itself is a signpost, not a manual. That is worth knowing before you start, because it means the quality of your experience depends on the documentation site rather than on the repository front page.

How the customization framework is put together

The repository is a Yarn workspaces monorepo. The root package.json declares workspaces across packages/medusa, packages/modules/*, packages/modules/providers/*, packages/plugins/*, packages/core/*, packages/framework/*, packages/cli/*, packages/admin/*, packages/design-system/* and packages/generated/*, with integration-tests/**/* as its own workspace. That layout tells you the architecture better than any prose summary: commerce capability is split into modules, providers sit behind those modules for external services, and the admin dashboard is a separate package built on a shared design system.

The practical consequence is that extending Medusa is a matter of adding or replacing a module or a provider rather than patching a monolith. The root also carries turbo.json, a changeset directory and a CHANGELOG, so releases are cut from a monorepo pipeline and individual packages version together. The default branch is develop, and the latest release recorded is v2.19.0 on 2026-08-13, with v2.18.0 and v2.17.2 before it. The last push to the repository was on 2026-08-13 as well, so the code and the release are in step.

One caveat on the layout: the root also contains directories such as memory/ and thoughts/, which are not described in the README. Do not read meaning into them. If you need to know what a package does, the workspace globs and the docs are the reliable sources.

Installing Medusa and running a first application

The README gives two starting points. The fastest, in its words, is Medusa Cloud, described as a managed environment with automated deployments, scaling and maintenance. For a local setup, the README sends you to the documentation at docs.medusajs.com/learn rather than listing commands itself. The repository does not contain an install snippet on the front page, so treat the documentation as the source of truth and do not copy commands from blog posts, including this one, without checking them.

The shape of the local workflow is a CLI-driven project scaffold. The root workspace list includes packages/cli/*, which is where the create and development commands live. The documentation's learn section is where the exact invocation is published, and it changes between releases, so pin your reading to the version you intend to run.

What you should verify before writing any application code:

cat .nvmrc

The repository pins a Node version in .nvmrc at the root. Match it. A mismatch between your local Node and the one the monorepo targets is the most common way a fresh scaffold fails in ways that look like framework bugs.

Once a project is generated, the development server is started through the CLI and the admin dashboard is served alongside the API. The documentation covers the port and the environment variables; the README does not, and the repository root does not ship a .env example. Plan to read the learn section end to end before your first commit, because the configuration surface is larger than a typical web framework's.

Where Medusa is the wrong choice

The open-core split is the first thing to price. The README states that Medusa uses an open-core model, that the core is MIT licensed, and that "RBAC-based Enterprise Edition materials identified in ENTERPRISE-LICENSE.md require a commercial agreement with MedusaJS, Inc." If role-based access control is a requirement rather than a nice-to-have, you are not evaluating an MIT project. You are evaluating a commercial product with an MIT core, and the boundary between the two is defined in a file you should read before you build a roadmap on top of it.

The second limitation is structural rather than legal. Medusa hands you a framework and expects you to build an application. Teams that want a store they can configure and launch without engineering involvement will spend more time than they saved. The README's own list of target use cases (B2B, marketplaces, distributor platforms, PoS, service businesses) is a list of situations where off-the-shelf commerce software tends to break down. If your requirements are ordinary, that complexity is a cost with no matching benefit.

The third is upgrade surface. Releases are frequent: v2.17.2, v2.18.0 and v2.19.0 landed between 2026-07-01 and 2026-08-13. The README's answer to this is to follow the release notes, and the repository has a changeset directory and a CHANGELOG to support that. But the upgrade burden scales with how much custom logic you wrote against the framework. The README does not document rollback, so a failed upgrade is your problem to solve with your own database and deployment tooling.

Medusa against a hosted commerce SaaS

The obvious alternative for many teams is a hosted commerce platform where the storefront, admin and checkout are provided and you extend through configuration and a plugin API. The difference in approach is where the code lives. With a hosted platform you rent a running system and write against its extension points; the vendor owns the schema, the release schedule and the failure modes. With Medusa you run the application, the modules are in your dependency tree, and a change to order or fulfillment behaviour is a change to your codebase.

That is not automatically better. It is a different allocation of responsibility. A hosted platform will absorb a database migration for you. Medusa will not, and the repository gives you a monorepo, a CLI and a changeset pipeline as the tools to manage that yourself. Choose Medusa when the commerce logic is genuinely the product and you need to own it. Choose a hosted platform when the commerce logic is a supporting function and owning it is a distraction.

Maintenance, licensing and the cost of staying current

The repository is not archived and the last push was on 2026-08-13, which is recent enough that the project is being worked on rather than merely hosted. The release cadence visible in the repository is roughly monthly: v2.17.2 on 2026-07-01, v2.18.0 on 2026-07-23, v2.19.0 on 2026-08-13. v2.19.0 is titled "Vite v7 Update, Inventory Export, Custom Fulfillment Addresses", which is a useful signal about what a minor release contains: build tooling changes and feature additions together. Build tooling changes are the ones that tend to break local development, so read the release notes rather than the version number.

On licensing, the README is explicit that the core is MIT and that Enterprise Edition RBAC materials fall under a separate commercial agreement described in ENTERPRISE-LICENSE.md. The repository also carries a SECURITY.md and a CONTRIBUTING.md. This is not legal advice, and the licence files are the only authority on what you may do; if your organisation has a review process, ENTERPRISE-LICENSE.md is the document it needs, not the README summary.

Editorial conclusion

Adopt Medusa if you are building a commerce application in TypeScript and expect to write your own logic around orders, inventory or fulfillment rather than configure a hosted storefront. Do not adopt it if you want a finished admin experience with no engineering time attached, or if the RBAC features in the Enterprise Edition are on your critical path and you have not priced the commercial agreement. Before committing, read ENTERPRISE-LICENSE.md against your feature list, check the release notes for the version you pin, and confirm on the documentation site which database and Node version the current release expects.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes