The Merchant Engine, open-source self-hosted ecommerce: a NestJS API, an Angular admin and an SSR storefront. French, English and Arabic (RTL), cash on delivery, one-command install. MIT.
If this is useful, a star helps others find it. Tell me what is missing in the feedback discussion.
Storefront demo · Admin demo · Docs · Try it locally · Discussions · Have it built and run for you
- One generic build. Every store-specific value (identity, brand, locales, currency, domains, third-party keys) is entered once through the install stepper and lives in the database and the environment. No fork per client.
- The whole stack in one repository. API, admin and storefront share one schema, one set of types and one test suite, so a change lands everywhere at once.
- Built for agencies. A developer with a server, a bucket, a domain and the third-party accounts ready goes from clone to a live, empty store in one sitting.
- MIT. Use it for any store, paid or not. No license key, no tiers, no caps.
![]() |
![]() |
![]() |
![]() |
- Catalogue: products, variants, categories, inventory, reviews and full-text search. See What you get.
- Orders: cart, checkout, orders, returns, invoices, gift cards and promotions. See Checkout and orders.
- Content: CMS pages, home sections, SEO and translatable fields in every locale you enable. See Content and sections.
- Payments: cash on delivery, manual bank transfer, gift cards and card payment through Stripe. The operator enters the Stripe keys in the admin (
STRIPE_API_KEYstill works as a fallback), and the shopper pays in an embedded form or on a hosted page. More card providers plug in behind one interface. See What you get. - Mail: Resend (
RESEND_API_KEY), plus a console transport that logs mail in development. See Environment variables. - Storage: local disk or any S3-compatible bucket (
S3_BUCKET). See Install on a server. - Shipping: zones and methods with the rates you enter in the admin, and a carrier list for tracking links. See Store settings.
- Admin: Angular 21 with signals,
@angular/cdkand Tailwind 4.3, themed at runtime from the store's brand settings. See Store settings. - Storefront: Analog SSR with locale routing and a documented API contract, so you can also build your own.
- Roles and permissions: granular admin permissions, listed in Permissions.
Planned, not built yet:
- More mail adapters, such as SMTP.
- Live shipping adapters that fetch carrier rates and labels.
With Node 22 and Docker installed, three commands give you a local store:
git clone https://github.com/Xdabier/themerchantengine.git
cd themerchantengine
./setup.sh --local # or ./setup.ps1 on WindowsThe stepper asks for the store's identity, brand, locales, money and owner account, then starts the stack. Install locally walks through each question.
To work on the engine itself, run the services from source:
npm install && npm run docker:up && cp .env.example .env
npm run db:setup && SEED_DEV_OK=1 npm run db:seed
npx nx serve api # then admin and storefront in two more terminalsSign in to the admin at http://localhost:53200 as superadmin@merchants.test with Admin123!. Development environment covers the env file, the test stack, everyday commands and what to do when the checkout misbehaves.
flowchart LR
shopper([Shopper]) --> storefront[Storefront<br/>Analog SSR]
staff([Store staff]) --> admin[Admin<br/>Angular 21]
storefront -->|/api/v1| api[API<br/>NestJS modular monolith]
admin -->|/api/v1| api
api --> pg[(PostgreSQL<br/>Prisma 7)]
api --> redis[(Redis<br/>cache and BullMQ)]
redis --> workers[Workers<br/>mail, media, sitemaps, webhooks]
api --> storage[(Local disk<br/>or S3)]
api --> stripe[Stripe]
workers --> resend[Resend]
The API is one NestJS process split into modules that never touch each other's tables. The storefront reads the store's identity, brand, locales and money from GET /v1/store/config at runtime, so one build serves every store. Topology shows how the pieces sit on one or two servers.
themerchantengine/
├── apps/
│ ├── api/ # NestJS backend (port 53000)
│ ├── admin/ # Angular 21 admin (port 53200)
│ └── storefront/ # Analog.js SSR storefront (port 53300)
├── libs/ # shared types, services and UI for the apps
├── prisma/ # schema and seeds
├── tools/setup/ # the install stepper behind setup.sh
├── docs/site/ # the documentation site
└── scripts/ # setup, release and maintenance scripts
Repository layout explains every folder and the rules each app follows.
The full guide lives at themerchantengine.com/docs. Its source is docs/site/:
- Getting started: what to have ready, what the stepper asks and the first hour after install.
- Operate: updates, rollback, backups, TLS, logs and store settings.
- Customize: the development environment, conventions, testing and gates, and releasing your fork.
- Build a storefront: the storefront API contract, step by step.
- Reference: environment variables, CLI, error codes, the admin API and the storefront API.
- Troubleshooting for install problems.
Two commands on a prepared Linux box:
git clone https://github.com/Xdabier/themerchantengine.git /srv/themerchantengine
cd /srv/themerchantengine && ./setup.sh --profile engineUse --profile storefront on a second box, or --profile both to run everything on one. The stepper verifies each third-party integration live, installs the stack and ends with backend server installed successfully! or storefront server installed successfully!, the admin URL and the owner login. A release tarball works the same way and skips the stepper build.
Read Install on a server first, then the go-live checklist.
- CONTRIBUTING.md explains how to propose a change. Run
npm run gatebefore you open a pull request; the public tree installs no git hooks. - ROADMAP.md lists what is planned next and which issues are open for contributors.
- SECURITY.md explains how to report a vulnerability privately. Please do not open a public issue for one.
- CODE_OF_CONDUCT.md applies to every space of the project.
- Questions and ideas go to Discussions. Feedback, good or bad, goes to the feedback discussion. Bugs go to Issues. If you tried to install it, the "I tried to install it" template takes two minutes.
- Every release is listed in the CHANGELOG.
The engine is free to use on your own. If you would rather not run it yourself, hire Badii Boutar, who builds the engine and works as Badii Studio. He installs, customizes, hosts and maintains stores built on it. Write to badii@badii.studio.
themerchantengine is licensed under the MIT License. See LICENSE for the terms and NOTICE for the copyright and trademark note. Questions go to Badii Studio at badii@badii.studio.





