# builderio/nextjs-shopify architecture

> Architecture diagram of the GitHub repository builderio/nextjs-shopify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/builderio/nextjs-shopify
- Repository: https://github.com/builderio/nextjs-shopify

## Overview

##### Main Components
- Next.js Application: Represent the core web app that handles page rendering, routing, and server-side logic.
- Builder.io Integration:
- Blocks & CMS Components: Display the “blocks” folder (CloudinaryImage, CollectionView, ProductGrid, ProductView, etc.) as Builder-driven, dynamic components. Indicate how Builder.io content (created via the builder cli commands) is fetched and injected into these components.
- Builder Content Sync: Highlight the process of initializing and updating Builder.io spaces (as described in the README) which is responsible for serving visual content.
- Shopify Connection:
- API Integration Module: Emphasize the “lib/shopify/storefront-data-hooks” folder along with the “config/shopify.ts” file that provide abstraction over Shopify’s Storefront API to pull live product, collection, and cart data.
- Custom App & Environment Configuration: Show that configuration for Shopify is handled through environment (.env) files and configuration files to ensure secure connectivity.
- UI Components:
- Presentation Components: Include the “components” directory that houses reusable UI pieces (cart items, common elements like Navbar, ProductCard, Searchbar, etc.) – this is the view-layer that renders both static and dynamic content.
- Utility and Helper Libraries:
- Utility libraries and hooks (inside the “lib” folder), such as click-outside management and layout/generic helper functions.
- External Services and Deployment:
- Third-Party Services: Note external dependencies like Shopify’s API, Builder.io’s API endpoints, and optional deployment providers (Vercel, Netlify) which are referenced in the README.
- State Management & Hooks: Include the abstraction layers (hooks in lib/hooks) that manage local state like cart updates and media queries.

##### Relationships and Interactions
- Data Flow from External Services: Illustrate how the Next.js pages (found in the “pages” directory) make API calls (using storefront-data-hooks) to Shopify in order to pull product and collection data.

##### Architectural Patterns & Design Principles
- Modular Architecture: The separation into folders (pages, components, blocks, config, lib) shows a clear modular design, where each module has a specific purpose.
- Separation of Concerns: UI, business logic, and integration layers are separated. For example, Shopify API calls are isolated in lib, while UI rendering is contained within components and Next.js pages.
- Headless CMS Approach: The dynamic block structure connects to Builder.io, emphasizing a headless CMS strategy where content is managed externally and injected into the application.
- Built-in Hooks & Contexts: Use of React hooks and contexts (in “components/common/context.tsx” and “lib/hooks”) to manage local states (for example, cart state) and reactivity.

