feat(codegen): warn when hydrogen schema version differs

Signed-off-by: Frederik Bußmann <frederik@bussmann.io>

Author: freb97

docs/content/2.essentials/4.customer-account.md

@@ -32,7 +32,7 @@ npm install @shopify/hydrogen
 ## Setup
 
 For the type generation to work correctly, make sure to install the `@shopify/hydrogen` package for the appropriate version of the API 
-you are using (e.g. `@shopify/hydrogen@2026.4.0` for API version 2026-04).
+you are using (e.g. `@shopify/hydrogen@2026.4.0` for API version 2026-04). The module warns during type generation when two versions differ.
 
 The customer account session is stored in an encrypted cookie.
 In development, a session password is generated automatically and written to your `.env` file. In production,

pnpm-lock.yaml

@@ -2,14 +2,15 @@ import type { Nuxt } from '@nuxt/schema'
 
 import type { ShopifyConfig } from '../types'
 
-import { relative, sep } from 'node:path'
+import { relative } from 'node:path'
 
 import { addTemplate } from '@nuxt/kit'
 
 import { ShopifyClientType } from '../schemas'
 import { getConfiguredClients } from '../utils/clients'
 import { getIntrospectionFilename } from '../utils/templates'
 import { useLogger } from '../utils/log'
+import { toPosix } from '../utils/codegen'
 
 const PROJECT_ORDER = [
   ShopifyClientType.Admin,
@@ -19,8 +20,6 @@ const PROJECT_ORDER = [
 
 const DIR_IGNORES = ['node_modules', 'dist', '.nuxt', '.output']
 
-const toPosix = (path: string) => path.split(sep).join('/')
-
 interface GraphqlProject {
   schema: string
   documents: string[]

src/setup/graphql-config.ts

@@ -15,6 +15,7 @@ import { createGraphqlTransformPlugin } from '../utils/graphql/transform'
 import { getConfiguredClients } from '../utils/clients'
 import { scanFragments } from '../utils/graphql/registry'
 import { useLogger } from '../utils/log'
+import { toPosix } from '../utils/codegen'
 
 const ROUTING_ORDER = [
   ShopifyClientType.Admin,
@@ -24,8 +25,6 @@ const ROUTING_ORDER = [
 
 const AUTO_IMPORT_CHANGING_EVENTS = ['add', 'unlink'] as const
 
-const toPosix = (path: string) => path.split(sep).join('/')
-
 const within = (dirs: string[], path: string) =>
   dirs.some(dir => path === dir || path.startsWith(dir + sep))
 

src/setup/graphql-transform.ts

@@ -19,10 +19,6 @@ export default function setupVite(nuxt: Nuxt, config: ShopifyConfig) {
     deps.push('@shopify/graphql-client')
   }
 
-  if (config.clients?.customerAccount) {
-    deps.push('@shopify/hydrogen')
-  }
-
   if (config.analytics) {
     deps.push('@shopify/hydrogen-react')
   }

src/setup/vite.ts

@@ -5,8 +5,7 @@ import type { ShopifyConfig } from '../types'
 
 import { existsSync, statSync } from 'node:fs'
 import { mkdir, stat, writeFile } from 'node:fs/promises'
-import { basename, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { basename, dirname, sep } from 'node:path'
 import { generate } from '@graphql-codegen/cli'
 import { preset, pluckConfig } from '@shopify/graphql-codegen'
 import { LogLevels } from 'consola'
@@ -16,7 +15,7 @@ import { joinURL } from 'ufo'
 
 import { ShopifyClientType } from '../schemas'
 import { useLogger } from './log'
-import { isInstalled } from './install'
+import { getInstalledVersion, resolveInstalledPath } from './install'
 import { getAdminAccessToken } from '../runtime/utils/clients/admin/auth'
 import {
   ADMIN_TOKEN_HEADER,
@@ -25,12 +24,11 @@ import {
   PUBLIC_TOKEN_HEADER,
 } from '../runtime/utils/clients/transport'
 
-const HYDROGEN_STOREFRONT_SCHEMA = '@shopify/hydrogen/storefront.schema.json'
-const HYDROGEN_CUSTOMER_ACCOUNT_SCHEMA = '@shopify/hydrogen/customer-account.schema.json'
+const HYDROGEN = '@shopify/hydrogen'
 
 const HYDROGEN_SCHEMAS: Partial<Record<ShopifyClientType, string>> = {
-  [ShopifyClientType.Storefront]: HYDROGEN_STOREFRONT_SCHEMA,
-  [ShopifyClientType.CustomerAccount]: HYDROGEN_CUSTOMER_ACCOUNT_SCHEMA,
+  [ShopifyClientType.Storefront]: `${HYDROGEN}/storefront.schema.json`,
+  [ShopifyClientType.CustomerAccount]: `${HYDROGEN}/customer-account.schema.json`,
 }
 
 const INTROSPECTION_ATTEMPTS = 3
@@ -61,18 +59,43 @@ type InterfaceExtensionsParams = {
   mutationType: string
 }
 
-function resolveSchemaPath(schemaId: string) {
-  return fileURLToPath(import.meta.resolve(schemaId))
-}
+export const toPosix = (path: string) => path.split(sep).join('/')
 
 function getHydrogenSchema(clientType: ShopifyClientType) {
   const schemaId = HYDROGEN_SCHEMAS[clientType]
+  const schemaPath = schemaId && resolveInstalledPath(schemaId)
 
-  if (!schemaId || !isInstalled(schemaId)) {
-    return undefined
-  }
+  return schemaPath ? [schemaPath] : undefined
+}
+
+function isHydrogenSchema(schema: Types.ConfiguredOutput['schema'], clientType: ShopifyClientType) {
+  const [hydrogenSchema] = getHydrogenSchema(clientType) ?? []
+
+  return !!hydrogenSchema && [schema].flat().includes(hydrogenSchema)
+}
+
+async function getHydrogenSchemaApiVersion() {
+  const version = await getInstalledVersion(HYDROGEN)
+  const [year, month] = version?.split('.').map(Number) ?? []
+
+  if (!year || !month) return undefined
 
-  return [resolveSchemaPath(schemaId)]
+  const apiReleaseMonth = month - ((month - 1) % 3)
+
+  return `${year}-${String(apiReleaseMonth).padStart(2, '0')}`
+}
+
+async function warnOnHydrogenSchemaMismatch({ clientType, clientConfig }: ShopifyTemplateOptions) {
+  const schemaApiVersion = await getHydrogenSchemaApiVersion()
+  const apiVersion = clientConfig?.apiVersion
+
+  if (!schemaApiVersion || !apiVersion || schemaApiVersion === apiVersion) return
+
+  useLogger().warn(
+    `The ${kebabCase(clientType)} types are generated from the \`${HYDROGEN}\` schema for API version \`${schemaApiVersion}\`, `
+    + `but the client uses \`${apiVersion}\`. Set \`clients.${clientType}.apiVersion\` to \`${schemaApiVersion}\`, `
+    + `or install the matching \`${HYDROGEN}\` release`,
+  )
 }
 
 function isRemoteSchema(schema: Types.ConfiguredOutput['schema']) {
@@ -276,7 +299,7 @@ async function getIntrospectionSource(options: ShopifyTemplateOptions) {
     }
   }
   else if (clientType === ShopifyClientType.CustomerAccount) {
-    return [resolveSchemaPath(HYDROGEN_CUSTOMER_ACCOUNT_SCHEMA)]
+    return getHydrogenSchema(clientType)
   }
   else if (clientType === ShopifyClientType.Admin) {
     const adminConfig = clientConfig as NonNullable<ShopifyConfig['clients']['admin']>
@@ -334,6 +357,10 @@ async function generateIntrospection(nuxt: Nuxt, options: ShopifyTemplateOptions
     config: generatorConfig,
   })
 
+  if (isHydrogenSchema(generatorConfig.schema, options.clientType)) {
+    await warnOnHydrogenSchemaMismatch(options)
+  }
+
   const contents = await runIntrospection(nuxt, options, generatorConfig, config => ({
     overwrite: true,
     ignoreNoDocuments: true,

src/utils/codegen.ts

@@ -1,11 +1,12 @@
 import type { GraphqlDefinition } from '../../runtime/utils/graphql/scanner'
 
 import { readFile, readdir } from 'node:fs/promises'
-import { join, relative, sep } from 'node:path'
+import { join, relative } from 'node:path'
 
 import { collectSpreads, scanDefinitions } from '../../runtime/utils/graphql/scanner'
 import { useLogger } from '../log'
 import { findGraphqlLiterals } from './literals'
+import { toPosix } from '../codegen'
 
 const SCANNABLE = /\.(?:ts|js|mjs|cjs|mts|cts|vue|gql|graphql)$/
 const SCHEMA_LANGUAGE = /\.(?:gql|graphql)$/
@@ -35,8 +36,6 @@ function createRegistry(): FragmentRegistry {
   return { fragments: new Map(), provides: new Map() }
 }
 
-const toPosix = (path: string) => path.split(sep).join('/')
-
 const hasUnresolvedInterpolation = (text: string) => text.includes('${')
 
 async function listFiles(dir: string): Promise<string[]> {

src/utils/graphql/registry.ts

@@ -1,21 +1,21 @@
-import { directoryToURL, resolveModule } from '@nuxt/kit'
+import { directoryToURL } from '@nuxt/kit'
+import { resolveModulePath } from 'exsolve'
+import { readPackageJSON } from 'pkg-types'
+
+export function resolveInstalledPath(id: string): string | undefined {
+  return resolveModulePath(id, { from: import.meta.url, try: true })
+}
 
 export function isInstalled(id: string): boolean {
-  try {
-    import.meta.resolve(id)
-    return true
-  }
-  catch {
-    return false
-  }
+  return !!resolveInstalledPath(id)
 }
 
 export function isResolvableFrom(id: string, directory: string): boolean {
-  try {
-    resolveModule(id, { url: directoryToURL(directory) })
-    return true
-  }
-  catch {
-    return false
-  }
+  return !!resolveModulePath(id, { from: directoryToURL(directory), try: true })
+}
+
+export async function getInstalledVersion(id: string): Promise<string | undefined> {
+  const packageJson = await readPackageJSON(id, { from: import.meta.url }).catch(() => undefined)
+
+  return packageJson?.version
 }

src/utils/install.ts

@@ -4,6 +4,7 @@ export const useCart = () => {
   const { t } = useI18n()
 
   const analytics = useShopifyAnalytics()
+  const { params: localization } = useLocalization()
 
   const cart = useState<CartFieldsFragment | undefined>('shopify-cart', () => undefined)
   const loading = useState('shopify-cart-loading', () => ref(false))
@@ -77,6 +78,7 @@ export const useCart = () => {
           quantity,
         },
       ],
+      ...localization.value,
     }),
   })).then(({ data }) => {
     id.value = data?.cartCreate?.cart?.id
@@ -101,6 +103,7 @@ export const useCart = () => {
     `, {
       variables: cartGetInputSchema.parse({
         id: id.value,
+        ...localization.value,
       }),
     })).then(({ data }) => {
       if (!data?.cart) id.value = undefined
@@ -137,6 +140,7 @@ export const useCart = () => {
             quantity,
           },
         ],
+        ...localization.value,
       }),
     })).then(({ data }) =>
       notifyAdded(variantId, data?.cartLinesAdd?.cart ?? undefined),
@@ -168,6 +172,7 @@ export const useCart = () => {
           quantity,
         },
       ],
+      ...localization.value,
     }),
   })).then(({ data }) => {
     setCart(data?.cartLinesUpdate?.cart ?? undefined)
@@ -203,6 +208,7 @@ export const useCart = () => {
     variables: cartRemoveInputSchema.parse({
       cartId: id.value,
       lineIds: [variantId],
+      ...localization.value,
     }),
   })).then(({ data }) => {
     setCart(data?.cartLinesRemove?.cart ?? undefined)