Template Structure

Understand how the ecommerce boilerplate under `web-builder/apps/templates/ecommerce-boilerplate` is organized so you can update UIs without touching core plumbing.

Architecture at a glance

  • Location: Clone the template into web-builder/apps/templates/ecommerce-boilerplate.
  • App Router-first: Routes live in app/ with a shared layout in app/layout.tsx that wraps pages with ApolloWrapper and ClientLayout.
  • Composable sections: Page JSON defines pageItems; React components in app/_components/sections/ render each section type.
  • Data-aware: GraphQL operations in graphql/ and helper hooks in lib/ fetch CMS/client-portal data; static JSON in data/ backs local mocks.
  • Shared UI: Shadcn UI primitives live in components/ui; reusable widgets (loaders, alerts, forms) live in components/common.
  • UI-only scope: Do not add/remove sections or change core wiring. Limit changes to UI (markup/styles/states) inside existing files.

Top-level folders

  • app/: All routes and page shells. Notable entries:
    • _components/: Layout chrome (Header, Footer, ClientLayout) and all section components under _components/sections/.
    • page.tsx: Home page that maps pageItems to section components via renderSections.
    • Route folders like about/, contact/, products/, profile/ that render CMS-backed pages with usePage.
  • components/: Reusable UI.
    • ui/: Shadcn primitives (buttons, inputs, dialog, sheet, etc.).
    • common/: Shared widgets (loaders, dynamic forms, empty states, template alerts).
  • data/: Local config and mock content.
    • configs.json: Template metadata (title, description), appearance tokens, menus, integrations.
    • pages/*.json: Page-level content (index.json, about.json, contact.json, etc.) used in build/local modes.
  • graphql/: Domain-specific operations grouped by feature (auth/, clientportal/, cms/, ecommerce/, order/, payment/, products/) plus aggregate queries.ts/mutations.ts.
  • lib/: Cross-cutting utilities.
    • apollo-wrapper.tsx and client.ts: Apollo Client setup.
    • Contexts (AuthContext, CartContext) and hooks (useClientPortal, usePage, fetchCms, fetchCpConfig, fetchTours).
    • renderSections.tsx: Helper to render a section list from a component map.
  • types/: Shared TypeScript contracts (types/sections.ts defines the base Section shape).
  • public/: Static assets (images, icons, favicons).

Page composition flow

  • Home (app/page.tsx): Imports pageData from data/pages/index.json, builds a SectionComponentMap, and calls renderSections to output the page. When BUILD_MODE=true, it swaps to app/page.client.tsx to let the builder inject live data via query params.
  • Other routes: Pages like about/page.tsx and contact/page.tsx call usePage(pageName) to fetch CMS content with GET_CMS_PAGE, passing the client-portal-id header from route params. Sections are rendered by switching on section.type.
  • Layout: app/layout.tsx wraps everything in ApolloWrapper and ClientLayout, ensuring GraphQL and layout chrome are available to every page.

Sections

  • Location: app/_components/sections/. Each file exports a React component that accepts { section: Section }.
  • Registry (read-only): app/page.tsx maps section.type to components for build/local; lib/usePage.tsx does the same for CMS. Do not add or remove mappings—only adjust UI inside existing section files.
  • Behavior: Sections are responsible for their own data needs (e.g., product listings, CMS posts) and should support sensible defaults so mocked JSON can render without live APIs.

Config and data sources

  • Template config: data/configs.json stores meta tags, theme tokens, menus, and integration placeholders. Keep IDs and secrets out of this file; use environment variables instead.
  • Page mocks: data/pages/*.json supply title, description, and pageItems for local development and build previews. Use these to validate layout and theming without hitting the CMS.
  • Environment flags: BUILD_MODE=true toggles builder-driven rendering; absence falls back to local JSON-driven rendering for the home page.

Shared UI and utilities

  • UI primitives live in components/ui (generated via components.json shadcn config).
  • Cross-template widgets live in components/common (loaders, dynamic forms, empty states).
  • Utility helpers like lib/utils.ts handle class merging and small helpers reused across sections.

GraphQL layer

  • Operations are organized by domain inside graphql/, with aggregated exports in graphql/queries.ts and graphql/mutations.ts.
  • lib/apollo-wrapper.tsx provides the provider setup; lib/client.ts configures the Apollo client instance.
  • Hooks and fetchers in lib/ (e.g., usePage, fetchCms, fetchCpConfig) standardize how sections and pages request CMS/client-portal data, keeping rendering logic composable and data-aware.