Shopify GraphQL Utilities
Relevant source files
The following files were used as context for generating this wiki page:
Shopify GraphQL Utilities provide a structured and type-safe approach to interacting with the Shopify Storefront API. This system centralizes GraphQL document management, automatic context injection, and data normalization to ensure consistency across the multi-tenant platform. By leveraging gql.tada, the project achieves end-to-end type safety for commerce data fetching.
Sources: README.md:12-25, CLAUDE.md:27-28, CONTEXT.md:27-30
Architecture and Core Components
The Shopify GraphQL architecture is built around the ShopifyApolloApiClient, which is the sanctioned method for making Shopify calls. This client is always constructed with specific { shop, locale } parameters to maintain tenant isolation.
GraphQL Processing Flow
The system uses an Apollo DocumentTransform from the @nordcom/commerce-shopify-graphql package to automatically inject the @inContext(country, language) directive into all outgoing queries. This prevents developers from having to manually declare regional context for every operation.
The diagram shows how a request is transformed from a standard GraphQL query into a tenant-aware request through automated context injection.
Sources: apps/storefront/README.md:91-104, CONTEXT.md:214-219
Technical Stack
| Component | Technology | Description |
|---|---|---|
| GraphQL Engine | gql.tada | Provides type-safe GraphQL definitions via the graphql() function. |
| Client | @apollo/client | Primary client for executing Storefront API queries. |
| React Integration | @shopify/hydrogen-react | Used for connection flattening and Shopify-specific hooks. |
| Schema Management | scripts/copy-schema.ts | Utilities to sync the Shopify Storefront API schema for local development. |
Sources: packages/shopify-graphql/package.json:48-60, CLAUDE.md:27-28
Data Fetching and Normalization
Data returned from Shopify is often raw and requires transformation before it can be used by the storefront. The utility layer includes normalization functions that convert GraphQL fragments into standardized TypeScript interfaces.
Example: Page Data Normalization
The ShopifyPageApi demonstrates the standard pattern: fetching data via a fragment and then passing it through a normalize function.
// apps/storefront/src/api/shopify/page.ts:68-83
function normalize(page: PageFields): NormalizedShopifyPage {
return {
id: page.id,
handle: page.handle,
title: page.title,
body: page.body,
bodySummary: page.bodySummary,
seo: {
title: page.seo?.title ?? null,
description: page.seo?.description ?? null,
},
createdAt: page.createdAt,
updatedAt: page.updatedAt,
onlineStoreUrl: page.onlineStoreUrl ?? null,
};
}
Sources: apps/storefront/src/api/shopify/page.ts:68-83
Shopify HTML Utilities
A specialized utility package, @nordcom/commerce-shopify-html, handles the conversion of Shopify's rich-text HTML (e.g., product.descriptionHtml) into React trees or plain text strings without using dangerouslySetInnerHTML.
| Function | Output | Use Case |
|---|---|---|
toReactNodes | React Tree | Rendering descriptions with custom components (e.g., next/link for <a>). |
toPlainText | string | Generating SEO meta descriptions or OG tags. |
normalize | Sanitized HTML | Stripping <script>, <style>, and data-* attributes. |
Sources: packages/shopify-html/README.md:9-40
Tenant and Locale Resolution
The utilities are strictly bound to the multi-tenant nature of the platform. Hostname-based resolution occurs in the middleware, which then passes the resolved shop and locale to the GraphQL clients.
Implementation Constraints
- Directive Restrictions: Source operations must NOT pre-declare
@inContext,$country, or$language. The internal transform will throwDuplicateContextDirectiveErrorif they are present. - Explicit Context: Helpers must never use implicit or "thread-local" shop context. Every call must carry an explicit
{ shop, locale }. - Taint Protection: Provider tokens used for client construction are guarded with React's
experimental_taintUniqueValueto prevent accidental exposure to Client Components.
Sources: apps/storefront/README.md:91-104, CONTEXT.md:465-470, CLAUDE.md:105-106
Summary
The Shopify GraphQL Utilities serve as a robust abstraction layer that hides the complexities of multi-tenancy and regional localization. By combining gql.tada for type safety, Apollo for data transport, and specialized normalization packages like @nordcom/commerce-shopify-html, the system provides a consistent and secure interface for commerce data throughout the platform.