Section A
Storefront API
Hydrogen 2026.10 ships a type-safe Storefront API client. gql() infers result and variable types from the query string itself, with no codegen step. Every query in this app goes through it, and in demo mode the client's injected fetch executes them against Hydrogen's own packaged schema.
GraphQL queries & typed responses
Write a query, run it through the same-origin SFAPI proxy, inspect the JSON. Invalid fields fail schema validation exactly like on Shopify.
- Hydrogen API
createStorefrontClientgqlStorefrontApi.ResultOfclient.graphql- Data
- Demo: mock SFAPI (graphql-js over storefront.schema.json). Live: your store.
import { gql, type StorefrontApi } from "@shopify/hydrogen";
const PRODUCT = gql(`
query Product($handle: String!, $country: CountryCode)
@inContext(country: $country) {
product(handle: $handle) { title priceRange { minVariantPrice { amount currencyCode } } }
}
`);
type Result = StorefrontApi.ResultOf<typeof PRODUCT>; // inferred, no codegen
// $country is filled from requestContext.locale automatically
const { data, errors } = await storefront.graphql(PRODUCT, { variables: { handle } });See it in the store:All loaders
API error handling
Transport failures throw StorefrontApiError / StorefrontTimeoutError; GraphQL errors are returned alongside partial data. Loaders log errors and return 500, and return 404 only when there are no errors and the resource is missing.
- Hydrogen API
StorefrontApiErrorStorefrontTimeoutErrorresult.errors- Data
- Any
const { data, errors } = await storefront.graphql(PRODUCT_QUERY, { variables });
if (errors) {
console.error("[nova] product query failed", errors);
throw new Response("Product query failed", { status: 500 });
}
if (!data?.product) throw new Response("Not found", { status: 404 });See it in the store:Missing product (404)
Store configuration
Shop name, payment settings, policies, localization and brand come from shop and localization queries in the root loader.
- Hydrogen API
shoplocalization- Data
- Mock store config (app/mocks/store.ts) or your store