How to setup SHOPin
This page is a setup guide: clone the repository, configure environment variables, install dependencies, and run the dev stack. For a high-level overview (repository layout, what ships in the monorepo), see the Getting started page.
Clone or fork the SHOPin storefront accelerator repository, then follow the steps below.
Prerequisites
- Node.js >= 24 (confirm with
enginesinpackage.jsonin your clone) - npm (see
packageManagerin the repository rootpackage.json) - A Commercetools project and API client for the default BFF (catalog, cart, customer, order, auth, and related flows)
- Optional: a Contentful space if you use the CMS integration
In practice the accelerator is hard to run without Commercetools right now: mock does not cover every storefront case, and the default BFF still uses Commercetools for several flows (including customer, order, and auth when catalog runs on mock). What mock covers is documented in Set up Mock .
Steps
1. Set up environment files
Create a root .env from the template:
# Repository root (read by BFF and presentation)
cp .env.example .env
Fill in values using Environment variables and the comments in .env.example. Data sources and how integrations fit together: Integration setup (and Set up Mock if you use the mock data source).
2. Install dependencies
npm ci
Use npm ci for a clean install from lockfile.
3. Start development servers
From the repository root, either run setup once then dev (as in the accelerator README.md), or run dev only — Turborepo runs the setup task before dev per turbo.json.
npm run setup
npm run dev
Alternatively:
npm run dev
When services are running, use the default local URLs from the accelerator README.md (storefront, BFF, Swagger, Storybook, Typedoc).
Environment variables
Environment variables configure the BFF and the Next.js presentation app. Copy .env.example at the repository root to .env and edit it. The variable reference table groups each name by scope (required, conditional, optional). The example block below follows the order in .env.example, which is not the same as that grouping.
Example root .env:
NEXT_BFF_INTERNAL_URL=
NEXT_PUBLIC_BFF_EXTERNAL_URL=
FRONTEND_URL=
# Logging (optional)
LOG_LEVEL=info
LOG_PRETTY_PRINT=true
# BFF rate limiting (optional)
BFF_RATE_LIMIT_ENABLED=true
BFF_RATE_LIMIT_TTL=60000
BFF_RATE_LIMIT_LIMIT=100
BFF_RATE_LIMIT_SECURE_TTL=60000
BFF_RATE_LIMIT_SECURE_LIMIT=5
# Contentful (optional; required if using Contentful as CMS)
CONTENTFUL_ACCESS_TOKEN=
CONTENTFUL_PREVIEW_ACCESS_TOKEN=
CONTENTFUL_SPACE=
CONTENTFUL_ENVIRONMENT=master
NEXT_DRAFT_MODE_SECRET=
# Management API — migrations for content types compatible with SHOPin storefront accelerator teasers.
CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=
# Commercetools
# env variables provided by commercetools
COMMERCETOOLS_CLIENT_ID=
COMMERCETOOLS_CLIENT_SECRET=
COMMERCETOOLS_PROJECT_KEY=
COMMERCETOOLS_API_URL=
COMMERCETOOLS_AUTH_URL=
# (base64-encoded 32-byte key)
JWT_ENCRYPTION_KEY=
# (base64-encoded 32-byte key)
JWT_SIGNING_KEY=
# (base64-encoded 32-byte key)
CSRF_TOKEN_ENCRYPTION_KEY=
# (base64-encoded 32-byte key)
CSRF_TOKEN_SIGNING_KEY=
Variable reference
Grouped by scope. Each row: variable name (left) and attributes (right). On narrow screens the layout stacks to one column.
Required
NEXT_BFF_INTERNAL_URL- Read by — Next.js presentation (server-only BFF client).
- When used — Server-side calls to the BFF (RSC, Server Actions, Route Handlers). Use an internal/base URL (e.g. Docker:
http://<bff_service>:4000/bff).
NEXT_PUBLIC_BFF_EXTERNAL_URL- Read by — Next.js presentation (browser and code built with public env).
- When used — Client-side and any path that calls the BFF from the browser; also embedded at build time. Use the URL browsers can reach (e.g. public host or same-origin
/bffbehind a reverse proxy).
FRONTEND_URL- Read by — BFF.
- When used — CORS, redirects, and other checks that need the storefront origin (every BFF request that depends on frontend URL configuration).
COMMERCETOOLS_*- Read by — BFF (
commercetools-api,commercetools-auth, …). - When used — Any Commercetools HTTP call (catalog, cart, customer, order, auth). Default wiring uses them for
commercetools-setand for customer/order/auth when the catalog side usesmock-set. Set up Commercetools
JWT_ENCRYPTION_KEYJWT_SIGNING_KEYCSRF_TOKEN_ENCRYPTION_KEYCSRF_TOKEN_SIGNING_KEY- Read by — BFF.
- When used — Base64-encoded 32-byte keys. Issuing or validating auth cookies and CSRF protection on state-changing BFF routes (login, cart, checkout, etc.).
Conditional (Contentful and migrations)
CONTENTFUL_ACCESS_TOKENCONTENTFUL_PREVIEW_ACCESS_TOKENCONTENTFUL_SPACECONTENTFUL_ENVIRONMENT- Read by — BFF (
@integrations/contentful-api). - When used — At runtime when
ContentfulApiModuleis registered: GraphQL Delivery/Preview for pages and layout. Omit if that module is removed (mock content). Set up Contentful
NEXT_DRAFT_MODE_SECRET- Read by — Next.js presentation.
- When used — Draft/preview entry points (e.g. enabling draft mode for Contentful preview). Not used for normal published page rendering via the BFF alone.
CONTENTFUL_MANAGEMENT_ACCESS_TOKEN- Read by —
@integrations/contentful-migrationCLI only. - When used — Only when you run migration commands from the repo root (
npm run migrate -w @integrations/contentful-migration). Not read by the running BFF or storefront.
Optional
LOG_LEVELLOG_PRETTY_PRINT- Read by — BFF and presentation.
- When used — Whenever each app emits logs; tune verbosity and format for dev vs production. Logging
BFF_RATE_LIMIT_ENABLEDBFF_RATE_LIMIT_TTLBFF_RATE_LIMIT_LIMITBFF_RATE_LIMIT_SECURE_TTLBFF_RATE_LIMIT_SECURE_LIMIT- Read by — BFF.
- When used — Each incoming HTTP request to the BFF while rate limiting is enabled; set
BFF_RATE_LIMIT_ENABLEDtofalseto disable. Rate limiting
Scripts
| Command | Description |
|---|---|
npm run dev | Starts development servers (presentation, BFF, Storybook, Typedoc). Turborepo runs setup first. |
npm run setup | Runs setup tasks only (e.g. building core packages). |
npm run build | Production build for apps. |
npm run test | Run tests. |
npm run lint | Lint the codebase. |
npm run format | Format the codebase. |
npm run check-types | Type-check TypeScript. |
npm run check-dependencies | Runs npm audit --audit-level=high. |
npm run start:local | Runs production builds locally (run npm run build first). |
Migrations
Open the README for the migration package you need in the accelerator repository and follow the migration instructions there.
Contentful (@integrations/contentful-migration)
Migrates Contentful content types and optional demo content for pages, layout, and teaser models used by the SHOPin storefront accelerator.
Instructions: integrations/contentful-migration/README.md
In this section
- Integration setup — Commercetools, Mock, Contentful-related setup and data sources
- Migrations — Contentful and other workspace migration packages
- Remove demo functionality
- Deploy project apps
- Advanced topics — Project health, performance, and rules that protect vitals (cache, CDN, SEO, workspaces)