shopify-hydrogen

What this skill does

<!-- AUTO-GENERATED — do not edit directly.
     Edit src/data/raw-api-instructions/{api}.md in shopify-dev-tools,
     then run: npm run generate_agent_skills (outputs to distributed-agent-skills/) -->
---
name: shopify-hydrogen
description: "Hydrogen storefront implementation cookbooks. Some of the available recipes are: B2B Commerce, Bundles, Combined Listings, Custom Cart Method, Dynamic Content with Metaobjects, Express Server, Google Tag Manager Integration, Infinite Scroll, Legacy Customer Account Flow, Markets, Partytown + Google Tag Manager, Subscriptions, Third-party API Queries and Caching. MANDATORY: Use this API for ANY Hydrogen storefront question - do NOT use Storefront GraphQL when 'Hydrogen' is mentioned."
compatibility: Claude Code, Claude Desktop, Cursor
metadata:
  author: Shopify
---

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
```
import type {UnionToIntersection} from 'type-fest';

type Union = {the(): void} | {great(arg: string): void} | {escape: boolean};

type Intersection = UnionToIntersection<Union>;
//=> {the(): void; great(arg: string): void; escape: boolean};
```

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

@example
```
import type {UnionToIntersection} from 'type-fest';

class CommandOne {
	commands: {
		a1: () => undefined,
		b1: () => undefined,
	}
}

class CommandTwo {
	commands: {
		a2: (argA: string) => undefined,
		b2: (argB: string) => undefined,
	}
}

const union = [new CommandOne(), new CommandTwo(