Graph
The gql function writes typed Storefront API queries, mutations, and fragments. TypeScript infers each operation's result and variables types without a codegen step.
Customer Account API documents use a separate gql function from @shopify/hydrogen/customer-account.
Import gql, InferResult, and InferVariables from @shopify/hydrogen.
Anchor to Typed queries and mutationsTyped queries and mutations
Writes a typed Storefront API query, mutation, or fragment. At runtime, the function returns the query text with each fragment appended once.
TypeScript infers the result and variables types from Hydrogen's bundled Storefront API schema, even when the client targets another . Read the types with and . To type a fragment on its own, compose the fragment into a query and read the type from the query. The helper from gql.tada doesn't accept gql documents.
Anchor to gql-parametersParameters
- Anchor to sourcesourcesourcestringstringrequiredrequired
The Storefront API query, mutation, or fragment source text.
- Anchor to fragmentsfragmentsfragmentsreadonly AnyStorefrontQueryString[]readonly AnyStorefrontQueryString[]
The
gqlfragments that the query text spreads.
Anchor to gql-returnsReturns
A typed document to pass to the client's
graphql()method.
AnyStorefrontQueryString
Any `gql` document, whatever its result and variables types. Use the type to accept any Storefront API document.
string & StorefrontQueryMetadataStorefrontQueryMetadata
Type-only properties that mark a string as a `gql` document.
- __hydrogenQueryBrand
Marks a string that `gql` returns. The property exists only in types.
true - __hydrogenQuerySource
The document's query text, which TypeScript reads to infer types. The property exists only in types.
Source
TypeScript
Examples
Description
Declare a product query and run it with a Storefront API client. This example checks `result.errors` before it reads the typed title.
TypeScript
import { gql, type StorefrontClient } from "@shopify/hydrogen"; const PRODUCT_QUERY = gql(` query Product($handle: String!) { product(handle: $handle) { title } } `); export async function getProductTitle(storefront: StorefrontClient, handle: string) { const result = await storefront.graphql(PRODUCT_QUERY, { variables: { handle }, }); if (result.errors) return null; return result.data.product?.title ?? null; }Description
Compose a product fragment into a list query. This example derives the result type from the `StorefrontApi` namespace.
TypeScript
import { gql, type StorefrontApi } from "@shopify/hydrogen"; const PRODUCT_FIELDS = gql(`fragment ProductFields on Product { title handle }`); export const PRODUCTS_QUERY = gql( `query Products { products(first: 10) { nodes { ...ProductFields } } }`, [PRODUCT_FIELDS], ); export type ProductsResult = StorefrontApi.ResultOf<typeof PRODUCTS_QUERY>;Description
Derive result and variables types from a query string. This example types a function parameter with `InferResult` and a variables object with `InferVariables`.
TypeScript
import type { InferResult, InferVariables } from "@shopify/hydrogen"; const PRODUCT_QUERY = ` query Product($handle: String!) { product(handle: $handle) { title } } `; type ProductQuery = InferResult<typeof PRODUCT_QUERY>; type ProductQueryVariables = InferVariables<typeof PRODUCT_QUERY>; export function productTitle(data: ProductQuery) { return data.product?.title ?? null; } export const variables: ProductQueryVariables = { handle: "snowboard" };
Anchor to Type helpersType helpers
InferResult and InferVariables type a result or variables shape outside a GraphQL call, such as a function parameter or a loader argument. Pass the query text as a string literal type. For a gql document, use StorefrontApi.ResultOf and StorefrontApi.VariablesOf. InferResult and InferVariables resolve to never for a gql document.