How bigcommerce-labs/catalyst-makeswift works
1. Overall shape
- This is a Next.js App Router storefront for BigCommerce Catalyst, not a generic web app.
- The app is organized around localized routes under app/[locale], with most business logic split between route-specific page-data.ts, route UI components, and shared storefront primitives.
2. Primary external systems
- The main backend dependency is BigCommerce GraphQL Storefront API.
- Additional integrations include NextAuth for authentication/session handling, Makeswift for CMS-style page editing/draft mode, and a KV store abstraction for ephemeral state or caching.
- The README and directory structure indicate this repo is meant to be connected to a specific BigCommerce store/channel via environment configuration.
3. Request routing and edge middleware
- The top-level middleware.ts is composed from middlewares/compose-middlewares.ts and specialized middlewares such as with-auth, with-makeswift, and with-routes.
- This is the first boundary in the system: requests are normalized for locale, auth, and editor/draft behavior before hitting page handlers.
- navigation.ts, i18n.ts, and messages/*.json support localized routing and translated UI strings.
4. Localized storefront pages
- The main customer-facing experience lives under app/[locale]/(default), which contains route groups for:
- catalog browsing (product, category, brand, search, faceted listing),
- commerce flows (cart, compare, login, account),
- content pages (blog, webpages, static pages),
- and utility pages like maintenance, error, and not-found.
- Many routes have companion page-data.ts files, which are the data-fetching boundary between the route and the API client layer.
5. Data access layer
- The client/ folder is the main API boundary to BigCommerce.
- It is split into:
- client/queries for read operations,
- client/mutations for write operations,
- client/fragments for reusable GraphQL selection sets,
- client/management for auxiliary store-management lookups like countries and zones.
- This layer centralizes all storefront API interaction so pages and components do not talk to BigCommerce directly.
6. Server actions and commerce mutations
- Many interactive flows use route-local _actions files, especially in cart, account, login, compare, and product/cart components.
- These actions typically orchestrate a mutation in client/mutations, then trigger revalidation or redirect behavior.
- This is the key write-path in the architecture: user interaction → server action → GraphQL mutation → refreshed storefront state.
7. Cart, checkout, and customer flows
- The cart subsystem is rich and self-contained, with components for line items, quantity updates, coupon handling, shipping estimation, shipping option selection, and checkout redirect.
- Customer identity flows are split between login/register/reset-password and authenticated account management.
- Account pages manage addresses and profile settings via dedicated actions and forms under app/[locale]/(default)/account/[tab].
8. Catalog and product presentation
- Product and category pages are built from specialized component bundles in their route directories, with shared faceting/search pieces under (faceted).
- Product pages use fragments and subcomponents for gallery, description, details, reviews, related products, and structured data/schema output.
- Category, brand, and search pages share a faceted navigation model, suggesting a common result-listing pipeline with filters, sorting, pagination, and mobile navigation.
9. Reusable storefront component system
- components/ contains shared UI and domain components used across routes.
- There is a clear separation between:
- low-level components/ui/* design-system primitives,
- higher-level storefront widgets like header, footer, breadcrumbs, hero, product card, quick search, compare drawer, and product sheet,
- and form systems like product-form.
- This makes the route pages thin composition layers rather than monolithic UI implementations.
10. Content, CMS, and draft-mode integration
- Makeswift support is first-class, with app/api/makeswift/*, makeswift/*, and middleware support.
- Content-heavy routes such as pages, blog posts, and “webpages” likely blend BigCommerce content data with Makeswift-rendered or draftable content.
- This is an important architectural boundary: dynamic storefront commerce flows coexist with CMS-driven marketing pages.
11. API routes
- app/api/auth/[...nextauth]/route.ts exposes auth endpoints.
- app/api/cart-quantity/route.ts likely supports cart badge/count updates.
- app/api/product/[id]/route.ts provides a product-level API surface, probably for product detail or quick lookup behavior.
- app/api/internal-auth.ts suggests internal request protection for select endpoints or integrations.
12. State, caching, and infrastructure utilities
- lib/kv provides a storage abstraction with memory and Vercel adapters, indicating the app can run both locally and in hosted/serverless environments.
- lib/cdn-image-loader.ts, lib/store-assets.ts, and lib/utils.ts hold shared infrastructure helpers for asset delivery and common transformations.
- client/revalidate-target.ts and client/tags.ts indicate revalidation/invalidation is part of the data freshness strategy.
13. Runtime characteristics
- The repo is TypeScript-first and uses modern Next.js conventions with server components, server actions, localized route segments, and route-level composition.
- It is designed for Node.js 20+ and deployed as a storefront, where render-time data fetching and cache invalidation matter more than traditional client-side state management.
Main entry points: (default) Storefront routes · components Shared UI · compose-middlewares.ts Compose · client BigCommerce client
Components 20
Routing & entry
Locale-aware request handling, middleware, and top-level app shell.
- Middleware · Composes locale, auth, Makeswift, and route handling before pages run.
middleware.ts - Compose · Builds the middleware chain used at the edge boundary.
middlewares/compose-middlewares.ts - Auth guard · Adds session/auth behavior to requests.
middlewares/with-auth.ts - Makeswift mw · Enables draft/editor behavior for CMS-driven pages.
middlewares/with-makeswift.ts - Route rules · Applies route normalization and rewrite logic.
middlewares/with-routes.ts - Locale app · Locale-scoped application root and nested default storefront segment.
app/[locale]/layout.tsx
Storefront UI
Customer-facing routes and shared storefront components.
- Storefront routes · Main localized customer experience under the default route group.
app/[locale]/(default) - Faceted catalog · Shared browsing pipeline for category, brand, and search result pages.
app/[locale]/(default)/(faceted) - Product page · Localized product detail experience with media, reviews, and schema output.
app/[locale]/(default)/product/[slug]/page.tsx - Cart flow · Cart view plus quantity, coupon, shipping, and checkout actions.
app/[locale]/(default)/cart/page.tsx - Account flow · Authenticated account pages for profile and address management.
app/[locale]/(default)/account/[tab]/page.tsx - Login flow · Login, register, reset password, and customer password actions.
app/[locale]/(default)/login/page.tsx - Content pages · Blog, webpages, static pages, and localized content routing.
app/[locale]/(default)/blog/page.tsx - Shared UI · Reusable storefront components and UI primitives used across routes.
components
Data layer
BigCommerce API access, server actions, caching, and revalidation.
- BigCommerce client · Central GraphQL API layer with queries, mutations, fragments, and management lookups.
client - Server actions · Route-local actions that call mutations and then refresh or redirect.
app/[locale]/(default) - Revalidation · Target and tag helpers used to invalidate storefront data after writes.
client/revalidate-target.ts
External integrations
Auth, CMS/draft mode, and runtime adapters.
- KV store · Memory and Vercel adapters for short-lived state and caching.
lib/kv - Makeswift · Client, provider, and runtime support for draft-mode editing and rendered content.
makeswift - NextAuth API · Authentication endpoints and session handling for customer flows.
app/api/auth/[...nextauth]/route.ts
Connections 27
- Middleware → Compose: uses · The top-level middleware is assembled from shared middleware composition.
- Compose → Auth guard: includes · Auth behavior is one step in the request pipeline.
- Compose → Makeswift mw: includes · Draft/editor handling is added to the request pipeline.
- Compose → Route rules: includes · Route normalization and rewrites are layered into the pipeline.
- Middleware → Locale app: protects · Requests are normalized before entering the locale-scoped app.
- Locale app → Storefront routes: contains · The locale root hosts the main storefront segment.
- Storefront routes → Faceted catalog: shares · Category, brand, and search routes reuse the faceted browsing subsystem.
- Storefront routes → Product page: contains · Product detail routes live in the default storefront segment.
- Storefront routes → Cart flow: contains · Cart and checkout-related screens live in the storefront segment.
- Storefront routes → Account flow: contains · Customer account pages are part of the default storefront segment.
- Storefront routes → Login flow: contains · Customer identity routes are part of the storefront flow.
- Storefront routes → Content pages: contains · Blog, webpages, and static content routes live alongside commerce routes.
- Faceted catalog → BigCommerce client: queries · Catalog list pages fetch product and route data through the API layer.
- Product page → BigCommerce client: queries · Product detail pages read product data and fragments from BigCommerce.
- Cart flow → Server actions: writes via · Cart interactions are mediated by server actions.
- Account flow → Server actions: writes via · Profile and address updates are executed through route-local actions.
- Login flow → Server actions: writes via · Login, registration, and password flows are handled by server actions.
- Server actions → BigCommerce client: mutates · Actions orchestrate GraphQL mutations against the storefront API.
- Server actions → Revalidation: invalidates · Successful writes refresh cached storefront data.
- BigCommerce client → KV store: uses · Supporting infrastructure can persist ephemeral state through KV adapters.
- Content pages → Makeswift: renders with · Marketing and content pages can be powered by Makeswift runtime and draft mode.
- Middleware → Makeswift: enables · Middleware activates Makeswift draft/editor behavior.
- NextAuth API → Auth guard: supports · NextAuth endpoints back the auth middleware and customer sessions.
- Shared UI → Product page: used by · Shared product, sheet, gallery, and schema components assemble product pages.
- Shared UI → Cart flow: used by · Header, cart, and form primitives support cart interactions.
- Shared UI → Faceted catalog: used by · Facets, search, and listing UI build catalog browsing.
- Shared UI → Content pages: used by · Global UI primitives and content widgets support blog and webpage rendering.