How konkonam/nuxt-shopify works
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