How mercurjs/b2c-marketplace-storefront works
Project type and purpose
• This is a Next.js-based B2C storefront (“b2c-marketplace-storefront”) built on the Mercur open-source marketplace platform.
• It serves as the presentation layer: browsing, filtering, and buying products; handling cart, checkout, wishlist, seller pages, user account pages, and chat.
• It connects to a headless MedusaJS backend for commerce data and integrates external services (Algolia, Stripe, TalkJS).
File structure
• Top-level configuration and build files:
– next.config.ts, tsconfig.json, tailwind.config.ts, .env.template
– Storybook config under .storybook/
• src/app/… — App router pages grouped by locale and feature (checkout, main, reset-password). SSR/SSG routes.
• src/components/… — Atomic Design structure: atoms, cells, molecules, organisms, sections.
• src/lib/… — Data layer: client.tsx (fetch wrapper), config/constants, data adapters for each resource.
• src/hooks/… — UI logic utilities (pagination, filters, screen size).
• src/public/… — Static assets (images, algolia import screenshot).
• Middleware and types support authentication, i18n, error handling.
README insights
• Purpose: fully customizable B2C storefront demo for Mercur.
• External dependencies:
– MEDUSA_BACKEND_URL (headless commerce API)
– Algolia (search and filtering)
– Stripe (payments)
– TalkJS (chat)
• Deployment: run via npm run dev or deploy on Vercel.
a. Main components
1) Client (Browser/Mobile)
2) CDN / Static asset host (images, JS bundles)
3) Next.js Server (App Router, SSR/SSG, API routes, middleware)
4) Data-fetch layer (src/lib/client.tsx)
5) UI component library (atoms → sections)
6) External Services:
• MedusaJS Backend (Commerce API & Database)
• Algolia Search Index
• Stripe Payment Gateway
• TalkJS Chat Service
b. Relationships & interactions
• Client ↔ Next.js Server: HTTP(S) for page render (SSR) and client navigation (RSC/Client-side).
• Next.js ↔ Medusa API: REST calls (cart, products, orders, users).
• Next.js ↔ Algolia: search and facets queries.
• Next.js ↔ Stripe: payment intent creation or verification via API routes or direct SDK.
• Next.js ↔ TalkJS: chat session initialization in user pages.
• Static assets served from CDN or Next.js static folder.
c. Architectural patterns & design principles
• Hybrid rendering: SSR for SEO and initial load; SSG/ISR for public listing pages; client-side hydration for interactivity.
• Atomic Design for UI composition (atoms → sections).
• Separation of concerns:
– “app/” directory handles routing and layouts.
– “lib/” directory abstracts API communication.
– “hooks/” directory handles reusable UI logic.
• Environment-driven configuration (via .env.local).
d. Key technologies & frameworks
• Next.js (App Router, server and client components)
• React + TypeScript
• Tailwind CSS
• Storybook for component development
• MedusaJS (headless commerce)
• Algolia (search & filtering)
• Stripe (payment processing)
• TalkJS (real-time chat)
Detail without over-fragmenting
• Every external dependency and major internal layer.
• Avoid drawing each individual UI component; instead group them as “UI Component Library (atoms → sections)”.