How bigcommerce/nextjs-commerce works
1. High-level shape
This is a Next.js App Router storefront for BigCommerce. The app is mostly a server-rendered commerce frontend, with BigCommerce as the system of record for catalog, pages, search, and cart state.
2. Route surface / user-facing entry points
The main routes are:
- app/page.tsx for the home page
- app/product/[handle]/page.tsx for product detail pages
- app/search/page.tsx and app/search/[collection]/page.tsx for browsing/searching collections
- app/[page]/page.tsx for generic content pages
- app/api/revalidate/route.ts for cache invalidation / revalidation
There are also Next.js metadata routes for robots.ts, sitemap.ts, and Open Graph image generation.
3. Rendering model
The app uses React Server Components heavily via the App Router, with route-level layout.tsx, loading.tsx, and error.tsx boundaries. Shared chrome such as navigation and footer is composed in app/layout.tsx and segment layouts like app/search/layout.tsx.
4. BigCommerce integration boundary
All BigCommerce access is centralized under lib/bigcommerce. That layer contains:
- GraphQL queries for cart, category, checkout, menu, page, product, and route resolution
- mutations for cart updates
- reusable fragments
- mappers and types to convert BigCommerce GraphQL shapes into app-friendly models
- storefront configuration/constants
This is the main boundary between the UI and the external commerce platform.
5. Catalog and content data flow
Product, category/collection, menu, and CMS page data are fetched through the lib/bigcommerce query layer and fed into route components under app/. The app/[page] route suggests generic page resolution, while app/product/[handle] and search routes map BigCommerce handles/collections to storefront pages.
6. Search and browsing subsystem
The search experience is split between route-level data fetching and UI filtering components:
- app/search/... handles collection/search pages
- components/layout/search/* contains filter, dropdown, and collections UI
- components/layout/product-grid-items.tsx and components/grid/* render product listings
This is a distinct browsing subsystem centered on collection faceting and list rendering.
7. Cart subsystem
Cart logic is separated into:
- components/cart/* for the drawer/modal and controls
- components/cart/actions.ts for cart mutations/actions
- BigCommerce cart queries/mutations in lib/bigcommerce
The cart is a client-interactive feature, but the authoritative state comes from BigCommerce via server-side API calls.
8. Shared layout and navigation
components/layout/* provides the storefront chrome:
- navbar, mobile menu, and search entry points
- footer and footer menu
- shared search controls and product grid layout helpers
These components are reused across route segments to keep the storefront shell consistent.
9. Presentation primitives
The repo includes a set of reusable UI primitives in components/ such as carousel, price, label, loading-dots, prose, icons, and product-specific elements like gallery and variant selector. Styling is handled with Tailwind CSS plus global styles in app/globals.css, with fonts managed in fonts/.
10. SEO and social metadata
The storefront is set up for indexability and share previews through:
- app/robots.ts
- app/sitemap.ts
- route-specific and shared opengraph-image.tsx files
- page/layout metadata in the App Router
This matters because the app is intended to be crawlable commerce content, not just an interactive SPA.
11. Runtime and request-boundary concerns
middleware.ts sits at the framework boundary for request-time handling, and app/api/revalidate/route.ts provides a controlled way to invalidate rendered content when upstream BigCommerce data changes. That suggests the storefront uses Next.js caching/revalidation rather than a separate backend.
12. Tooling and deployment posture
The repo is TypeScript-based and uses standard frontend tooling: ESLint, Prettier, Tailwind, PostCSS, and PNPM. The presence of .env.example, .nvmrc, and GitHub Actions indicates a Vercel-friendly deployment model with environment-driven BigCommerce credentials and CI test automation.
13. Architectural summary
The clearest diagram is: browser → Next.js route/layout tree → BigCommerce GraphQL integration layer → BigCommerce storefront API. Everything else in the repo is either presentation around that flow, or supporting infrastructure for search, cart, SEO, and cache invalidation.
Main entry points: product.ts Storefront queries · layout.tsx Root shell · index.tsx Browse UI · price.tsx Primitives
Components 22
App Router
Next.js routes, layouts, metadata, and API boundaries.
- Root shell · Global App Router shell with shared providers and chrome.
app/layout.tsx - Home page · Storefront landing page.
app/page.tsx - Product page · Product detail route by handle.
app/product/[handle]/page.tsx - Search page · Entry point for browsing and search.
app/search/page.tsx - Collection page · Collection-specific search and browse route.
app/search/[collection]/page.tsx - Content page · Generic CMS/page resolution route.
app/[page]/page.tsx - Revalidate API · Cache invalidation endpoint for upstream content changes.
app/api/revalidate/route.ts - SEO routes · Robots, sitemap, and Open Graph image generation.
app/robots.ts - Search shell · Search segment layout and loading boundary.
app/search/layout.tsx
UI Components
Reusable storefront chrome, product, cart, and browsing UI.
- Browse UI · Filter, dropdown, and collection browsing controls.
components/layout/search/filter/index.tsx - Product grid · Shared product list rendering for search and category views.
components/layout/product-grid-items.tsx - Site chrome · Navbar, mobile menu, footer, and footer menu.
components/layout/navbar/index.tsx - Cart drawer · Interactive cart modal and item controls.
components/cart/index.tsx - Cart actions · Add, edit, delete, open, and close cart interactions.
components/cart/actions.ts - Product UI · Gallery, description, and variant selection widgets.
components/product/gallery.tsx - Primitives · Reusable display pieces such as price, labels, prose, icons, and carousel.
components/price.tsx
BigCommerce Layer
Queries, mutations, fragments, and mapping around the storefront API.
- Storefront queries · BigCommerce GraphQL access for product, category, menu, page, checkout, and route resolution.
lib/bigcommerce/queries/product.ts - Cart mutations · BigCommerce cart update operations.
lib/bigcommerce/mutations/cart.ts - Data models · Fragments, types, and mapping from BigCommerce shapes to app models.
lib/bigcommerce/mappers.ts - Storefront config · Constants and storefront configuration for the BigCommerce integration.
lib/bigcommerce/constants.ts
Infra
Runtime, styling, and build/config support.
- Middleware · Framework-level request interception and routing concerns.
middleware.ts - Styling · Global CSS and Tailwind-based presentation layer.
app/globals.css
Connections 23
- Root shell → Site chrome: composes · Root shell composes shared site chrome.
- Root shell → Cart drawer: mounts · Cart drawer is available from the global shell.
- Root shell → Styling: applies · Global styles support the App Router shell.
- Home page → Storefront queries: loads · Home page fetches catalog and storefront data.
- Product page → Storefront queries: loads · Product route resolves product data from BigCommerce.
- Product page → Product UI: renders · Product page uses gallery and variant controls.
- Search page → Browse UI: renders · Search entry page uses browse and filter controls.
- Collection page → Browse UI: renders · Collection route uses faceting and dropdown filters.
- Collection page → Product grid: renders · Collection results are shown in product grids.
- Search shell → Browse UI: wraps · Search segment layout organizes the browsing experience.
- Content page → Storefront queries: loads · Generic pages are resolved through BigCommerce content queries.
- SEO routes → Storefront queries: depends on · SEO metadata and routes derive from storefront content.
- Revalidate API → Storefront config: uses · Revalidation endpoint follows storefront configuration.
- Cart drawer → Cart actions: invokes · Cart controls trigger client actions and mutations.
- Cart actions → Cart mutations: writes · Cart updates are persisted through BigCommerce mutations.
- Storefront queries → Data models: maps to · Query results are normalized into app-friendly models.
- Cart mutations → Data models: shares models · Mutations reuse the same cart/product data shapes.
- Storefront queries → Storefront config: configured by · Queries rely on storefront constants and API setup.
- Middleware → Root shell: guards · Request-time handling sits in front of the app routes.
- Product UI → Primitives: uses · Product widgets are built from shared presentation primitives.
- Browse UI → Primitives: uses · Search controls share common UI pieces and icons.
- Product grid → Primitives: uses · Listing tiles reuse core visual primitives.
- Site chrome → Primitives: uses · Navbar and footer use shared branding and icon primitives.