How storefront-foundation/react-storefront works
Project Type and Purpose
• React Storefront is an open-source framework built on Next.js for creating high-performance, server-rendered, headless eCommerce PWAs with built-in support for AMP, predictive prefetching, caching, and code splitting.
High-Level Architectural Layers
Break the system into these logical layers:
a. Client Runtime (Browser/PWA)
• React hydration layer (Next.js client entry points)
• Service Worker (src/serviceWorker.js + src/sw/configureServiceWorker.js) for offline support, caching strategies, and background sync
• AMP renderer (Auto-AMP creation)
b. Presentation/UI Component Library
• src/*.js top-level components (Accordion, Breadcrumbs, etc.)
• Feature modules: /carousel, /menu, /plp (Product Listing), /search, /nav, /option, /session, etc.
• Storybook stories (/.storybook) that illustrate each component in isolation
c. Data & Business Logic
• src/api — adapters to fetch from real eCommerce backends (getAPIURL, addVersion)
• src/mock-connector — local mock data server for development/testing
• src/props — helper methods for Next.js data fetching (fetchServerSideProps, fulfillAPIRequest)
• src/hooks and src/utils — reusable React hooks and utilities (useLocalStorage, useIntersectionObserver, withCaching, mod, merge, etc.)
d. Server-Side Framework Extensions
• src/server — Next.js route listing and dynamic route generation (getRoutes, listRoutes)
• Plugins (/src/plugins) — e.g., withReactStorefront.js, withServiceWorker.js to extend Next.js’s Webpack and runtime
• Middleware (withAmpFormParser)
e. Build, Testing & Documentation
• Jest test suites under /test covering components, hooks, api, server, sw, etc.
• Storybook config in /.storybook
• Documentation scripts (docs/buildDocs.js, docs/moduleParser.js)
• CI/CD workflows (/.github/workflows/*.yml) for testing, publishing, release drafting
Component Interactions and Data Flow
• At build time, Next.js + React Storefront plugins generate pages, AMP variants, and skeleton loading states.
• On the first request, the Node.js server (Next.js SSR enhanced by src/server) fetches data via src/props → src/api connectors (or mock-connector in dev) and applies caching rules.
• The server renders HTML + JSON state, sends to the browser.
• The client bootstraps React, hydrates UI components, and uses service worker to cache assets and API responses for offline and fast navigations.
• Predictive prefetcher (built into core) observes user interactions (via NavigationEvent hooks) and preloads data/components.
• Data flows: Browser ⇄ Service Worker ⇄ Server SSR ⇄ External eCommerce APIs
Architectural Patterns & Principles
• Isomorphic/Universal JavaScript: same code runs on server and client
• Headless architecture: decoupled frontend consuming any backend via REST/GraphQL APIs
• Plugin-based extensibility: Next.js customization is encapsulated in /src/plugins
• Modular UI library: feature folders each expose composable React components
• Caching & PWA: service worker strategies, data hydration, client-side caching utilities