Skip to content

About

Open-source self-hosted ecommerce: NestJS API, Angular admin, SSR storefront. FR/EN/AR RTL, cash on delivery, one-command install. MIT.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

11 stars

Watchers

0 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

The Merchant Engine

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

MIT license CI Latest release Last commit Stars Issues As seen on Open Source Alternatives The Merchant Engine badge Node 22

The Merchant Engine on Product Hunt

A cash on delivery order on the storefront demo, from the home page to the order confirmation

Why

  • 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.

Screenshots

Admin dashboard Admin product editor
Storefront home page Storefront product page

Features

  • 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_KEY still 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/cdk and 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.

Quickstart

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 Windows

The 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 terminals

Sign 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.

Architecture

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]
Loading

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.

Repository layout

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.

Documentation

The full guide lives at themerchantengine.com/docs. Its source is docs/site/:

Deploy

Two commands on a prepared Linux box:

git clone https://github.com/Xdabier/themerchantengine.git /srv/themerchantengine
cd /srv/themerchantengine && ./setup.sh --profile engine

Use --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, security and community

  • CONTRIBUTING.md explains how to propose a change. Run npm run gate before 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.

Need it built or run for you?

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.

License

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.

Contributors

Contributors

About

Open-source self-hosted ecommerce: NestJS API, Angular admin, SSR storefront. FR/EN/AR RTL, cash on delivery, one-command install. MIT.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages