How bigcommerce/catalyst works
Main Components and Their Roles
• Frontend Storefront Application – This is the “core” Next.js app (located in core/app). It handles routing, pages (including dynamic routes for products, accounts, orders, blogs, etc.), API endpoints, and server-side rendering. Subdirectories such as “[locale]”, “api”, and “auth” indicate differentiated flows for authentication, localization, and commerce interactions.
• API and GraphQL Integration – Within the Next.js application, there are API routes (e.g., in core/app/api) that use the GraphQL client (from core/client) to interact with the BigCommerce GraphQL Storefront API. This component manages data fetching, mutations (for cart, authentication, account), and integration with external BigCommerce services.
• Reusable UI Components – Found in directories like core/components and core/vibes, these are tailored React components and primitives (buttons, modals, forms, product cards, etc.) ensuring the storefront is both consistent and customizable.
• Business Logic and Data Transformers – In directories such as core/data-transformers, the project implements business logic to massage data (e.g., for breadcrumbs, product options, search results) to be properly rendered by the UI.
• Middleware and Configuration – The “core/middlewares” and configuration files (e.g., core/next.config.ts, tailwind.config.js, .eslintrc.cjs) show architectural choices for routing, security (CSP headers), and code quality.
• Tooling, CLI, and Package Ecosystem – The monorepo includes a “packages” directory with subprojects like CLI (for project scaffold and build), client (supporting API interactions), and even tooling for linting and configuration (eslint-config-catalyst). These provide extension and automation capabilities across the project.
• Testing and Visual Regression – The “core/tests” directory outlines a comprehensive testing suite that covers both functional and visual regression for UI components and flows.
Relationships and Data Flows
• The Next.js frontend acts as the central component. It renders pages by combining reusable UI components with data sourced via API endpoints.
• The API routes (inside the app directory) use the GraphQL client from core/client to fetch data from the external BigCommerce GraphQL Storefront API.
• Middleware modules intercept and enrich requests (for authentication, localization, etc.), ensuring secure and tailored user experiences.
• The CLI and related packages in the “packages” directory interact with the core codebase for scaffolding, setup, and build processes.
• Data transformers act as intermediaries between raw API responses and the UI components, guaranteeing a consistent data model throughout the app.
Architectural Patterns and Principles
• Monorepo with Modular Architecture – The project is organized as a monorepo, separating concerns into a core application and various packages for CLI, client libraries, and ESLint configurations.
• Component-Driven and Headless Approach – The storefront is entirely built upon reusable UI components and leverages Next.js server/client components. The headless strategy decouples the presentation from the commerce API.
• Separation of Concerns – With dedicated folders for API, business logic (data transformers), UI, middleware, and testing, the project strictly separates concerns which simplifies scaling and maintenance.
• Extensibility and Customization – Through the CLI and various plugins (for telemetry, localization, etc.), the system design supports high customizability.