Vendure: a TypeScript headless commerce core you extend with plugins, not forks

Who Vendure is for, and the problem it removes

Commerce platforms usually force one of two choices. A hosted suite gives you a working catalog, cart and checkout, but the moment your pricing rules or order lifecycle differ from its model you are writing workarounds. A composable stack gives you freedom, and in exchange you assemble catalog, orders, customers, promotions, channels, tax, shipping, payments and stock yourself, then keep them consistent.

Vendure takes the position that these are the same backend. The README describes it as a headless commerce platform where you "model your catalog, orders, pricing, promotions, and customers on one backend you can change at the core", and lists D2C, B2B, marketplace and omnichannel as the models it is meant to run. The stated goal is that teams "don't choose between a rigid suite and a DIY composable stack".

The audience that follows from that is narrow and specific: engineering teams with TypeScript skills who intend to own a commerce backend in production. A single merchant who wants a themed storefront and no server has nothing to do here. A team that has already built its own order service and only needs a payment page will find the built-in catalog and order model to be more than they asked for.

One GraphQL core, two APIs, and plugins as the extension contract

The architecture named in the README is a Node.js and NestJS backend exposing GraphQL, with a React and TanStack admin dashboard on top. The repository confirms the split at the schema level: schema-shop.json and schema-admin.json sit at the top level, which matches the two-API model that headless commerce platforms typically use, a customer-facing shop API and an administrative API.

The extension mechanism is the part worth understanding before you commit. Vendure's claim is that you "extend or override any part of the system through stable plugin contracts and service overrides", adding custom entities, pricing logic and workflows without patching core. That is a different promise from a platform that only exposes webhooks and a REST surface. A plugin runs inside the same process and the same type system as the core, so a custom entity participates in the same GraphQL schema and the same database.

The trade-off is that your customizations compile against Vendure's internals. Service overrides and entity extensions are powerful precisely because they reach into the framework, and that reach is what makes major-version upgrades a project rather than a version bump. The README's claim of "stable plugin contracts" is the mitigation, not an absence of the problem.

One further consequence of GraphQL is stated plainly: the schema is introspectable, which the README notes makes it "straightforward to wire up LLM tool-calling, MCP servers, and agent frameworks". That is a real property of the API surface, not a feature you install.

Installing Vendure and getting a shop running

The README is explicit that you should not clone the repository to build a store. The monorepo holds @vendure/core, the admin dashboard, the CLI, the official plugins and an e2e harness; the README says to "clone this repo only to contribute to Vendure itself".

Project creation goes through the scaffolder, which produces a server, an admin dashboard and a GraphQL API ready to run:

npx @vendure/create my-shop

The prerequisites are stated in the README: Node.js 20.19+ or 22.12+, and a SQL database from PostgreSQL, MySQL, MariaDB or SQLite. The root package.json tightens the first of those into an engines field of ^20.19.0 || >=22.12.0, so a Node 21 or an early Node 22 install will not satisfy it.

If you want databases running locally while you work, the monorepo ships a docker-compose.yml whose comment says it "contains the services required to develop and test Vendure locally". It defines MariaDB, MySQL 8.0, MySQL 5.7 and PostgreSQL services, each with a vendure-dev database and a vendure user, with the SQL ports published on 3306 and 5432 respectively. Note that the compose file is a development aid, not a deployment recipe.

docker compose up -d postgres_12

The full walkthrough, including configuration options, is in the Getting Started guide the README links to at docs.vendure.io. The README does not document a rollback path for a scaffolded project, so treat the generated directory as the thing you version.

Where Vendure is the wrong tool

The licence is the first constraint, and it is easy to misread. Vendure is released under GPLv3. The README addresses the most common worry directly: "Building against the GraphQL API doesn't make your storefront or services subject to GPLv3". There is also a plugin license exception, with a file at license/plugin-exception.txt, that lets you "release your own Vendure plugins under any license you choose". The licensing FAQ lives at license/license-faq.md.

What that means in practice is that the boundary runs through your plugin code, not through your storefront. A storefront that talks to the shop API over GraphQL is on the safe side of the line as the README describes it. Code that extends the core is where the exception matters, and that is a question for your own counsel rather than for this article.

The second constraint is operational. Vendure "runs anywhere Node.js runs", which the README frames as ownership: "You own the deployment, the data, and the stack." That is a benefit for a platform team and a cost for anyone without one. There is no storefront in the box. The admin dashboard is included, but the customer-facing surface is something you build against the GraphQL API.

The third is scope. Vendure is a commerce backend, not a CMS, not a search service, and not a warehouse system. The README notes that the local development compose file includes Elasticsearch and Redis alongside the databases, which tells you what a realistic deployment looks like at scale, but none of that is part of the core promise.

Vendure compared with Medusa, and with building it yourself

The comparison people reach for is Medusa, and the difference that matters is the extension model rather than the feature list. Both are TypeScript headless commerce backends with a GraphQL or REST API and a separate admin. Vendure's distinguishing claim is that you change core behaviour through plugin contracts and service overrides, with custom entities living in the same schema and the same database as the built-ins. If your differentiation is in pricing, promotions or order workflows, that is the axis to evaluate, because it decides whether your customizations survive an upgrade or become a fork you maintain.

The other real alternative is building the commerce layer yourself on NestJS or another Node framework. That gives you total control and no framework upgrade to absorb. It also means implementing catalog, orders, customers, promotions, channels, tax, shipping, payments and stock before you ship anything a customer can buy. Vendure's argument is that those are "commerce building blocks from day one", and that the same extension model then carries the parts specific to your business.

There is a middle path the README names. Vendure Cloud is described as a fully managed PaaS with a modern CLI and agent-first DevOps workflows, for teams that want git-push deploys. Vendure Platform is an "optional enterprise capability layer" adding SSO, approval workflows and B2B pricing "on the same open-source core". Both are commercial, with pricing on vendure.io/pricing, and both are separate from the GPLv3 repository.

Release cadence, upgrade cost and licence upkeep

The repository is not archived, and the last push was on 2026-09-21. Recent releases are v3.7.1 on 2026-07-14, v3.7.2 on 2026-08-03 and v3.7.3 on 2026-09-02, so patch releases arrive roughly monthly. The README confirms the pattern: "Patch releases ship regularly", pointing at the release notes.

That cadence is comfortable for patch upgrades and says nothing about major versions. The upgrade cost that matters is the one created by your own plugins. Every service override and entity extension is a place where a core change can reach you, and the README's "stable plugin contracts" is the mechanism that is supposed to contain it. Budget for reading the changelog on major versions; the repository keeps CHANGELOG.md alongside CHANGELOG_v1.md and CHANGELOG_v2.md, so the history is at least legible.

On licence, the practical items to track are three files: LICENSE.md for the GPLv3 terms, license/plugin-exception.txt for the exception that lets you license your own plugins freely, and license/license-faq.md for the interpretation Vendure publishes. Vendure Platform is licensed commercially and separately. None of that is legal advice, and the plugin exception is the one document worth reading in full before you decide how to distribute plugin code.

Editorial conclusion

Adopt Vendure if your team already writes TypeScript and you need to change core commerce behaviour, such as pricing or order workflows, without maintaining a fork. Do not adopt it if you want a hosted storefront with no backend to run: the README says you own the deployment, the data and the stack, and the repo's docker-compose.yml exists only for local development services. Before committing, verify two things: that your Node.js version satisfies the engines field (^20.19.0 || >=22.12.0), and that your intended use of the plugin license exception fits how you plan to distribute your plugins. The repository itself is the contribution target, not the starting point; the README says to run npx @vendure/create rather than clone it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. vendurehq/vendure on GitHub