How vercel/commerce works
1. Overall architecture
- This is a Next.js App Router ecommerce storefront, built around server-rendered React Server Components with selective client-side islands for interactivity.
- The repo is structured as a thin presentation layer on top of a Shopify-specific data adapter in lib/shopify.
2. Routing surface
- The app/ directory defines the public site routes: home (app/page.tsx), generic CMS pages (app/[page]), product detail pages (app/product/[handle]), and search/browse pages (app/search/...).
- app/layout.tsx and nested layout files provide the shared shell, navigation, footer, search UI, and per-section wrappers.
3. Shopify integration boundary
- lib/shopify/ is the main backend boundary for the whole app.
- It contains GraphQL fragments, queries, and mutations for Shopify resources such as products, collections, menus, pages, carts, images, and SEO data.
- The rest of the app is intentionally provider-agnostic in shape; swapping commerce providers would mostly mean replacing this folder.
4. Data flow for storefront pages
- Page routes fetch data on the server through lib/shopify and compose it into UI components under components/.
- Product and collection browsing is driven by Shopify catalog data, while page content and menus come from CMS-like Shopify resources.
- SEO metadata and social images are derived from the same fetched records where possible.
5. Product detail subsystem
- app/product/[handle]/page.tsx renders individual product pages.
- Supporting components in components/product/ handle the product gallery, description, and variant selection.
- This is where product-specific state such as selected variant and displayed images is localized.
6. Search and collection browsing
- app/search/page.tsx and app/search/[collection]/page.tsx support catalog discovery.
- The search area has its own layout and loading state, plus helper components for collections and filtering under components/layout/search/.
- This portion of the app is the main browse/filter entry point rather than a separate search backend.
7. Cart subsystem
- Cart behavior is isolated in components/cart/ and backed by Shopify cart queries/mutations in lib/shopify.
- The cart uses client-side state/context for UI updates, while the actual create/update/delete operations are handled through server-backed actions and mutations.
- UI pieces include add-to-cart controls, quantity editing, deletion, an open-cart trigger, and a cart modal.
8. Mutation and refresh path
- app/api/revalidate/route.ts is the explicit server endpoint for cache invalidation.
- This is intended for Shopify-triggered updates, so the storefront can revalidate content after catalog or content changes rather than waiting for TTL expiry.
- That makes the app behave like a cached SSR storefront with webhook-driven freshness.
9. SEO, metadata, and sharing
- The app includes route-level metadata support via opengraph-image.tsx, robots.ts, and sitemap.ts.
- Dynamic OG images exist for the root, generic pages, products, and search collections, so shared links have route-specific previews.
- SEO fields are also part of the Shopify query layer, not just hardcoded metadata.
10. Shared UI and layout system
- components/layout/ contains the site chrome: navbar, mobile menu, search entry, footer, and product grid scaffolding.
- components/grid/, components/carousel.tsx, components/price.tsx, components/prose.tsx, and similar files are reusable presentation primitives.
- These components are mostly stateless and used to assemble the page-specific routes.
11. Cross-cutting client components
- A few components are explicitly client-side for interactivity, such as welcome toast, cart controls, dropdown filters, and modal UI.
- Most other rendering remains server-side, which keeps page composition fast and minimizes client bundle size.
12. Runtime, config, and deployment assumptions
- The project is designed for Vercel deployment and depends on environment variables for Shopify domain, storefront token, revalidation secret, company name, and site name.
- next.config.ts, postcss.config.mjs, tsconfig.json, and the font/CSS setup define the framework and styling boundaries, but they do not introduce additional backend services.
Main entry points: index.ts Shopify entry · layout.tsx Root layout · collections.tsx Search UI · product.ts Queries
Components 21
App routes
Next.js App Router pages, layouts, metadata, and API endpoints.
- Root layout · Global shell, providers, fonts, and shared chrome.
app/layout.tsx - Home page · Storefront landing page.
app/page.tsx - CMS page · Generic content page route for Shopify-backed pages.
app/[page]/page.tsx - Product page · Individual product detail route.
app/product/[handle]/page.tsx - Search page · Catalog discovery and browse entry point.
app/search/page.tsx - Collection page · Search/browse route scoped to a collection.
app/search/[collection]/page.tsx - Search layout · Shared search section shell and wrappers.
app/search/layout.tsx - Revalidate API · Webhook-friendly cache invalidation endpoint.
app/api/revalidate/route.ts - SEO assets · Robots, sitemap, and route-specific Open Graph images.
UI system
Shared presentation components and client-side islands.
- Navbar · Primary navigation, search entry, and mobile menu.
components/layout/navbar/index.tsx - Footer · Footer menus and site footer.
components/layout/footer.tsx - Search UI · Collection list and filter controls for search/browse.
components/layout/search/collections.tsx - Product UI · Gallery, description, and variant selection.
components/product/gallery.tsx - Cart UI · Cart context, modal, and item actions.
components/cart/cart-context.tsx - Grid tiles · Reusable product and content grid presentation.
components/grid/index.tsx - Primitives · Shared rendering helpers like price, prose, carousel, and labels.
components/price.tsx
Shopify adapter
Queries, mutations, fragments, and typed boundary for commerce data.
- Shopify entry · Central Shopify API surface used by routes.
lib/shopify/index.ts - Queries · Catalog, page, menu, and cart read operations.
lib/shopify/queries/product.ts - Mutations · Cart and write operations against Shopify.
lib/shopify/mutations/cart.ts - Fragments · Shared GraphQL fragments for cart, product, image, and SEO data.
lib/shopify/fragments/product.ts
Shared libs
Non-Shopify utilities and constants used across the app.
- Shared utils · Constants, utility functions, and type guards.
lib/constants.ts
Connections 26
- Root layout → Navbar: renders · Root shell composes global navigation.
- Root layout → Footer: renders · Root shell composes site footer.
- Root layout → Primitives: uses · Shared presentation helpers appear across the shell.
- Home page → Shopify entry: fetches · Home page loads storefront data server-side.
- Home page → Grid tiles: renders · Home page composes product/content tiles.
- CMS page → Shopify entry: fetches · Generic page route reads CMS-like Shopify content.
- CMS page → Primitives: renders · Content pages use prose and media primitives.
- Product page → Shopify entry: fetches · Product detail page loads product and SEO data.
- Product page → Product UI: renders · Product detail page composes gallery and variant UI.
- Search layout → Search UI: wraps · Search section layout provides browse/filter chrome.
- Search page → Shopify entry: fetches · Search page reads catalog and collection data.
- Search page → Search UI: renders · Search page renders browse and filter controls.
- Collection page → Shopify entry: fetches · Collection-scoped search page loads collection data.
- Revalidate API → Shopify entry: invalidates · Webhook-triggered refresh aligns storefront cache with Shopify updates.
- SEO assets → Shopify entry: derives from · Robots, sitemap, and OG images are driven by store data.
- Navbar → Search UI: links to · Navigation includes search entry and related browse UI.
- Cart UI → Mutations: writes · Cart UI triggers create/update/delete cart mutations.
- Cart UI → Queries: reads · Cart state is hydrated from Shopify cart reads.
- Product UI → Fragments: shapes with · Product UI depends on catalog fields and image fragments.
- Search UI → Queries: filters · Browse controls operate on catalog query results.
- Shopify entry → Queries: re-exports · Central adapter exposes read operations to routes.
- Shopify entry → Mutations: re-exports · Central adapter exposes write operations to routes.
- Shopify entry → Fragments: re-exports · Central adapter shares common GraphQL fragments.
- Queries → Fragments: uses · Queries compose shared fragments for consistency.
- Mutations → Fragments: uses · Mutations reuse fragments for cart payloads.
- Root layout → Shared utils: uses · Global shell relies on shared constants and utilities.