ajmalajjuca/storefront

Purpose and Runtime

This is a server-rendered, headless Shopify storefront built with Next.js App Router and React Server Components. It is intended for Vercel deployment, with Shopify Storefront API credentials and revalidation secret supplied through environment variables. The main application shell begins at app/layout.tsx; storefront entry routes include app/(browser)/page.tsx and product, collection, editorial, and policy routes under app/.

Routing, Rendering, and SEO

App Router pages render catalog and content views on the server, with client islands where interaction is required. Key route families are product detail at app/products/[handle]/page.tsx, collections/products indexes at app/indexes/collections/page.tsx and app/indexes/products/page.tsx, and editorial stories at app/story/[slug]/page.tsx. Search-engine discovery is generated by app/sitemap.ts and app/robots.ts; global failures are handled by app/error.tsx.

Commerce Provider Boundary

lib/shopify/ is the provider adapter boundary: it contains the Shopify client and domain-facing types in lib/shopify/index.ts and lib/shopify/types.ts, reusable GraphQL fragments in lib/shopify/fragments/, and operation definitions in lib/shopify/queries/ and lib/shopify/mutations/. Pages and components should consume this layer rather than issue Storefront API calls directly, enabling a provider replacement without broadly changing UI code.

Catalog and Content Flow

Route handlers/pages resolve a product handle, collection, page, policy, or metaobject; query modules retrieve it from Shopify; server components transform that data into catalog and editorial UI. Product-facing rendering is centered on app/products/[handle]/page.tsx with interactive variant/purchase behavior in app/products/[handle]/product-client.tsx. Shared product display primitives include components/product-card/index.tsx, components/product-rail/index.tsx, and components/collection-showcase/index.tsx.

Cart and Checkout State

The cart is a client-side context backed by Shopify cart mutations. components/cart/cart-context.tsx owns cart state and optimistic updates, while components/cart/actions.ts invokes server-side cart operations represented in lib/shopify/mutations/cart.ts. The drawer UI at components/cart/drawer.tsx consumes that state; Shopify remains authoritative for cart identity, lines, prices, and checkout progression.

Personalization and Browser-State Features

Client contexts manage preferences that should not alter Shopify source data: currency selection/exchange-rate display is implemented in components/currency/currency-preference-context.tsx, components/currency/exchange-rates-context.tsx, and components/currency/use-display-money.ts. Wishlist persistence and controls are isolated in components/wishlist/wishlist-context.tsx and app/wishlist/wishlist-client.tsx. The browser-specific shell is separated under app/(browser)/layout.tsx.

Invalidation, Domains, and External Interfaces

Shopify-triggered cache invalidation enters through app/api/revalidate/route.ts, protected by a revalidation secret, allowing catalog/content changes to refresh rendered routes. middleware.ts and lib/domain-redirects.ts define request-level domain routing/redirect behavior; snippets/shopify-theme-domain-redirect.liquid supports corresponding behavior from the Shopify theme. Newsletter and prebook submissions use server actions at components/newsletter/actions.ts and app/prebook/[handle]/notify-form.tsx, forming explicit server-side integration boundaries.