Storefront
Overview
Section titled “Overview”The storefront is a Next.js 15 application using the App Router with React 19 RC. It supports multi-country routing, multi-language content, per-brand theming, and custom features like the Magic Logo Configurator.
Dev port: 10010 (Turbopack) Production port: 9002 (standalone)
Pages & Routes
Section titled “Pages & Routes”All routes are prefixed with [countryCode] (nl, de, fr, en):
Main Pages
Section titled “Main Pages”| Route | Purpose |
|---|---|
/ | Homepage (hero, featured products) |
/store | Product listing with filters |
/products/[handle] | Product detail page |
/categories/[...category] | Category browsing |
/collections/[handle] | Product collections |
/cart | Shopping cart |
/checkout | Multi-step checkout |
/account | Customer dashboard |
/account/@dashboard/orders | Order history |
/quote | B2B quote request |
/toegang | Access request (gatekeeper) |
/contact | Contact form |
/about | About page |
/service | Service page |
/faq | FAQ page |
/privacy | Privacy policy |
/retourbeleid | Return policy (Dutch) |
/terms | Terms and conditions |
/partners/* | Partner pages (Spranz, Langenberg, MOXZ, Lanyards) |
Order Pages
Section titled “Order Pages”| Route | Purpose |
|---|---|
/order/[id]/confirmed | Order confirmation |
/order/[id]/transfer/[token]/accept | Accept order transfer |
/order/[id]/transfer/[token]/decline | Decline order transfer |
Account (Parallel Routes)
Section titled “Account (Parallel Routes)”@login— Login/register form@dashboard— Account overview, orders, addresses, profile
Feature Modules
Section titled “Feature Modules”Magic Logo Configurator
Section titled “Magic Logo Configurator”The signature custom feature — lets customers upload logos and configure print techniques:
- User clicks “Order with logo” on a product
- System fetches available techniques from API
- Multi-step wizard: Quantity → Technique → Colors → Logo Upload
- Integration with Spranz Designer (designer.spranz.de) via modal
- Config saved with cart item
Supports SKU formats:
- Spranz:
376-00,376-00.005 - XD Connect:
100804-001,P706.042
Access Control (Gatekeeper)
Section titled “Access Control (Gatekeeper)”IP-based access control for B2B-only storefronts:
- Enable:
NEXT_PUBLIC_GATEKEEPER_ENABLED=true - Public paths always accessible:
/toegang,/privacy,/terms,/contact - States: loading, approved, pending, rejected, none, disabled
- Backend:
/store/access-checkand/store/access-request
Multi-Language (i18n)
Section titled “Multi-Language (i18n)”- Languages: Dutch (nl), German (de), French (fr), English (en)
- Default: Dutch
- UI labels: JSON translation files with 3-layer resolution (tenant override → storefront base → shared package)
- Product content: Medusa
metadata.translationspopulated during medusa-sync from APLT multi-language columns - Context-based with
useLanguage()hook +useProductTranslation()hook - LocalStorage persistence (
magiverse_language)
See Multi-Language (i18n) for full documentation.
React Contexts
Section titled “React Contexts”| Context | Purpose |
|---|---|
BrandProvider | Domain-based brand detection, CSS injection, logo/favicon |
LanguageProvider | Language selection, translation function, persistence |
LogoProvider | Magic Logo upload, browser fingerprinting, cached logos |
ModalProvider | Modal dialog state |
GatekeeperProvider | Access control status |
Data Fetching
Section titled “Data Fetching”Server-side data modules (src/lib/data/):
| Module | Functions |
|---|---|
products.ts | listProducts(), getProductByHandle(), getProductsById() |
cart.ts | retrieveCart(), addToCart(), updateLineItem() |
customer.ts | login(), register(), retrieveCustomer() |
orders.ts | retrieveOrder(), listCustomerOrders() |
pim.ts | getProductPriceTiers(), getFullPIMProduct() |
cms.ts | CMS content per brand |
categories.ts | Category hierarchy |
regions.ts | Region/country data |
Caching Strategy
Section titled “Caching Strategy”- Products:
revalidate: 3600(1 hour) - Categories:
revalidate: 86400(24 hours) - Customer/cart:
no-store(always fresh) - ISR revalidation via
/api/revalidateendpoint
Storefront API Routes
Section titled “Storefront API Routes”| Route | Purpose |
|---|---|
/api/pim/products/[sku] | Fetch PIM price tiers (direct PostgreSQL) |
/api/search/suggestions | Search autocomplete |
/api/revalidate | ISR cache revalidation |
/api/images/[...path] | Image proxy to backend |
/api/aplt/categories | APLT categories |
Next.js Configuration
Section titled “Next.js Configuration”Key features from next.config.js:
output: 'standalone'for Docker deployment- URL rewrites proxying APLT endpoints to backend
- Image optimization with 10+ remote domains
- React Strict Mode disabled