# konkonam/nuxt-shopify architecture

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

- Interactive diagram: https://gitdiagram.com/konkonam/nuxt-shopify
- Repository: https://github.com/konkonam/nuxt-shopify

## Overview

##### Project type and purpose
- This is an open-source Nuxt module (“@konkonam/nuxt-shopify”) that plugs into Nuxt 3 & 4 applications as a GraphQL API connector for Shopify.
- It provides code generation for TypeScript types, client- and server-side composables, Nitro endpoints, sandboxed GraphiQL, starter templates, and playground examples.

##### File structure
- Top-level:
– package.json, tsconfig.json, build.config.ts, eslint.config.mjs, graphql.config.yml → module build/config and quality tooling
– .env.example/.envrc → environment variables for Shopify credentials
– src/ → core module code (commands, module registration, runtime, templates, types, utilities)
– template/ → Nuxt storefront+server starter app template (full-stack storefront example)
– playgrounds/ → live projects demonstrating module usage in Nuxt apps
– docs/ → VitePress documentation site
- src breakdown:
– commands/init.ts → CLI initialization
– module.ts → Nuxt module entry point, hooks into Nuxt lifecycle
– runtime/ → injected code at runtime (client & server), exposable composables and Nitro utilities
– templates/ → generates sandbox/template scaffolding for users at install/init
– types/ → ambient type declarations for Shopify entities
– utils/ → codegen orchestrators, config loaders, logging, validation
- template/ breakdown:
– app/ → Nuxt app structure (pages, components, composables, layouts) using useStorefront/useAdmin
– server/api/ → Nitro API endpoints wrapping Shopify operations
– graphql.config.yaml, package.json, nuxt.config.ts → sample configuration for codegen and module

##### Key insights from the README
- The module auto-generates TypeScript types for GraphQL operations and hot-reloads on file changes.
- It exposes two main composables: useStorefront (client & server) and useAdmin (server only) via Nitro event handlers.
- GraphQL files (.ts/.gql) are scanned and processed, separated by suffix (.admin).
- Generated artifacts live in .nuxt/types and .nuxt/schema.

