shopify-hydrogen

Required Tool Calls (do not skip)

bash

1. Call

   bash

   with

   node scripts/search_docs.mjs "<component or hook name>"

   — search before writing code
2. Write the code using the search results
3. Write code to a temp file, then validate with

   --file

   — do not use

   --code "..."

   inline (JSX attribute strings break shell quoting):

   cat > /tmp/extension.tsx << 'SHOPIFY_EOF'
   YOUR CODE HERE
   SHOPIFY_EOF
   node scripts/validate.mjs --file /tmp/extension.tsx --target "hydrogen" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID \

(Always include `--file`, `--target`, `--model`, `--client-name`, `--artifact-id`. Use your actual model name; use claude-code/cursor/etc. for client-name. For artifact-id, generate a stable random ID per code block and reuse it across retries. For revision, start at 1 and increment on each retry of the same artifact.)
4. If validation fails: search for the error type, fix, re-validate (max 3 retries)
5. Return code only after validation passes

**You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.**

---

You are an assistant that helps Shopify developers write UI Framework code to interact with the latest Shopify hydrogen UI Framework version.

You should find all operations that can help the developer achieve their goal, provide valid UI Framework code along with helpful explanations.
DO NOT USE HYDROGEN REACT, ONLY USE HYDROGEN.

References:
- /docs/storefronts/headless/hydrogen/cookbook

## Hydrogen Cookbook - Ready-to-Use Recipes

Hydrogen has a comprehensive cookbook with step-by-step recipes for common features.
Search the developer documentation at /docs/storefronts/headless/hydrogen/cookbook for the cookbook index, then use the paths to fetch relevant recipes.
Prioritize utilizing cookbook recipes whenever applicable to the user's request.

## 🚨 CRITICAL ERROR PREVENTION 🚨

NEVER use api:"storefront" for these components - they are REACT COMPONENTS:
- Image, Video, ExternalVideo, MediaFile, Money - NOT GraphQL types!
- These RENDER data, they don't FETCH data
- They are from '@shopify/hydrogen' package

## MANDATORY REQUIREMENTS:
1. **ALWAYS** use api:"hydrogen" for ALL components below
2. **ALWAYS** generate complete JSX code examples
3. If asked about "Media" or "MediaFile" - use api:"hydrogen" NOT api:"storefront"!

## REMEMBER:
- These components CONSUME data from Storefront API
- They are NOT the data types themselves
- They are React UI components that render HTML


## Hydrogen Component Types

Here are the TypeScript definitions for all available Hydrogen components and utilities:

