GitHub - unchainedshop/unchained: High-Performance Headless Node.js ESM E-Commerce Framework

Unchained Engine

Licensed under the EUPL 1.2

Unchained Engine is a modular, API-first e-commerce platform built as a monorepo with npm workspaces. It provides a complete solution for building custom e-commerce applications with GraphQL APIs, extensible plugin architecture, and support for modern use cases like subscriptions, quotations, and tokenized products.

View Documentation

Quickstart

Prerequisites

• Node.js >=22 (see .nvmrc)
• MongoDB (or use MongoDB Memory Server for development)

Create a New Project

Then navigate to http://localhost:4000/ to view the welcome screen. Login with:

• User: admin@unchained.local
• Password: password

Run Local AI for Copilot

A minimum of 24GB VRAM is needed for this.

llama-server -hf ggml-org/gpt-oss-20b-GGUF --ctx-size 0 --jinja -ub 2048 -b 2048

Package Architecture

Unchained Engine is organized in a hierarchical structure:

platform     → Highest level orchestration, combines all packages
    ↓
api          → GraphQL API layer with Express/Fastify adapters
    ↓
core         → Business logic coordination, integrates all core-* modules
    ↓
core-*       → Domain-specific modules (users, products, orders, etc.)
    ↓
infrastructure → Base utilities (mongodb, events, logger, utils, roles)

Packages

Platform & API

Core Domain Modules

Business logic modules for e-commerce functionality:

Infrastructure

Foundational utilities used across all layers:

Extensions

Admin UI

Examples

Plugin Architecture

Unchained uses a Director/Adapter pattern for extensibility. Directors manage collections of adapters that implement specific behaviors.

Available Directors

See the Core README for detailed documentation on creating custom adapters.

Available Plugins

The @unchainedshop/plugins package includes:

Payment

• Stripe, PayPal, Braintree, Datatrans, Saferpay
• Payrexx, Cryptopay, Apple IAP
• Invoice (standard and prepaid)

Delivery

• Post (manual shipping), Store pickup, Digital delivery

Pricing

• Product catalog pricing, Currency conversion, Tax calculation (Swiss VAT)
• Order-level and product-level discounts, Price rounding

File Storage

• MongoDB GridFS, MinIO/S3-compatible storage

Workers

• Email (Nodemailer), SMS (Twilio, Bulkgate), Push notifications
• Currency rate updates (ECB, Coinbase), Bulk import

Events

• Node.js EventEmitter, Redis pub/sub, AWS EventBridge

Development

Commands

npm install          # Install all dependencies
npm run dev          # Start development with hot-reload
npm run build        # Build all packages
npm test             # Run all tests
npm run lint         # Lint and fix code

Testing

npm run test:run:unit         # Run unit tests only
npm run test:run:integration  # Run integration tests
node --test path/to/test.ts   # Run a single test file

Project Structure

unchained/
├── packages/           # All npm packages
│   ├── platform/       # Main entry point
│   ├── api/            # GraphQL API
│   ├── core/           # Business logic orchestration
│   ├── core-*/         # Domain modules
│   ├── plugins/        # Official plugins
│   ├── ticketing/      # Ticketing extension
│   └── ...             # Infrastructure packages
├── examples/           # Example implementations
│   ├── kitchensink/    # Full-featured example
│   ├── minimal/        # Minimal setup
│   └── ...
└── tests/              # Integration tests

Migration Guide

See MIGRATION.md for upgrade instructions between major versions.

Claude Code Integration

Unchained provides a Claude Code skill to help with upgrades:

claude skill install https://docs.unchained.shop/skills/upgrade-unchained

This skill guides Claude through fetching the correct migration guide, changelog, and examples for your target version.

Resources

• Changelog
• Benchmarks

Contributing

Please see our Contribution Guidelines.

Code of Conduct

See our Contributor Covenant Code of Conduct.

License

EUPL-1.2