Mercatus Liber

A free, MIT-licensed, headless commerce framework: an open alternative to Shopify that you own and can run anywhere.

No per-transaction cut, no app-store tax, no required vendor. Every subsystem is its own package behind a narrow interface, so you can swap the database, CMS, payments, auth, or fulfillment provider without touching the rest. Everything a person can do in the admin, an AI agent can do through the same interfaces over MCP.

Live demo · Docs · Wiki · Vision and roadmap · Contributing

Status: pre-1.0, not yet on npm. The packages run in production on the demo stores below, but you consume them from this monorepo for now. npm publishing is planned after a dogfooding period on a real store. Expect breaking changes between versions; see CHANGELOG.md.

See it running

Three sample stores, all built from the same open-source app (apps/reference-storefront). They are meant to be read and copied: each one is a public example of building a storefront on the framework.

Store	What it is	Theme	Backend	Links
The Print Shop	Embroidery and custom prints	editorial	Postgres	standalone · shared
Northline Home Tech	Smart-home installer with service-area pages	northline	Postgres	standalone · shared
Broadleaf & Co.	Artisan and handmade goods	vibrant	Convex	standalone · shared

The demos run in sandbox payment mode, so no real charges happen. Details: sample stores.

Quick start

Requires Node 22.13 or newer and pnpm 11 (corepack enable picks up the pinned version).

git clone https://github.com/mdostal/mercatus-liber.git
cd mercatus-liber
pnpm install
pnpm turbo run build --filter=@mercatus-liber/reference-storefront^...
pnpm --filter @mercatus-liber/reference-storefront dev

Then open http://localhost:3000/demo/print-shop. No accounts or environment variables are needed: with nothing configured, the app runs on in-memory SQLite and reseeds on restart. Set DATABASE_URL or SQLITE_FILE_PATH to persist the catalog. Every variable is listed in the configuration reference.

To start your own store, use the scaffolder: packages/create-store.

What's in the box

Commerce core: catalog with multi-axis variants, a marketing catalog kept separate from the sales catalog, search, product pages, long-lived cart, checkout and orders, customer accounts, inventory.

Merchandising and content: per-page CMS (no forced whole-site theme), 10 theme bundles, promotions, bundles, recommendations, advertising, reviews, storefront views, service-area pages, community goals, and made-to-order customization with an admin-defined pricing engine.

Operations: role-based admin auth, fulfillment, shipping, webhooks, accounting sync, analytics, internal BI, a store scaffolder, auto-update, and a Shopify migration tool.

Outside apps: a key-authenticated store API and typed client, so apps such as flayr can import the catalog and run promotions (packages/store-api, flayr plan).

AI access: MCP server and tool catalog calling the same subsystem interfaces as the admin (packages/ai-interface).

Adapters

An adapter implements a subsystem's interface for one provider. "Live" means running on the demo stores. "Unverified" means built and unit-tested against the provider's documented API, but never run against a real account.

Area	Adapter	State
Database	adapter-sqlite	Local and zero-config default
Database	adapter-postgres, adapter-postgres-inventory	Live
Database	adapter-convex	Live
Database	adapter-mongodb	Built and tested, not live
Commerce backend	adapter-shopify	Unverified; available through create-store, not used by the demos
CMS	adapter-sanity	Live
Admin auth	adapter-clerk	Live
Payments	Stripe (in payments)	Live in sandbox mode
Payments	adapter-paypal	Unverified
Print on demand	adapter-printful, adapter-printify	Unverified; activates when credentials are set
Shipping	adapter-shippo	Unverified
Images	adapter-cloudinary	Unverified
Accounting	adapter-quickbooks	Unverified
Analytics	PostHog (in analytics)	Live
Analytics	GA4 (in analytics)	Unverified

Database support is not uniform yet. Postgres covers nearly every commerce subsystem, while Convex, MongoDB, and SQLite mainly cover the catalog and customization. The integrations catalog has per-adapter detail and the environment variables for each.

Leaving Shopify: migrate-shopify reads a store once and writes it into native persistence, with a dry-run default. It covers products, collections, and inventory, but not orders, customers, or images yet. adapter-shopify is the other route: it keeps Shopify as the backend.

Build on it

Write a plugin for anything that should react to commerce events. A plugin gets the event bus and nothing else:

import type { Plugin } from "@mercatus-liber/plugins";

export const orderLogger: Plugin = {
  name: "order-logger",
  init({ events }) {
    events.subscribe<{ orderId: string }>("checkout.order.placed", async ({ orderId }) => {
      console.log(`order placed: ${orderId}`);
    });
  },
};

Write an adapter to connect a new provider: implement the subsystem's interface in a new packages/adapter-* package. See the adapter pattern.

Looking for something to build? Wishlists, gift cards, subscriptions, returns, marketplace sync, and more are listed in VISION.md's community frontier.

UI: how it's organized

Layer	Where	State
Sample stores	apps/reference-storefront	Live, public, and meant to be copied
Theme tokens and bundles	packages/theming	Live, 10 bundles
Other storefront components	apps/reference-storefront/components	Live, but navigation, home, category, and CMS components are still inside the app
Common components	packages/storefront-ui	Partial: cart and product page templates, plus the customizer and price breakdown, live on The Print Shop's dad cap
Customizer Web Component	packages/customization-ui	Framework-free, but still on hex colors and not used by a sample store
Default UI	Not built	Planned: move the remaining app components into storefront-ui as a default storefront

What's being worked on

• Customization: a quote flow for request-only options; see its known limitations.
• UI: moving the rest of the app's components into storefront-ui as a default UI.
• Release: npm publishing, after dogfooding on a real store.

How it's built

packages/    52 packages: core types, one package per subsystem, one per adapter
apps/
  reference-storefront/   the sample stores (Next.js)
  docs/                   the docs site (Nextra)
docs/        architecture and one reference doc per subsystem

One rule holds it together: no subsystem imports another subsystem's internals. They share core types, adapter interfaces, and a typed event bus. If replacing subsystem A means changing code inside subsystem B, that's a bug. apps/reference-storefront/lib/services.ts is where concrete adapters get chosen. Read more in docs/ARCHITECTURE.md.

Documentation

• Getting started
• Architecture
• Subsystem reference (28 docs)
• Configuration reference
• Integrations catalog
• Each package's own README.md

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md. Please report security problems as described in SECURITY.md.

License

MIT