##### Relevant Technologies and Frameworks
- Next.js as the React framework for SSR & static rendering.
- Shopify’s Storefront API for e-commerce backend.
- Builder.io for visual CMS, page building, and dynamic content management.
- Various utility libraries and custom hooks for UI interaction (e.g., click-outside handling).
- Environment setup using dotenv files (.env.development, .env.production) to securely pass API keys and tokens.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Configuration Subgraph
    subgraph "Configuration"
        ENV1["Env .env.development"]:::config
        ENV2["Env .env.production"]:::config
        ENV3["Env .env.template"]:::config
    end

    %% Next.js Application Subgraph
    subgraph "Next.js Application"
        PAGES["pages/"]:::next
        P_APP["pages/_app.tsx"]:::next
        P_DOC["pages/_document.tsx"]:::next
    end

    %% UI Components Subgraph
    subgraph "UI Components"
        UI["components/"]:::ui
    end

    %% Builder.io Integration Subgraph
    subgraph "Builder.io Integration"
        BLOCKS["blocks/"]:::builder
        B_CI["blocks/CloudinaryImage"]:::builder
        B_CV["blocks/CollectionView"]:::builder
        B_PG["blocks/ProductGrid"]:::builder
        B_PV["blocks/ProductView"]:::builder
        B_CONFIG["config/builder.ts"]:::builder
    end

    %% Builder Content Sync
    B_SYNC["lib/resolve-builder-content.ts"]:::builder

    %% Shopify Integration Subgraph
    subgraph "Shopify Integration"
        SHOP_HOOKS["lib/shopify/storefront-data-hooks/"]:::shopify
        SHOP_CONFIG["config/shopify.ts"]:::shopify
    end

    %% Utility and Helper Libraries Subgraph
    subgraph "Utility & Helper Libraries"
        LIB["lib/"]:::utility
        LIB_CLICK["lib/click-outside"]:::utility
        LIB_HOOKS["lib/hooks"]:::utility
        LIB_LAYOUT["lib/get-layout-props.ts"]:::utility
    end

    %% External Services
    SHOPIFY_API["Shopify API"]:::external
    BUILDER_API["Builder.io API"]:::external

    %% Relationships

    %% Configuration feeds into integrations
    ENV1 -->|"config"| SHOP_CONFIG
    ENV2 -->|"config"| SHOP_CONFIG
    ENV3 -->|"config"| SHOP_CONFIG
    ENV1 -->|"config"| B_CONFIG
    ENV2 -->|"config"| B_CONFIG
    ENV3 -->|"config"| B_CONFIG

    %% Next.js Application interactions
    PAGES -->|"rendersUI"| UI
    P_APP -->|"globalContext"| UI
    PAGES -->|"fetchData"| SHOP_HOOKS

    %% Shopify Integration flows
    SHOP_HOOKS -->|"APIcall"| SHOPIFY_API
    SHOP_CONFIG -->|"config"| SHOPIFY_API

    %% Builder.io Integration flows
    BLOCKS -->|"dynamicContent"| UI
    B_CONFIG -->|"config"| BUILDER_API
    BLOCKS -->|"content"| BUILDER_API
    B_SYNC -->|"injects"| BLOCKS

    %% Utility usage by UI and Application
    UI -->|"hooks&utils"| LIB
    PAGES -->|"usesUtils"| LIB

    %% Additional integration flows among Builder components
    B_CI --- BLOCKS
    B_CV --- BLOCKS
    B_PG --- BLOCKS
    B_PV --- BLOCKS

    %% Click Events
    click PAGES "https://github.com/builderio/nextjs-shopify/tree/master/pages/"
    click P_APP "https://github.com/builderio/nextjs-shopify/blob/master/pages/_app.tsx"
    click P_DOC "https://github.com/builderio/nextjs-shopify/blob/master/pages/_document.tsx"
    
    click UI "https://github.com/builderio/nextjs-shopify/tree/master/components/"
    
    click BLOCKS "https://github.com/builderio/nextjs-shopify/tree/master/blocks/"
    click B_CI "https://github.com/builderio/nextjs-shopify/tree/master/blocks/CloudinaryImage"
    click B_CV "https://github.com/builderio/nextjs-shopify/tree/master/blocks/CollectionView"
    click B_PG "https://github.com/builderio/nextjs-shopify/tree/master/blocks/ProductGrid"
    click B_PV "https://github.com/builderio/nextjs-shopify/tree/master/blocks/ProductView"
    click B_CONFIG "https://github.com/builderio/nextjs-shopify/blob/master/config/builder.ts"
    
    click B_SYNC "https://github.com/builderio/nextjs-shopify/blob/master/lib/resolve-builder-content.ts"
    
    click SHOP_HOOKS "https://github.com/builderio/nextjs-shopify/tree/master/lib/shopify/storefront-data-hooks/"
    click SHOP_CONFIG "https://github.com/builderio/nextjs-shopify/blob/master/config/shopify.ts"
    
    click ENV1 "https://github.com/builderio/nextjs-shopify/blob/master/.env.development"
    click ENV2 "https://github.com/builderio/nextjs-shopify/blob/master/.env.production"
    click ENV3 "https://github.com/builderio/nextjs-shopify/blob/master/.env.template"
    
    click LIB "https://github.com/builderio/nextjs-shopify/tree/master/lib/"
    click LIB_CLICK "https://github.com/builderio/nextjs-shopify/tree/master/lib/click-outside"
    click LIB_HOOKS "https://github.com/builderio/nextjs-shopify/tree/master/lib/hooks"
    click LIB_LAYOUT "https://github.com/builderio/nextjs-shopify/blob/master/lib/get-layout-props.ts"
    
    %% Class Definitions for styling
    classDef next fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef ui fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef builder fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef shopify fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef config fill:#FDF6E3,stroke:#000,stroke-width:1px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
```