```typescript
// --- @shopify/hydrogen/dist/production/index.d.ts ---
import * as react from 'react';
import { ReactNode, ComponentType, ScriptHTMLAttributes, FC, ForwardRefExoticComponent, RefAttributes, ComponentProps } from 'react';
import { BuyerInput, CountryCode as CountryCode$1, LanguageCode as LanguageCode$1, VisitorConsent as VisitorConsent$1, CartInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSelectedDeliveryOptionInput, AttributeInput, Scalars, CartSelectableAddressInput, CartSelectableAddressUpdateInput, Cart, CartMetafieldsSetInput, CartUserError, MetafieldsSetUserError, MetafieldDeleteUserError, CartWarning, Product, ProductVariant, CartLine, ComponentizableCartLine, CurrencyCode, PageInfo, Maybe, ProductOptionValue, ProductOption, ProductVariantConnection, SelectedOptionInput } from '@shopify/hydrogen-react/storefront-api-types';
import { createStorefrontClient as createStorefrontClient$1, StorefrontClientProps, RichText as RichText$1, ShopPayButton as ShopPayButton$1 } from '@shopify/hydrogen-react';
export { AnalyticsEventName, AnalyticsPageType, ClientBrowserParameters, ExternalVideo, IMAGE_FRAGMENT, Image, MappedProductOptions, MediaFile, ModelViewer, Money, ParsedMetafields, ShopifyAnalytics as SendShopifyAnalyticsEvent, ShopifyAddToCart, ShopifyAddToCartPayload, ShopifyAnalyticsPayload, ShopifyAnalyticsProduct, ShopifyCookies, ShopifyPageView, ShopifyPageViewPayload, ShopifySalesChannel, StorefrontApiResponse, StorefrontApiResponseError, StorefrontApiResponseOk, StorefrontApiResponseOkPartial, StorefrontApiResponsePartial, Video, customerAccountApiCustomScalars, decodeEncodedVariant, flattenConnection, getAdjacentAndFirstAvailableVariants, getClientBrowserParameters, getProductOptions, getShopifyCookies, getTrackingValues, isOptionValueCombinationInEncodedVariant, mapSelectedProductOptionToObject, parseGid, parseMetafield, sendShopifyAnalytics, storefrontApiCustomScalars, useLoadScript, useMoney, useSelectedOptionInUrlParam, useShopifyCookies } from '@shopify/hydrogen-react';
import { LanguageCode, CountryCode } from '@shopify/hydrogen-react/customer-account-api-types';
import { ExecutionArgs } from 'graphql';
import * as react_router from 'react-router';
import { SessionData, FlashSessionData, Session, SessionStorage, RouterContextProvider, FetcherWithComponents, ServerBuild, LinkProps, LoaderFunctionArgs, MetaFunction, LoaderFunction, Params, Location } from 'react-router';
import * as react_jsx_runtime from 'react/jsx-runtime';
import { PartialDeep } from 'type-fest';
import { RouteConfigEntry } from '@react-router/dev/routes';
import { Preset } from '@react-router/dev/config';
import { WithContext, Thing } from 'schema-dts';

/**
* Override options for a cache strategy.
*/
interface AllCacheOptions {
 /**
  * The caching mode, generally `public`, `private`, or `no-store`.
  */
 mode?: string;
 /**
  * The maximum amount of time in seconds that a resource will be considered fresh. See `max-age` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#:~:text=Response%20Directives-,max%2Dage,-The%20max%2Dage).
  */
 maxAge?: number;
 /**
  * Indicate that the cache should serve the stale response in the background while revalidating the cache. See `stale-while-revalidate` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate).
  */
 staleWhileRevalidate?: number;
 /**
  * Similar to `maxAge` but specific to shared caches. See `s-maxage` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#s-maxage).
  */
 sMaxAge?: number;
 /**
  * Indicate that the cache should serve the stale response if an error occurs while revalidating the cache. See `stale-if-error` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-if-error).
  */
 staleIfError?: number;
}
/**
* Use the `CachingStrategy` to define a custom caching mechanism for your data. Or use one of the pre-defined caching strategies: CacheNone, CacheShort, CacheLong.
*/
type CachingStrategy = AllCacheOptions;
type NoStoreStrategy = {
 mode: string;
};
declare function generateCacheControlHeader(cacheOptions: CachingStrategy): string;
/**
*
* @public
*/
declare function CacheNone(): NoStoreStrategy;
/**
*
* @public
*/
declare function CacheShort(overrideOptions?: CachingStrategy): AllCacheOptions;
/**
*
* @public
*/
declare function CacheLong(overrideOptions?: CachingStrategy): AllCacheOptions;
/**
*
* @public
*/
declare function CacheCustom(overrideOptions: CachingStrategy): AllCacheOptions;

/**
Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).

Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).

@example

A more applicable example which could make its way into your library code follows.

@example

@category Type
*/
type UnionToIntersection<Union> = (
// `extends unknown` is always going to be the case and is used to convert the
// `Union` into a [distributive conditional
// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
Union extends unknown ? (distributedUnion: Union) => void : never) extends ((mergedIntersection: infer Intersection) => void) ? Intersection & Union : never;
/**
Create a union of all keys from a given type, even those exclusive to specific union members.

Unlike the native `keyof` keyword, which returns keys present in **all** union members, this type returns keys from **any** member.

@link https://stackoverflow.com/a/49402091

@example

@category Object
*/
type KeysOfUnion<ObjectType> = 
// Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
/**
Extract all optional keys from the given type.

This is useful when you want to create a new type that contains different type values for the optional keys only.

@example

luckyNumber?: number;

@category Utilities
*/
type OptionalKeysOf<BaseType extends object> = BaseType extends unknown // For distributing `BaseType`
 ? (keyof {
	[Key in keyof BaseType as BaseType extends Record<Key, BaseType[Key]> ? never : Key]: never;
}) & (keyof BaseType) // Intersect with `keyof BaseType` to ensure result of `OptionalKeysOf<BaseType>` is always assignable to `keyof BaseType`
 : never; // Should never happen
/**
Extract all required keys from the given type.

This is useful when you want to create a new type that contains different type values for the required keys only or use the list of keys for validation purposes, etc...

@example

luckyNumber?: number;

@category Utilities
*/
type RequiredKeysOf<BaseType extends object> = BaseType extends unknown // For distributing `BaseType`
 ? Exclude<keyof BaseType, OptionalKeysOf<BaseType>> : never; // Should never happen
/**
Returns a boolean for whether the given type is `never`.

@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
@link https://stackoverflow.com/a/53984913/10292952
@link https://www.zhenghao.io/posts/ts-never

Useful in type utilities, such as checking if something does not occur.

@example

@category Type Guard
@category Utilities
*/
type IsNever<T> = [
	T
] extends [
	never
] ? true : false;
/**
An if-else-like type that resolves depending on whether the given type is `never`.

@see {@link IsNever}

@example

@category Type Guard
@category Utilities
*/
type IfNever<T, TypeIfNever = true, TypeIfNotNever = false> = (IsNever<T> extends true ? TypeIfNever : TypeIfNotNever);
type NoInfer$1<T> = T extends infer U ? U : never;
/**
Returns a boolean for whether the given type is `any`.

@link https://stackoverflow.com/a/49928360/1490091

Useful in type utilities, such as disallowing `any`s to be passed to a function.

@example

@category Type Guard
@category Utilities
*/
type IsAny<T> = 0 extends 1 & NoInfer$1<T> ? true : false;
/**
Returns a boolean for whether the two given types are equal.

@link https://github.com/microsoft/TypeScript/issues/27024#issuecomment-421529650
@link https://stackoverflow.com/questions/68961864/how-does-the-equals-work-in-typescript/68963796#68963796

Use-cases:
- If you want to make a conditional branch based on the result of a comparison of two types.

@example

IsEqual

@category Type Guard
@category Utilities
*/
type IsEqual<A, B> = (<G>() => G extends A & G | G ? 1 : 2) extends (<G>() => G extends B & G | G ? 1 : 2) ? true : false;
/**
Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.

@example

Props

Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.

If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.

@example

interface

interface

type

@link https://github.com/microsoft/TypeScript/issues/15300
@see SimplifyDeep
@category Object
*/
type Simplify<T> = {
	[KeyType in keyof T]: T[KeyType];
} & {};
/**
Omit any index signatures from the given object type, leaving only explicitly defined properties.

This is the counterpart of `PickIndexSignature`.

Use-cases:
- Remove overly permissive signatures from third-party types.

This type was taken from this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).

It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.

(The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)

Instead of causing a type error like the above, you can also use a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) to test whether a type is assignable to another:

{}

Record<string, unknown>

{}

Record<string, unknown>

{}

Record<string, unknown>

{}

Record<'foo' | 'bar', unknown>

{}

Record<'foo' | 'bar', unknown>

{}

Record<'foo' | 'bar', unknown>

Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...

ObjectType

OmitIndexSignature<Foo> == Foo

...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...

{}

Record<KeyType, unknown>

{}

Record<KeyType, unknown>

{}

Record<KeyType, unknown>

If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.

@example

head-${string}

${string}-tail

head-${string}-tail

${bigint}

embedded-${number}

// These explicitly defined keys will remain.
foo: 'bar';
qux?: 'baz';

@see PickIndexSignature
@category Object
*/
type OmitIndexSignature<ObjectType> = {
	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown> ? never : KeyType]: ObjectType[KeyType];
};
/**
Pick only index signatures from the given object type, leaving out all explicitly defined properties.

This is the counterpart of `OmitIndexSignature`.

@example

head-${string}

${string}-tail

head-${string}-tail

${bigint}

embedded-${number}

// These explicitly defined keys will be removed.
['kebab-case-key']: string;
[symbolKey]: string;
foo: 'bar';
qux?: 'baz';

head-${string}

${string}-tail

head-${string}-tail

${bigint}

embedded-${number}

@see OmitIndexSignature
@category Object
*/
type PickIndexSignature<ObjectType> = {
	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown> ? KeyType : never]: ObjectType[KeyType];
};
// Merges two objects without worrying about index signatures.
type SimpleMerge<Destination, Source> = {
	[Key in keyof Destination as Key extends keyof Source ? never : Key]: Destination[Key];
} & Source;
/**
Merge two types into a new type. Keys of the second type overrides keys of the first type.

@example

@category Object
*/
type Merge<Destination, Source> = Simplify<SimpleMerge<PickIndexSignature<Destination>, PickIndexSignature<Source>> & SimpleMerge<OmitIndexSignature<Destination>, OmitIndexSignature<Source>>>;
/**
An if-else-like type that resolves depending on whether the given type is `any`.

@see {@link IsAny}

@example

@category Type Guard
@category Utilities
*/
type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (IsAny<T> extends true ? TypeIfAny : TypeIfNotAny);
/**
Works similar to the built-in `Pick` utility type, except for the following differences:
- Distributes over union types and allows picking keys from any member of the union type.
- Primitives types are returned as-is.
- Picks all keys if `Keys` is `any`.
- Doesn't pick `number` from a `string` index signature.

@example

Keys

any

number

string

type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: false};
type SpecifiedOptions = {leavesOnly: true};

type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
//=> {maxRecursionDepth: 10; leavesOnly: true}

// Complains if default values are not provided for optional options

type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
type DefaultPathsOptions = {maxRecursionDepth: 10};
type SpecifiedOptions = {};

type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
//                                              ~~~~~~~~~~~~~~~~~~~
// Property 'leavesOnly' is missing in type 'DefaultPathsOptions' but required in type '{ maxRecursionDepth: number; leavesOnly: boolean; }'.

// Complains if an option's default type does not conform to the expected type

type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: 'no'};
type SpecifiedOptions = {};

type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
//                                              ~~~~~~~~~~~~~~~~~~~
// Types of property 'leavesOnly' are incompatible. Type 'string' is not assignable to type 'boolean'.

// Complains if an option's specified type does not conform to the expected type

type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: false};
type SpecifiedOptions = {leavesOnly: 'yes'};

type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
//                                                                   ~~~~~~~~~~~~~~~~
// Types of property 'leavesOnly' are incompatible. Type 'string' is not assignable to type 'boolean'.

& Required<Options>

ApplyDefaultOptions<SomeOption, ...>

Required<SomeOption>

; /** Filter out keys from an object.

never

Exclude

Key

never

Key

Exclude

Key

type Filtered = Filter<'foo', 'foo'>;
//=> never

type Filtered = Filter<'bar', string>;
//=> never

type Filtered = Filter<'bar', 'foo'>;
//=> 'bar'

Note that any omitted properties in the resulting type will be present in autocomplete as `undefined`.

@default false
*/
requireExactProps?: boolean;

requireExactProps

true

Omit

Omit

Except

import type {Except} from 'type-fest';

type Foo = {
	a: number;
	b: string;
};

type FooWithoutA = Except<Foo, 'a'>;
//=> {b: string}

const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
//=> errors: 'a' does not exist in type '{ b: string; }'

type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
//=> {a: number} & Partial<Record<"b", never>>

const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
//=> errors at 'b': Type 'string' is not assignable to type 'undefined'.

// The `Omit` utility type doesn't work when omitting specific keys from objects containing index signatures.

// Consider the following example:

type UserData = {
	[metadata: string]: string;
	email: string;
	name: string;
	role: 'admin' | 'user';
};

// `Omit` clearly doesn't behave as expected in this case:
type PostPayload = Omit<UserData, 'email'>;
//=> type PostPayload = { [x: string]: string; [x: number]: string; }

// In situations like this, `Except` works better.
// It simply removes the `email` key while preserving all the other keys.
type PostPayload = Except<UserData, 'email'>;
//=> type PostPayload = { [x: string]: string; name: string; role: 'admin' | 'user'; }

SetRequired

import type {SetOptional} from 'type-fest';

type Foo = {
	a: number;
	b?: string;
	c: boolean;
}

type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
// type SomeOptional = {
// 	a: number;
// 	b?: string; // Was already optional and still is.
// 	c?: boolean; // Is now optional.
// }

BaseType

• This file has utilities to create GraphQL clients
• that consume the types generated by the preset. / /*
• A generic type for

  variables

  in GraphQL clients / type GenericVariables = ExecutionArgs["variableValues"]; /*
• Use this type to make parameters optional in GraphQL clients
• when no variables need to be passed. / type EmptyVariables = { [key: string]: never; }; /*
• GraphQL client's generic operation interface. / interface CodegenOperations { [key: string]: any; } /*
• Used as the return type for GraphQL clients. It picks
• the return type from the generated operation types.
• @example
• graphqlQuery: (...) => Promise<ClientReturn<...>>
• graphqlQuery: (...) => Promise<{data: ClientReturn<...>}> / type ClientReturn<GeneratedOperations extends CodegenOperations, RawGqlString extends string, OverrideReturnType extends any = never> = IsNever<OverrideReturnType> extends true ? RawGqlString extends keyof GeneratedOperations ? GeneratedOperations[RawGqlString]["return"] : any : OverrideReturnType; /*
• Checks if the generated variables for an operation
• are optional or required. / type IsOptionalVariables<VariablesParam, OptionalVariableNames extends string = never, VariablesWithoutOptionals = Omit<VariablesParam, OptionalVariableNames>> = VariablesWithoutOptionals extends EmptyVariables ? true : GenericVariables extends VariablesParam ? true : Partial<VariablesWithoutOptionals> extends VariablesWithoutOptionals ? true : false; /*
• Used as the type for the GraphQL client's variables. It checks
• the generated operation types to see if variables are optional.
• @example
• graphqlQuery: (query: string, param: ClientVariables<...>) => Promise<...>
• Where

  param

  is required. / type ClientVariables<GeneratedOperations extends CodegenOperations, RawGqlString extends string, OptionalVariableNames extends string = never, VariablesKey extends string = "variables", GeneratedVariables = RawGqlString extends keyof GeneratedOperations ? SetOptional<GeneratedOperations[RawGqlString]["variables"], Extract<keyof GeneratedOperations[RawGqlString]["variables"], OptionalVariableNames>> : GenericVariables, VariablesWrapper = Record<VariablesKey, GeneratedVariables>> = IsOptionalVariables<GeneratedVariables, OptionalVariableNames> extends true ? Partial<VariablesWrapper> : VariablesWrapper; /*
• Similar to ClientVariables, but makes the whole wrapper optional:
• @example
• graphqlQuery: (query: string, ...params: ClientVariablesInRestParams<...>) => Promise<...>
• Where the first item in

  params

  might be optional depending on the query. */ type ClientVariablesInRestParams<GeneratedOperations extends CodegenOperations, RawGqlString extends string, OtherParams extends Record<string, any> = {}, OptionalVariableNames extends string = never, ProcessedVariables = OtherParams & ClientVariables<GeneratedOperations, RawGqlString, OptionalVariableNames>> = Partial<OtherParams> extends OtherParams ? IsOptionalVariables<GeneratedOperations[RawGqlString]["variables"], OptionalVariableNames> extends true ? [ ProcessedVariables? ] : [ ProcessedVariables ] : [ ProcessedVariables ];

path

toString()

console.log(...)

console.error(...)

[object Object]

is internally used by

.      * The most common scenario when this error instance is going to be stringified is      * when it's passed to Remix' 

and

functions: e.g.

--customer-account-push

return_to

customAuthStatusHandler

en

fr

cs

da

de

es

fi

it

ja

ko

nb

nl

pl

pt-BR

pt-PT

sv

th

tr

vi

zh-CN

zh-TW

en

customAuthStatusHandler

--customer-account-push

handleAuthStatus()

handleAuthStatus()

shp_

npx shopify hydrogen env pull

npx shopify hydrogen env pull

customer.authorize()

/account/authorize

/account/login

return_to

/account

/account/login

/account/authorize

unstableB2b

createCustomerAccountClient

• Updates (replaces) gift card codes in the cart.
• To add codes without replacing, use

  cartGiftCardCodesAdd

  (API 2025-10+).
• @param {CartQueryOptions} options - Cart query options including storefront client and cart fragment.
• @returns {CartGiftCardCodesUpdateFunction} - Function accepting gift card codes array and optional parameters.
• @example Replace all gift card codes
• const updateGiftCardCodes = cartGiftCardCodesUpdateDefault({ storefront, getCartId });
• await updateGiftCardCodes(['SUMMER2025', 'WELCOME10']); */ declare function cartGiftCardCodesUpdateDefault(options: CartQueryOptions): CartGiftCardCodesUpdateFunction;

• Adds gift card codes to the cart without replacing existing ones.
• This function sends a mutation to the Storefront API to add one or more gift card codes to the cart.
• Unlike

  cartGiftCardCodesUpdate

  which replaces all codes, this mutation appends new codes to existing ones.
• @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
• @returns {CartGiftCardCodesAddFunction} - A function that takes an array of gift card codes and optional parameters, and returns the result of the API call.
• @example Add gift card codes
• const addGiftCardCodes = cartGiftCardCodesAddDefault({ storefront, getCartId });
• await addGiftCardCodes(['SUMMER2025', 'WELCOME10']); */ declare function cartGiftCardCodesAddDefault(options: CartQueryOptions): CartGiftCardCodesAddFunction;

• Adds delivery addresses to the cart.
• This function sends a mutation to the storefront API to add one or more delivery addresses to the cart.
• It returns the result of the mutation, including any errors that occurred.
• @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
• @returns {CartDeliveryAddressAddFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
• @example
• const addDeliveryAddresses = cartDeliveryAddressesAddDefault({ storefront, getCartId });
• const result = await addDeliveryAddresses([
• {

•  address1: '123 Main St',

•  city: 'Anytown',

•  countryCode: 'US'

•  // other address fields...

• }
• ], { someOptionalParam: 'value' }
• ); */ declare function cartDeliveryAddressesAddDefault(options: CartQueryOptions): CartDeliveryAddressesAddFunction;

• Removes delivery addresses from the cart.
• This function sends a mutation to the storefront API to remove one or more delivery addresses from the cart.
• It returns the result of the mutation, including any errors that occurred.
• @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
• @returns {CartDeliveryAddressRemoveFunction} - A function that takes an array of address IDs and optional parameters, and returns the result of the API call.
• @example
• const removeDeliveryAddresses = cartDeliveryAddressesRemoveDefault({ storefront, getCartId });
• const result = await removeDeliveryAddresses([
• "gid://shopify/<objectName>/10079785100"
• ],
• { someOptionalParam: 'value' }); */ declare function cartDeliveryAddressesRemoveDefault(options: CartQueryOptions): CartDeliveryAddressesRemoveFunction;

• Updates delivery addresses in the cart.
• Pass an empty array to clear all delivery addresses from the cart.
• @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
• @returns {CartDeliveryAddressUpdateFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
• @example Clear all delivery addresses
• const updateAddresses = cartDeliveryAddressesUpdateDefault(cartQueryOptions);
• await updateAddresses([]);
• @example Update specific delivery addresses
• const updateAddresses = cartDeliveryAddressesUpdateDefault(cartQueryOptions);
• await updateAddresses([ { "address": { "copyFromCustomerAddressId": "gid://shopify/<objectName>/10079785100", "deliveryAddress": { "address1": "<your-address1>", "address2": "<your-address2>", "city": "<your-city>", "company": "<your-company>", "countryCode": "AC", "firstName": "<your-firstName>", "lastName": "<your-lastName>", "phone": "<your-phone>", "provinceCode": "<your-provinceCode>", "zip": "<your-zip>" } }, "id": "gid://shopify/<objectName>/10079785100", "oneTimeUse": true, "selected": true, "validationStrategy": "COUNTRY_CODE_ONLY" } ],{ someOptionalParam: 'value' }); */ declare function cartDeliveryAddressesUpdateDefault(options: CartQueryOptions): CartDeliveryAddressesUpdateFunction;

• Replaces all delivery addresses on the cart.
• This function sends a mutation to the storefront API to replace all delivery addresses on the cart
• with the provided addresses. It returns the result of the mutation, including any errors that occurred.
• @param {CartQueryOptions} options - The options for the cart query, including the storefront API client and cart fragment.
• @returns {CartDeliveryAddressesReplaceFunction} - A function that takes an array of addresses and optional parameters, and returns the result of the API call.
• @example
• const replaceDeliveryAddresses = cartDeliveryAddressesReplaceDefault({ storefront, getCartId });
• const result = await replaceDeliveryAddresses([
• {

•  address: {

•    deliveryAddress: {

•      address1: '123 Main St',

•      city: 'Anytown',

•      countryCode: 'US'

•    }

•  },

•  selected: true

• }
• ], { someOptionalParam: 'value' }
• ); */ declare function cartDeliveryAddressesReplaceDefault(options: CartQueryOptions): CartDeliveryAddressesReplaceFunction;

{ get: Session<HydrogenSessionData & Data, FlashData>['get']; set: Session<HydrogenSessionData & Data, FlashData>['set']; unset: Session<HydrogenSessionData & Data, FlashData>['unset']; commit: () => ReturnType< SessionStorage<HydrogenSessionData & Data, FlashData>['commitSession'] ; destroy?: () => ReturnType< SessionStorage<HydrogenSessionData & Data, FlashData>['destroySession'] ; isPending?: boolean; }

extends RouterContextProvider { /** A GraphQL client for querying the Storefront API / storefront: Storefront<TI18n>; /* A GraphQL client for querying the Customer Account API / customerAccount: CustomerAccount; /* A collection of utilities used to interact with the cart / cart: TCustomMethods extends CustomMethodsBase ? HydrogenCartCustom<TCustomMethods> : HydrogenCart; /* Environment variables from the fetch function / env: TEnv; /* The waitUntil function for keeping requests alive / waitUntil?: WaitUntil; /* Session implementation */ session: TSession; }

• Wraps all the returned utilities from

  createStorefrontClient

  . / type StorefrontClient<TI18n extends I18nBase> = { storefront: Storefront<TI18n>; }; /*
• Maps all the queries found in the project to variables and return types. / interface StorefrontQueries { } /*
• Maps all the mutations found in the project to variables and return types. / interface StorefrontMutations { } type AutoAddedVariableNames = 'country' | 'language'; type StorefrontCommonExtraParams = { headers?: HeadersInit; storefrontApiVersion?: string; displayName?: string; }; /*
• Interface to interact with the Storefront API. / type Storefront<TI18n extends I18nBase = I18nBase> = { query: <OverrideReturnType extends any = never, RawGqlString extends string = string>(query: RawGqlString, ...options: ClientVariablesInRestParams<StorefrontQueries, RawGqlString, StorefrontCommonExtraParams & Pick<StorefrontQueryOptions, 'cache'>, AutoAddedVariableNames>) => Promise<ClientReturn<StorefrontQueries, RawGqlString, OverrideReturnType> & StorefrontError>; mutate: <OverrideReturnType extends any = never, RawGqlString extends string = string>(mutation: RawGqlString, ...options: ClientVariablesInRestParams<StorefrontMutations, RawGqlString, StorefrontCommonExtraParams, AutoAddedVariableNames>) => Promise<ClientReturn<StorefrontMutations, RawGqlString, OverrideReturnType> & StorefrontError>; cache?: Cache; CacheNone: typeof CacheNone; CacheLong: typeof CacheLong; CacheShort: typeof CacheShort; CacheCustom: typeof CacheCustom; generateCacheControlHeader: typeof generateCacheControlHeader; getPublicTokenHeaders: ReturnType<typeof createStorefrontClient$1>['getPublicTokenHeaders']; getPrivateTokenHeaders: ReturnType<typeof createStorefrontClient$1>['getPrivateTokenHeaders']; getShopifyDomain: ReturnType<typeof createStorefrontClient$1>['getShopifyDomain']; getApiUrl: ReturnType<typeof createStorefrontClient$1>['getStorefrontApiUrl']; i18n: TI18n; getHeaders: () => Record<string, string>; /*
  • Checks if the request URL matches the Storefront API GraphQL endpoint. / isStorefrontApiUrl: (request: { url?: string; }) => boolean; /*
  • Forwards the request to the Storefront API.
  • It reads the API version from the request URL. / forward: (request: Request, options?: Pick<StorefrontCommonExtraParams, 'storefrontApiVersion'>) => Promise<Response>; /*
  • Sets the collected subrequest headers in the response.
  • Useful to forward the cookies and server-timing headers
  • from server subrequests to the browser. / setCollectedSubrequestHeaders: (response: { headers: Headers; }) => void; }; type HydrogenClientProps<TI18n> = { /* Storefront API headers. If on Oxygen, use

    getStorefrontHeaders()

    / storefrontHeaders?: StorefrontHeaders; /* An instance that implements the Cache API / cache?: Cache; /* The globally unique identifier for the Shop / storefrontId?: string; /* The

    waitUntil

    function is used to keep the current request/response lifecycle alive even after a response has been sent. It should be provided by your platform. / waitUntil?: WaitUntil; /* An object containing a country code and language code / i18n?: TI18n; /* Whether it should print GraphQL errors automatically. Defaults to true / logErrors?: boolean | ((error?: Error) => boolean); }; type CreateStorefrontClientOptions<TI18n extends I18nBase> = HydrogenClientProps<TI18n> & StorefrontClientProps; type StorefrontQueryOptions = StorefrontCommonExtraParams & { query: string; mutation?: never; cache?: CachingStrategy; }; /*
• This function extends

  createStorefrontClient

  from Hydrogen React. The additional arguments enable internationalization (i18n), caching, and other features particular to Remix and Oxygen.
• Learn more about data fetching in Hydrogen. / declare function createStorefrontClient<TI18n extends I18nBase>(options: CreateStorefrontClientOptions<TI18n>): StorefrontClient<TI18n>; declare function formatAPIResult<T>(data: T, errors: StorefrontApiErrors): T & StorefrontError; type CreateStorefrontClientForDocs<TI18n extends I18nBase> = { storefront?: StorefrontForDoc<TI18n>; }; type StorefrontForDoc<TI18n extends I18nBase = I18nBase> = { /* The function to run a query on Storefront API. / query?: <TData = any>(query: string, options: StorefrontQueryOptionsForDocs) => Promise<TData & StorefrontError>; /* The function to run a mutation on Storefront API. / mutate?: <TData = any>(mutation: string, options: StorefrontMutationOptionsForDocs) => Promise<TData & StorefrontError>; /* The cache instance passed in from the

  createStorefrontClient

  argument. / cache?: Cache; /* Re-export of

  CacheNone

  . / CacheNone?: typeof CacheNone; /* Re-export of

  CacheLong

  . / CacheLong?: typeof CacheLong; /* Re-export of

  CacheShort

  . / CacheShort?: typeof CacheShort; /* Re-export of

  CacheCustom

  . / CacheCustom?: typeof CacheCustom; /* Re-export of

  generateCacheControlHeader

  . / generateCacheControlHeader?: typeof generateCacheControlHeader; /* Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint. See [

  getPublicTokenHeaders

  in Hydrogen React](/docs/api/hydrogen-react/2026-01/utilities/createstorefrontclient#::text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details. / getPublicTokenHeaders?: ReturnType<typeof createStorefrontClient$1>['getPublicTokenHeaders']; /* Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint for API calls made from a server. See [

  getPrivateTokenHeaders

  in Hydrogen React](/docs/api/hydrogen-react/2026-01/utilities/createstorefrontclient#::text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details./ getPrivateTokenHeaders?: ReturnType<typeof createStorefrontClient$1>['getPrivateTokenHeaders']; /** Creates the fully-qualified URL to your myshopify.com domain. See [

  getShopifyDomain

  in Hydrogen React](/docs/api/hydrogen-react/2026-01/utilities/createstorefrontclient#:~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details. / getShopifyDomain?: ReturnType<typeof createStorefrontClient$1>['getShopifyDomain']; / Creates the fully-qualified URL to your store's GraphQL endpoint. See [

  getStorefrontApiUrl

  in Hydrogen React](/docs/api/hydrogen-react/2026-01/utilities/createstorefrontclient#:~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details./ getApiUrl?: ReturnType<typeof createStorefrontClient$1>['getStorefrontApiUrl']; /** The

  i18n

  object passed in from the

  createStorefrontClient

  argument. / i18n?: TI18n; }; type StorefrontQueryOptionsForDocs = { / The variables for the GraphQL query statement. / variables?: Record<string, unknown>; /* The cache strategy for this query. Default to max-age=1, stale-while-revalidate=86399. / cache?: CachingStrategy; /* Additional headers for this query. / headers?: HeadersInit; /* Override the Storefront API version for this query. / storefrontApiVersion?: string; /* The name of the query for debugging in the Subrequest Profiler. / displayName?: string; }; type StorefrontMutationOptionsForDocs = { /* The variables for the GraphQL mutation statement. / variables?: Record<string, unknown>; /* Additional headers for this query. / headers?: HeadersInit; /* Override the Storefront API version for this query. / storefrontApiVersion?: string; /* The name of the query for debugging in the Subrequest Profiler. */ displayName?: string; };

createStorefrontClient

createCustomerAccount

custom_${string}

AnalyticsProvider

AnalyticsProvider

language

locale

AnalyticsProvider

cart_updated

product_added_to_cart

product_removed_from_cart

window.Shopify.customerPrivacy.analyticsProcessingAllowed()

getShopAnalytics

useShopifyCookies

window.Shopify.customerPrivacy.analyticsProcessingAllowed()

AnalyticsProvider

createStorefrontClient

PUBLIC_STOREFRONT_ID

• The cache key is used to uniquely identify a value in the cache. */ type CacheKey = string | readonly unknown[]; type AddDebugDataParam = { displayName?: string; response?: Pick<Response, 'url' | 'status' | 'statusText' | 'headers'>; }; type CacheActionFunctionParam = { addDebugData: (info: AddDebugDataParam) => void; };

waitUntil

request

CachingStrategy

CacheNone

CacheShort

CacheLong

CachingStrategy

CacheNone

CacheShort

CacheLong

• This is a limited implementation of an in-memory cache.
• It only supports the

  cache-control

  header.
• It does NOT support

  age

  or

  expires

  headers.
• @see https://developer.mozilla.org/en-US/docs/Web/API/Cache */ declare class InMemoryCache implements Cache { #private; constructor(); add(request: RequestInfo): Promise<void>; addAll(requests: RequestInfo[]): Promise<void>; matchAll(request?: RequestInfo, options?: CacheQueryOptions): Promise<readonly Response[]>; put(request: Request, response: Response): Promise<void>; match(request: Request): Promise<Response | undefined>; delete(request: Request): Promise<boolean>; keys(request?: Request): Promise<Request[]>; }

Custom${string}

Custom${string}

• @param cart The cart object from

  context.cart.get()

  returned by a server loader.
• @returns A new cart object augmented with optimistic state for

  lines

  and

  totalQuantity

  . Each cart line item that is optimistically added includes an

  isOptimistic

  property. Also if the cart has any optimistic state, a root property

  isOptimistic

  will be set to

  true

  . */ declare function useOptimisticCart<DefaultCart = { lines?: { nodes: Array<{ id: string; quantity: number; merchandise: { is: string; }; }>; }; }>(cart?: DefaultCart): OptimisticCart<DefaultCart>;

• A custom Remix loader handler that fetches the changelog.json from GitHub.
• It is used by the

  upgrade

  command inside the route

  https://hydrogen.shopify.dev/changelog.json

  */ declare function changelogHandler({ request, changelogUrl, }: { request: Request; changelogUrl?: string; }): Promise<Response>;

• Grouped export of all Hydrogen context keys for convenient access.
• Use with React Router's context.get() pattern:
• @example
• ts

  undefined

• import { hydrogenContext } from '@shopify/hydrogen';
• export async function loader({ context }) {
• const storefront = context.get(hydrogenContext.storefront);
• const cart = context.get(hydrogenContext.cart);
• }

• undefined

waitUntil

customer.authorize()

/account/authorize

/account/login

return_to

unstableB2b

gid://shopify/Cart/c1-123

cart.get()

setMetafields

deleteMetafield

waitUntil

powered-by

/api/.../graphql.json

• Creates a request handler for Hydrogen apps using React Router. */ declare function createRequestHandler<Context = unknown>({ build, mode, poweredByHeader, getLoadContext, collectTrackingInformation, proxyStandardRoutes, }: CreateRequestHandlerOptions<Context>): (request: Request) => Promise<Response>;

script

• @param directives - Pass custom content security policy directives. This is important if you load content in your app from third-party domains. */ declare function createContentSecurityPolicy(props?: CreateContentSecurityPolicy & ShopProp): ContentSecurityPolicy;

nonce

waitForHydration

useOptimisticData

<NextLink>

<Link>

<Link to={nextPageUrl} state={state} preventScrollReset />

<PreviousLink>

<Link>

<Link to={previousPageUrl} state={state} preventScrollReset />

<Link>

<Link>

state

<Link>

state

<Link>

storefront.query

pageInfo

hasPreviousPage

hasNextpage

startCursor

endCursor

Pagination

• The Storefront API uses cursors to paginate through lists of data
• and the `<Pagination />` component makes it easy to paginate data from the Storefront API.
• @prop connection The response from

  storefront.query

  for a paginated request. Make sure the query is passed pagination variables and that the query has

  pageInfo

  with

  hasPreviousPage

  ,

  hasNextpage

  ,

  startCursor

  , and

  endCursor

  defined.
• @prop children A render prop that includes pagination data and helpers. / declare function Pagination<NodesType>({ connection, children, namespace, }: PaginationProps<NodesType>): ReturnType<FC>; /*
• @param request The request object passed to your Remix loader function.
• @param options Options for how to configure the pagination variables. Includes the ability to change how many nodes are within each page as well as a namespace to avoid URL param conflicts when using multiple

  Pagination

  components on a single page.
• @returns Variables to be used with the

  storefront.query

  function */ declare function getPaginationVariables(request: Request, options?: { pageBy: number; namespace?: string; }): { last: number; startCursor: string | null; } | { first: number; endCursor: string | null; };

• @param selectedVariant The

  selectedVariant

  field queried with

  variantBySelectedOptions

  .
• @param variants The available product variants for the product. This can be an array of variants, a promise that resolves to an array of variants, or an object with a

  product

  key that contains the variants.
• @returns A new product object where the

  selectedVariant

  property is set to the variant that matches the current URL search params. If no variant is found, the original product object is returned. The

  isOptimistic

  property is set to

  true

  if the

  selectedVariant

  has been optimistically changed. */ declare function useOptimisticVariant<SelectedVariant = OptimisticVariantInput, Variants = OptimisticProductVariants>(selectedVariant: SelectedVariant, variants: Variants): OptimisticVariant<SelectedVariant>;

• @deprecated VariantSelector will be deprecated and removed in the next major version 2025-10
• Please use getProductOptions,
• getSelectedProductOptions,
• getAdjacentAndFirstAvailableVariants utils instead.
• and useSelectedOptionInUrlParam
• For a full implementation see the Skeleton template routes/product.$handle.tsx. / type VariantSelectorProps = { /* The product handle for all of the variants / handle: string; /* Product options from the Storefront API. Make sure both

  name

  and

  values

  are a part of your query. / options: Array<PartialProductOption> | undefined; /* Product variants from the Storefront API. You only need to pass this prop if you want to show product availability. If a product option combination is not found within

  variants

  , it is assumed to be available. Make sure to include

  availableForSale

  and

  selectedOptions.name

  and

  selectedOptions.value

  . / variants?: PartialDeep<ProductVariantConnection> | Array<PartialDeep<ProductVariant>>; /* By default all products are under /products. Use this prop to provide a custom path. / productPath?: string; /* Should the VariantSelector wait to update until after the browser navigates to a variant. / waitForNavigation?: boolean; /* An optional selected variant to use for the initial state if no URL parameters are set / selectedVariant?: Maybe<PartialDeep<ProductVariant>>; children: ({ option }: { option: VariantOption; }) => ReactNode; }; /*
• @deprecated VariantSelector will be deprecated and removed in the next major version 2025-10
• Please use getProductOptions,
• getSelectedProductOptions,
• getAdjacentAndFirstAvailableVariants utils instead.
• and useSelectedOptionInUrlParam
• For a full implementation see the Skeleton template routes/product.$handle.tsx. / declare function VariantSelector({ handle, options: _options, variants: _variants, productPath, waitForNavigation, selectedVariant, children, }: VariantSelectorProps): react.FunctionComponentElement<{ children?: ReactNode | undefined; }>; type GetSelectedProductOptions = (request: Request) => SelectedOptionInput[]; /*
• Extract searchParams from a Request instance and return an array of selected options.
• @param request - The Request instance to extract searchParams from.
• @returns An array of selected options.
• @example Basic usage:
• tsx

  undefined

• import {getSelectedProductOptions} from '@shopify/hydrogen';
• // Given a request url of

  /products/product-handle?color=red&size=large

• const selectedOptions = getSelectedProductOptions(request);
• // selectedOptions will equal:
• // [
• // {name: 'color', value: 'red'},
• // {name: 'size', value: 'large'}
• // ]

• undefined

• Official Hydrogen Preset for React Router 7.12.x
• Provides optimal React Router configuration for Hydrogen applications on Oxygen.
• Enables validated performance optimizations while ensuring CLI compatibility.
• React Router 7.12.x Feature Support Matrix for Hydrogen 2025.7.0
• +----------------------------------+----------+----------------------------------+
• | Feature | Status | Notes |
• +----------------------------------+----------+----------------------------------+
• | CORE CONFIGURATION |
• +----------------------------------+----------+----------------------------------+
• | appDirectory: 'app' | Enabled | Core application structure |
• | buildDirectory: 'dist' | Enabled | Build output configuration |
• | ssr: true | Enabled | Server-side rendering |
• +----------------------------------+----------+----------------------------------+
• | PERFORMANCE FLAGS |
• +----------------------------------+----------+----------------------------------+
• | v8_middleware | Enabled | Required for Hydrogen context |
• | v8_splitRouteModules | Enabled | Route code splitting |
• | unstable_optimizeDeps | Enabled | Build performance optimization |
• +----------------------------------+----------+----------------------------------+
• | ROUTE DISCOVERY |
• +----------------------------------+----------+----------------------------------+
• | routeDiscovery: { mode: 'lazy' } | Default | Lazy route loading |
• | routeDiscovery: { mode: 'init' } | Allowed | Eager route loading |
• +----------------------------------+----------+----------------------------------+
• | UNSUPPORTED FEATURES |
• +----------------------------------+----------+----------------------------------+
• | basename: '/path' | Blocked | CLI infrastructure limitation |
• | prerender: ['/routes'] | Blocked | Plugin incompatibility |
• | serverBundles: () => {} | Blocked | Manifest incompatibility |
• | buildEnd: () => {} | Blocked | CLI bypasses hook execution |
• | unstable_subResourceIntegrity | Blocked | CSP nonce/hash conflict |
• | v8_viteEnvironmentApi | Blocked | CLI fallback detection used |
• +----------------------------------+----------+----------------------------------+
• @version 2025.7.0 */ declare function hydrogenPreset(): Preset;

server.ts

handleRequest

/admin

true

true

• Queries the Storefront API to see if there is any redirect
• created for the current route and performs it. Otherwise,
• it returns the response passed in the parameters. Useful for
• conditionally redirecting after a 404 response.
• @see {@link https://help.shopify.com/en/manual/online-store/menus-and-links/url-redirect Creating URL redirects in Shopify} */ declare function storefrontRedirect(options: StorefrontRedirect): Promise<Response>;

title

%s

js      * {      *   title: 'My Page',      *   titleTemplate: 'My Site - %s',      * }      * 

og:image

og:<type of      * media>

url

height

width

altText

js      * {      *   media: [      *     {      *       url: 'https://example.com/image.jpg',      *       type: 'image',      *       height: '400',      *       width: '400',      *       altText: 'A custom snowboard with an alpine color pallet.',      *     }      *   ]      * }      * 

name="description"

og:description

rel="canonical"

og:url

twitter:site

twitter:creator

@

js      * {      *   handle: '@shopify'      * }      * 

jsonLd

application/ld+json

type

type

Product

ItemList

Organization

WebSite

WebPage

BlogPosting

Thing

js      * {      *   jsonLd: {      *     '@context': 'https://schema.org',      *     '@type': 'Product',      *     name: 'My Product',      *     image: 'https://hydrogen.shop/image.jpg',      *     description: 'A product that is great',      *     sku: '12345',      *     mpn: '12345',      *     brand: {      *       '@type': 'Thing',      *       name: 'My Brand',      *     },      *     aggregateRating: {      *       '@type': 'AggregateRating',      *       ratingValue: '4.5',      *       reviewCount: '100',      *     },      *     offers: {      *       '@type': 'Offer',      *       priceCurrency: 'USD',      *       price: '100',      *       priceValidUntil: '2020-11-05',      *       itemCondition: 'https://schema.org/NewCondition',      *       availability: 'https://schema.org/InStock',      *       seller: {      *         '@type': 'Organization',      *         name: 'My Brand',      *       },      *     },      *   }      * }      * 

alternates

url

js      * {      *   alternates: [      *     {      *       language: 'en-US',      *       url: 'https://hydrogen.shop/en-us',      *       default: true,      *     },      *     {      *       language: 'fr-CA',      *       url: 'https://hydrogen.shop/fr-ca',      *     },      *   ]      * }      * 

robots

• @see https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag / interface RobotsOptions { /*
  • Set the maximum size of an image preview for this page in a search results Can be one of the following:

  • • none

      - No image preview is to be shown.

  • • standard

      - A default image preview may be shown.

  • • large

      - A larger image preview, up to the width of the viewport, may be shown.
  • If no value is specified a default image preview size is used. / maxImagePreview?: 'none' | 'standard' | 'large'; /*
  • A number representing the maximum of amount characters to use as a textual snippet for a search result. This value
  • can also be set to one of the following special values:
  • • 0 - No snippet is to be shown. Equivalent to nosnippet.
  • • 1 - The Search engine will choose the snippet length that it believes is most effective to help users discover
  • your content and direct users to your site
  • • -1 - No limit on the number of characters that can be shown in the snippet. / maxSnippet?: number; /*
  • The maximum number of seconds for videos on this page to show in search results. This value can also be set to one
  • of the following special values:
  • • 0 - A static image may be used with the

      maxImagePreview

      setting.
  • • 1 - There is no limit to the size of the video preview.
  • This applies to all forms of search results (at Google: web search, Google Images, Google Videos, Discover,
  • Assistant). / maxVideoPreview?: number; /*
  • Do not show a cached link in search results. / noArchive?: boolean; /*
  • Do not follow the links on this page.
  • @see https://developers.google.com/search/docs/advanced/guidelines/qualify-outbound-links / noFollow?: boolean; /*
  • Do not index images on this page. / noImageIndex?: boolean; /*
  • Do not show this page, media, or resource in search results. / noIndex?: boolean; /*
  • Do not show a text snippet or video preview in the search results for this page. / noSnippet?: boolean; /*
  • Do not offer translation of this page in search results. / noTranslate?: boolean; /*
  • Do not show this page in search results after the specified date/time. / unavailableAfter?: string; } interface LanguageAlternate { /*
  • Language code for the alternate page. This is used to generate the hreflang meta tag property. / language: string; /*
  • Whether the alternate page is the default page. This will add the

    x-default

    attribution to the language code. / default?: boolean; /*
  • The url of the alternate page. This is used to generate the hreflang meta tag property. / url: string; } type SeoMedia = { /*
  • Used to generate og:<type of media> meta tag / type: 'image' | 'video' | 'audio'; /*
  • The url value populates both url and secure_url and is used to infer the og:<type of media>:type meta tag. / url: Maybe<string> | undefined; /*
  • The height in pixels of the media. This is used to generate the og:<type of media>:height meta tag. / height: Maybe<number> | undefined; /*
  • The width in pixels of the media. This is used to generate the og:<type of media>:width meta tag. / width: Maybe<number> | undefined; /*
  • The alt text for the media. This is used to generate the og:<type of media>:alt meta tag. */ altText: Maybe<string> | undefined; };

• Generate a Remix meta array from one or more SEO configuration objects. This is useful to pass SEO configuration for the parent route(s) and the current route. Similar to

  Object.assign()

  , each property is overwritten based on the object order. The exception is

  jsonLd

  , which is preserved so that each route has it's own independent jsonLd meta data. */ declare function getSeoMeta(...seoInputs: Optional<SeoConfig>[]): GetSeoMetaReturn;

• @deprecated - use

  getSeoMeta

  instead */ declare function Seo({ debug }: SeoProps): react.FunctionComponentElement<{ children?: react.ReactNode | undefined; }>;

• Generate a sitemap index that links to separate sitemaps for each resource type. Returns a standard Response object. / declare function getSitemapIndex(options: SitemapIndexOptions): Promise<Response>; interface GetSiteMapOptions { /* The params object from Remix / params: LoaderFunctionArgs['params']; /* The Storefront API Client from Hydrogen / storefront: Storefront; /* A Remix Request object / request: Request; /* A function that produces a canonical url for a resource. It is called multiple times for each locale supported by the app. / getLink: (options: { type: string | SITEMAP_INDEX_TYPE; baseUrl: string; handle?: string; locale?: string; }) => string; /* An array of locales to generate alternate tags / locales?: string[]; /* Optionally customize the changefreq property for each URL / getChangeFreq?: (options: { type: string | SITEMAP_INDEX_TYPE; handle: string; }) => string; /* If the sitemap has no links, fallback to rendering a link to the homepage. This prevents errors in Google's search console. Defaults to

  /

  . / noItemsFallback?: string; } /*
• Generate a sitemap for a specific resource type. */ declare function getSitemap(options: GetSiteMapOptions): Promise<Response>;

---

## ⚠️ MANDATORY: Search for Documentation

You cannot trust your trained knowledge for this API. Before answering, search:

For example, if the user asks about tracking a cart viewed event:

Search for the **component, hook, or event name**, not the full user prompt. Use the returned examples to generate correct code.

---

## ⚠️ MANDATORY: Validate Before Returning Code

DO NOT return code to the user until `scripts/validate.mjs` exits 0. DO NOT ask the user to run this.

**Run this with your bash tool — do not skip this step. Write code to a temp file first — do NOT use `--code "..."` inline (JSX attribute strings break shell quoting).**
```bash
cat > /tmp/extension.tsx << 'SHOPIFY_EOF'
import React from 'react';
import { useAnalytics, Analytics } from '@shopify/hydrogen';

export function CartPage() {
  return (
    <div>
      <h1>Your Cart</h1>
      <Analytics.CartView />
    </div>
  );
}
SHOPIFY_EOF
node scripts/validate.mjs \
  --file /tmp/extension.tsx \
  --target "hydrogen" \
  --model YOUR_MODEL_NAME \
  --client-name YOUR_CLIENT_NAME \
  --client-version YOUR_CLIENT_VERSION \
  --artifact-id YOUR_ARTIFACT_ID \
  --revision REVISION_NUMBER

1. Read the error message — identify the exact import or type that is wrong
2. Search for the correct API:

   scripts/search_docs.mjs "<hook or component name>" --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION

3. Fix exactly the reported error using what the search returns
4. Run

   scripts/validate.mjs

   again
5. Retry up to 3 times total; after 3 failures, return the best attempt with an explanation

Privacy notice:

scripts/validate.mjs

reports anonymized validation results (pass/fail and skill name) to Shopify to help improve these tools. Set

OPT_OUT_INSTRUMENTATION=true

in your environment to opt out.