##### Main components and interactions
a. Nuxt application (host)
– nuxt.config.ts with module registration and shopify config
– Vue components/pages calling useStorefront composable
– Nitro server with /api/* endpoints using useStorefront/useAdmin
b. Nuxt-Shopify module
– Module entry (module.ts) registers hooks for codegen, plugin injection, schema extraction
– CLI command (init) scaffolds template app
c. Code generation pipeline
– GraphQL schema fetch from Shopify Admin & Storefront APIs
– GraphQL operation files (.ts & .gql) scanned → TypeScript types generated → written to .nuxt/types and .nuxt/schema
d. Runtime layer
– Plugin injected into Nuxt: provides composables (useStorefront, useAdmin)
– Nitro utilities wrap underlying HTTP calls to Shopify
e. External services
– Shopify Storefront GraphQL endpoint
– Shopify Admin GraphQL endpoint
f. Developer tools
– Playground apps demonstrating integration
– Documentation site powered by VitePress

##### Relationships and data flow
- At build time:
nuxt.config.ts → module hook → codegen pipeline → fetch Shopify schemas → scan operations → generate types
- At runtime (SSR or client):
Vue component → useStorefront composable → if client, direct fetch with public token; if server, Nitro proxy → external Shopify endpoint → returns typed data → component renders
- At runtime (admin):
Nitro endpoint → useAdmin composable → authorized fetch → Shopify Admin endpoint → returns typed data → API response

##### Architectural patterns and principles
- Modular plugin architecture: Nuxt module registers build and runtime hooks
- Code-first / convention-over-configuration for GraphQL codegen
- Separation of concerns: client-side vs server-side API composables
- File-based routing for both Nuxt pages and Nitro endpoints
- Template scaffolding for fast project bootstrap

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nuxt Host Application
    subgraph "Nuxt Host Application"
        direction TB
        nuxtConfig["nuxt.config.ts"]:::build
        pages["Vue Pages & Components"]:::runtimeClient
        NitroEndpoints["Nitro /api/* Endpoints"]:::runtimeServer
    end

    %% Nuxt-Shopify Module
    subgraph "Nuxt-Shopify Module"
        direction TB

        subgraph "Build Plugin"
            direction TB
            moduleEntry["Module Entry (module.ts)"]:::build
            codegenOrch["Code Generation Orchestrator"]:::build
            configLoader["Configuration Loader"]:::build
            logging["Logging Utility"]:::build
            validation["Validation Utility"]:::build
        end

        subgraph "Code Generation Pipeline"
            direction TB
            schemaFetch["Fetch Shopify Schemas"]:::build
            scanOps["Scan .gql/.ts Operations"]:::build
            typeGen["Generate TypeScript Types"]:::build
            artifacts[".nuxt/types & .nuxt/schema"]:::build
        end

        subgraph "Runtime Plugin"
            direction TB
            injectPlugin["Plugin Injection"]:::runtimeClient
            composablesRuntime["useStorefront Composable"]:::runtimeClient
            adminComposable["useAdmin Composable"]:::runtimeServer
            nitroUtilsStorefront["Storefront Server Util"]:::runtimeServer
            nitroUtilsAdmin["Admin Server Util"]:::runtimeServer
        end
    end

    %% External Services
    subgraph "External Shopify APIs"
        direction TB
        StorefrontAPI["Shopify Storefront GraphQL API"]:::external
        AdminAPI["Shopify Admin GraphQL API"]:::external
    end

    %% Developer Tools
    subgraph "Developer Tools"
        direction TB
        initCmd["CLI Init Command"]:::devtool
        TemplateStarter["Starter App Template"]:::devtool
        Playground1["Playground Nuxt v4"]:::devtool
        Playground2["Playground Nuxt v3"]:::devtool
        Docs["Documentation Site"]:::devtool
    end

    %% Build-time Flows
    nuxtConfig -->|"register module"| moduleEntry
    moduleEntry -->|hooks into| codegenOrch
    codegenOrch -->|load config| configLoader
    codegenOrch -->|log actions| logging
    codegenOrch -->|validate| validation
    codegenOrch -->|start pipeline| schemaFetch
    schemaFetch --> scanOps
    scanOps --> typeGen
    typeGen --> artifacts

    %% Runtime Flows
    injectPlugin --> composablesRuntime
    injectPlugin --> adminComposable
    pages -->|calls| composablesRuntime
    composablesRuntime -->|client fetch| StorefrontAPI
    composablesRuntime -->|server fetch via Nitro| NitroEndpoints
    NitroEndpoints -->|wrap with util| nitroUtilsStorefront
    nitroUtilsStorefront -->|proxy request| StorefrontAPI
    NitroEndpoints -->|admin fetch| nitroUtilsAdmin
    nitroUtilsAdmin -->|proxy request| AdminAPI
    pages -->|admin API calls via Nitro| adminComposable

    %% Developer Tools Flows
    initCmd -->|scaffold| TemplateStarter
    TemplateStarter --> playground1
    TemplateStarter --> playground2
    Docs

    %% Click Events
    click moduleEntry "https://github.com/konkonam/nuxt-shopify/blob/main/src/module.ts"
    click initCmd "https://github.com/konkonam/nuxt-shopify/blob/main/src/commands/init.ts"
    click composablesRuntime "https://github.com/konkonam/nuxt-shopify/blob/main/src/runtime/composables/useStorefront.ts"
    click nitroUtilsStorefront "https://github.com/konkonam/nuxt-shopify/blob/main/src/runtime/server/utils/useStorefront.ts"
    click nitroUtilsAdmin "https://github.com/konkonam/nuxt-shopify/blob/main/src/runtime/server/utils/useAdmin.ts"
    click codegenOrch "https://github.com/konkonam/nuxt-shopify/blob/main/src/utils/codegen.ts"
    click configLoader "https://github.com/konkonam/nuxt-shopify/blob/main/src/utils/config.ts"
    click logging "https://github.com/konkonam/nuxt-shopify/blob/main/src/utils/log.ts"
    click validation "https://github.com/konkonam/nuxt-shopify/blob/main/src/utils/validation.ts"
    click sandboxTemplate "https://github.com/konkonam/nuxt-shopify/blob/main/src/templates/sandbox-template.ts"
    click utilsTemplate "https://github.com/konkonam/nuxt-shopify/blob/main/src/templates/utils-template.ts"
    click typesIndex "https://github.com/konkonam/nuxt-shopify/blob/main/src/types/index.d.ts"
    click typesShopify "https://github.com/konkonam/nuxt-shopify/blob/main/src/types/shopify.d.ts"
    click buildConfig "https://github.com/konkonam/nuxt-shopify/blob/main/build.config.ts"
    click graphqlConfig "https://github.com/konkonam/nuxt-shopify/blob/main/graphql.config.yml"
    click tsconfig "https://github.com/konkonam/nuxt-shopify/blob/main/tsconfig.json"
    click eslintConfig "https://github.com/konkonam/nuxt-shopify/blob/main/eslint.config.mjs"
    click TemplateStarter "https://github.com/konkonam/nuxt-shopify/tree/main/template/"
    click Playground1 "https://github.com/konkonam/nuxt-shopify/tree/main/playgrounds/playground-nuxt-v4/"
    click Playground2 "https://github.com/konkonam/nuxt-shopify/tree/main/playgrounds/playground/"
    click Docs "https://github.com/konkonam/nuxt-shopify/tree/main/docs/"

    %% Styles
    classDef build fill:#FFEECC,stroke:#333,stroke-width:1px
    classDef runtimeClient fill:#CCEEFF,stroke:#333,stroke-width:1px
    classDef runtimeServer fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef external fill:#FFE4E1,stroke:#333,stroke-width:1px
    classDef devtool fill:#E8E8E8,stroke:#333,stroke-width:1px
```
