Control and ownership
You get full ownership and control of the code. No vendor dependency, no third-party roadmap — your team controls hosting, deployment and performance.
CH · 01
What is SHOPin?
A working definition before everything else.
SHOPin is an Agnostic Frontend Accelerator — or, if you prefer the longer name, a Composable Storefront Accelerator. It is a solution layer designed to overcome the practical difficulties of building a consumer experience on a purely decoupled (MACH) backend.
It is not a platform. It is not a UI library. It is a coherent set of conventions, contracts and runnable applications you fork, deploy, and own.
Think of SHOPin as the missing layer between a MACH stack and a launchable storefront — the part nobody wants to write twice.
CH · 02
Why SHOPin is just
an accelerator.
SHOPin ships as a source-code framework, not a closed platform. Your competitive edge lives in custom checkout logic, bespoke UI and business-specific integrations — a generic SaaS cannot accommodate that. The accelerator is the starting framework you make yours.
Focus on philosophy, not updates
Your team maintains SHOPin's architecture and patterns, not our release notes. We do not force version updates. Your business evolves on your roadmap, not ours.
Acknowledge custom complexity
Your custom features will introduce project-specific challenges in performance, scalability and security. The accelerator gives you the best foundation — operating it well is still real work.
CH · 03
SHOPin architecture.
Architecture is four distinct layers of thinking, each handling a different class of concerns. SHOPin's core principle is to keep these kinds of complexity honestly separate — so visual design, rendering, orchestration and contracts never bleed into each other.
Visual thinking
Separates visual design and component composition from business logic. The layer centralises your visual language so UI is independent, reusable and testable in isolation — design complexity stays out of application logic.
Rendering thinking
Separates page composition and rendering strategy from data orchestration. Routing, SSR and page assembly never mix with fetching or transformation — performance work stays independent of backend complexity.
Orchestration thinking
Separates data aggregation and transformation from both presentation and backend services. Multiple services (CMS, commerce, search) merge into unified responses — swap backends without touching presentation code.
Contract thinking
Separates interface definitions from implementation. Strict shared contracts between layers keep data structures stable regardless of backend change — no cascading edits, clear boundaries.
Layer synergy
How the layers cooperate.
The flow of data and responsibilities between UI, presentation, BFF and the contracts that bind them — on one example product page.
Visual thinking
UI
Rendering thinking
Presentation
Header
Gallery
Title
Price & Info
Description
Orchestration thinking
BFF
Map APIs to SHOPin product image contracts
Aggregates CMS, commerce, search, auth, and other services into a single response tailored to this page.
Connected APIs
CMS API
Commerce API
Search API
Auth API
Other services (payments, personalization, etc.)
Contract thinking
Contracts
Shopin product image (core/contracts)
interface ProductImageResponse {
src: string;
alt: string;
}
interface ProductGalleryResponse {
images: ProductImageResponse[];
}
CH · 04
Monorepo structure.
All of it lives in a single monorepo — no juggling repositories, no diverging tooling. Five workspace categories, each with a clear job.
| Category | Purpose | Usage |
|---|---|---|
| apps/* | Product applicationsRunnable apps that ship to users. | Any runnable application or site. |
| core/* | Shared packagesReusable code, types and tooling configs. | Contracts, i18n, ESLint, Prettier, TypeScript configs. |
| integrations/* | Backend integrationsCommerce and auth providers. | commercetools-api, commercetools-auth, mock-api. |
| config/* | Central configurationCross-app constants and config. | Shared constants consumed by apps and core. |
| demo/* | Optional demosPrototyping and showcases. | Safe to remove for production. Dedicated to showing SHOPin possibilities. |
CH · 05
Project structure.
A tour of the directories. Open the repo and you will recognise it from this map.
- ├─ bff/NestJS — backend for frontend.
- ├─ presentation/Next.js — frontend & UI components.
- ├─ storybook/Storybook — stories for UI components.
- └─ typedoc/Typedoc — generates docs from core/contracts.
- ├─ contracts/Internal contracts consumed by apps and integrations.
- ├─ i18n/Translations and language utilities.
- ├─ logger-config/Shared logging (Pino levels, redaction, correlation IDs) for BFF and presentation.
- ├─ eslint-config/Shared ESLint config.
- ├─ prettier-config/Shared Prettier config.
- └─ typescript-config/Shared TypeScript configs and path aliases.
- ├─ commercetools-api/Commerce API client and mappers for commercetools.
- ├─ commercetools-auth/Auth services — login, register, session, tokens.
- └─ mock-api/Mock commerce backend for development and demos.
- └─ constants/Shared constants and cross-workspace configuration.
- ├─ data-source-header-reader/Middleware that reads the data-source header.
- ├─ data-source-selector/Demo UI for switching between data sources.
- └─ mocked-payment-service-provider/Demo payment provider used by the example checkout.
Everything under demo/ exists only to showcase SHOPin. It is safe to delete before real development begins.
Aligned on principles?
Now go compose
your storefront.
Clone the repo, wire your backends and start with patterns that already know how to be composed.