git:20260326.0dd80de to git:20260409.42c2ef2

- description: "Core Shopify Hydrogen APIs — createHydrogenContext, cart handler, CartForm, caching strategies, pagination, SEO, variant selection, analytics, and CSP. Based on source at github.com/Shopify/hydrogen."

- ---

- ## createHydrogenContext

- The recommended single entry point to set up all Hydrogen services in `server.ts`. Creates and wires together `storefront`, `customerAccount`, and `cart`.

- ```ts

- import {createHydrogenContext} from '@shopify/hydrogen'

- export async function createAppLoadContext(request, env, executionContext) {

- const hydrogenContext = createHydrogenContext({

- env,

- request,

- cache: await caches.open('hydrogen'),

- waitUntil: executionContext.waitUntil.bind(executionContext),

- session,

- i18n: {language: 'EN', country: 'US'},

- // Optional overrides:

- storefront: {apiVersion: '2026-01'},

- customerAccount: {authUrl: '/account/authorize'},

- cart: {

- queryFragment: CUSTOM_CART_FRAGMENT,

- mutateFragment: CUSTOM_MUTATE_FRAGMENT,

- customMethods: {},

- },

- })

- return {...hydrogenContext}

- }

- **Required env vars:**

- - `PUBLIC_STORE_DOMAIN`

- - `PUBLIC_STOREFRONT_API_TOKEN`

- - `PRIVATE_STOREFRONT_API_TOKEN`

- - `PUBLIC_STOREFRONT_ID`

- - `PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID`

- - `SHOP_ID`

- **Returns:** `{ storefront, customerAccount, cart }` — plus React Router context provider.

- See [references/01-setup.md](references/01-setup.md).

- ---

- ## Caching

- ```ts

- import {CacheNone, CacheShort, CacheLong, CacheCustom, generateCacheControlHeader} from '@shopify/hydrogen'

- ```

- | Strategy | `maxAge` | `staleWhileRevalidate` | Use for |

- |----------|----------|------------------------|---------|

- | `CacheLong()` | 1hr (3600s) | 23hr (82800s) | Stable data (shop info, menus) |

- ```ts

- const {product} = await storefront.query(PRODUCT_QUERY, {

- variables: {handle},

- cache: CacheShort(),

- })

- ```

-

- All strategies accept optional override options. `mode` must be `'public'` or `'private'` — any other value throws.

-

- ```ts

- // Generate a Cache-Control header string manually:

- const header = generateCacheControlHeader({

- mode: 'public',

- maxAge: 60,

- staleWhileRevalidate: 3600,

- })

- // → 'public, max-age=60, stale-while-revalidate=3600'

- ```

-

- See [references/02-caching.md](references/02-caching.md).

-

- ---

-

- ## Cart

-

- ### createCartHandler

-

- ```ts

- import {createCartHandler, cartGetIdDefault, cartSetIdDefault} from '@shopify/hydrogen'

-

- const cart = createCartHandler({

- storefront,

- customerAccount,

- getCartId: cartGetIdDefault(request.headers),

- setCartId: cartSetIdDefault(),

- cartQueryFragment: CUSTOM_CART_FRAGMENT, // optional

- cartMutateFragment: CUSTOM_MUTATE_FRAGMENT, // optional

- customMethods: {}, // optional

- })

- ```

-

- **All cart methods:**

- | Method | Description |

- |--------|-------------|

- | `cart.get()` | Fetch current cart |

- | `cart.create(input)` | Create a new cart |

- | `cart.addLines(lines)` | Add items (creates cart if needed) |

- | `cart.updateLines(lines)` | Update line quantities |

- | `cart.removeLines(lineIds)` | Remove lines |

- | `cart.updateDiscountCodes(codes)` | Apply/remove discount codes |

- | `cart.addGiftCardCodes(codes)` | Add gift card codes |

- | `cart.updateGiftCardCodes(codes)` | Update gift card codes |

- | `cart.removeGiftCardCodes(codes)` | Remove gift card codes |

- | `cart.updateBuyerIdentity(identity)` | Update buyer info |

- | `cart.updateNote(note)` | Update cart note |

- | `cart.updateAttributes(attributes)` | Update cart attributes |

- | `cart.updateSelectedDeliveryOption(input)` | Update delivery option |

- | `cart.setMetafields(metafields)` | Add/update metafields |

- | `cart.deleteMetafield(metafield)` | Delete a metafield |

- | `cart.addDeliveryAddresses(addresses)` | Add delivery addresses |

- | `cart.removeDeliveryAddresses(addressIds)` | Remove delivery addresses |

- | `cart.updateDeliveryAddresses(addresses)` | Update delivery addresses |

- | `cart.replaceDeliveryAddresses(addresses)` | Replace all delivery addresses |

- Form component for cart mutations. Submits to a route action via React Router's `useFetcher`.

-

- ```tsx

- import {CartForm} from '@shopify/hydrogen'

-

- <CartForm

- route="/cart"

- action={CartForm.ACTIONS.LinesAdd}

- inputs={{lines: [{merchandiseId: variantId, quantity: 1}]}}

- >

- {(fetcher) => (

- <button type="submit" disabled={fetcher.state !== 'idle'}>

- Add to cart

- </button>

- )}

- </CartForm>

- ```

-

- **All `CartForm.ACTIONS`:**

-

- | Action | inputs required |

- |--------|----------------|

- | `LinesAdd` | `lines: OptimisticCartLineInput[]` |

- | `LinesUpdate` | `lines: CartLineUpdateInput[]` |

- | `LinesRemove` | `lineIds: string[]` |

- | `DiscountCodesUpdate` | `discountCodes: string[]` |

- | `GiftCardCodesAdd` | `giftCardCodes: string[]` |

- | `GiftCardCodesUpdate` | `giftCardCodes: string[]` |

- | `GiftCardCodesRemove` | `giftCardCodes: string[]` |

- | `BuyerIdentityUpdate` | `buyerIdentity: CartBuyerIdentityInput` |

- | `NoteUpdate` | `note: string` |

- | `AttributesUpdateInput` | `attributes: AttributeInput[]` |

- | `SelectedDeliveryOptionsUpdate` | `selectedDeliveryOptions: CartSelectedDeliveryOptionInput[]` |

- | `MetafieldsSet` | `metafields: MetafieldWithoutOwnerId[]` |

- | `MetafieldDelete` | `key: string` |

- | `DeliveryAddressesAdd` | `addresses: CartSelectableAddressInput[]` |

- | `DeliveryAddressesUpdate` | `addresses: CartSelectableAddressUpdateInput[]` |

- | `DeliveryAddressesRemove` | `addressIds: string[]` |

- | `DeliveryAddressesReplace` | `addresses: CartSelectableAddressInput[]` |

-

- **In the cart route action:**

- ```ts

- const {action, inputs} = CartForm.getFormInput(formData)

- // Checkbox values are automatically coerced: 'on' → true, 'off' → false

- ```

- Applies pending cart mutations locally for instant UI feedback before the server responds. Requires passing `selectedVariant` in `LinesAdd` inputs.

-

- ```tsx

- import {useOptimisticCart} from '@shopify/hydrogen'

-

- function Cart({cart: serverCart}) {

- const cart = useOptimisticCart(serverCart)

- // cart.lines.nodes — lines with isOptimistic: true are not yet confirmed

- // cart.isOptimistic — true when any optimistic state is pending

- // cart.totalQuantity — recalculated optimistically

- }

- ```

-

- **Important:** Pass `selectedVariant` in `LinesAdd` inputs, otherwise `useOptimisticCart` will log an error and skip the optimistic update:

-

- ```tsx

- <CartForm

- action={CartForm.ACTIONS.LinesAdd}

- inputs={{lines: [{merchandiseId: variantId, quantity: 1, selectedVariant}]}}

- >

- ```

-

- See [references/03-cart.md](references/03-cart.md).

-

- ---

-

- ## Pagination

-

- ```ts

- import {getPaginationVariables, Pagination} from '@shopify/hydrogen'

-

- // In loader:

- const variables = getPaginationVariables(request, {

- pageBy: 12,

- namespace: '', // use when multiple Pagination components are on the same page

- })

- ```

-

- ```tsx

- <Pagination connection={collection.products} namespace="">

- {({nodes, PreviousLink, NextLink, isLoading, hasPreviousPage, hasNextPage, state}) => (

- <>

- {hasPreviousPage && <PreviousLink>Load previous</PreviousLink>}

- <ProductGrid products={nodes} />

- {hasNextPage && <NextLink>{isLoading ? 'Loading...' : 'Load more'}</NextLink>}

- </>

- )}

- </Pagination>

- ```

-

- - `PreviousLink` / `NextLink` render `null` automatically when there's no adjacent page

- - GraphQL query **must** include `pageInfo { hasPreviousPage hasNextPage startCursor endCursor }`

- - Use `namespace` when multiple `Pagination` components share the same page to avoid URL param conflicts

-

- ---

-

- ## SEO

-

- ### getSeoMeta

-

- Generates a React Router `meta` array from one or more SEO config objects. Works like `Object.assign` — later values overwrite earlier ones. Exception: `jsonLd` is **concatenated**, so each route keeps its own structured data.

-

- ```tsx

- import {getSeoMeta} from '@shopify/hydrogen'

-

- export const meta = ({data, matches}) => {

- return getSeoMeta(

- matches[0]?.data?.seo, // parent route (lower priority)

- data?.seo, // current route (higher priority)

- )

- }

- ```

-

- **`SeoConfig` shape:**

- ```ts

- type SeoConfig = {

- title?: string // → <title>, og:title, twitter:title

- titleTemplate?: string // e.g. '%s | My Store'

- description?: string // → <meta name="description">, og:description, twitter:description

- url?: string // → <link rel="canonical">, og:url (trailing slash + query params stripped)

- handle?: string // Twitter @handle → twitter:site, twitter:creator

- media?: {url, width, height, altText, type?} | string

- jsonLd?: WithContext<Thing> // Schema.org — concatenated across routes

- robots?: {

- noIndex?: boolean

- noFollow?: boolean

- noArchive?: boolean

- noSnippet?: boolean

- noImageIndex?: boolean

- noTranslate?: boolean

- maxImagePreview?: string

- maxSnippet?: number

- maxVideoPreview?: number

- unavailableAfter?: string

- }

- alternates?: Array<{url: string; language?: string; default?: boolean}>

- }

- ```

-

- ### getSitemapIndex + getSitemap

-

- Two-level sitemap. Requires Storefront API **2024-10 or later**.

-

- ```ts

- // app/routes/sitemap[.xml].tsx — index

- import {getSitemapIndex} from '@shopify/hydrogen'

-

- export async function loader({request, context: {storefront}}) {

- return getSitemapIndex({

- storefront,

- request,

- types: ['products', 'collections', 'pages', 'articles', 'blogs', 'metaObjects'],

- customChildSitemaps: ['/sitemap/custom/1.xml'],

- })

- }

-

- // app/routes/sitemap.$type.$page[.xml].tsx — per-type pages

- import {getSitemap} from '@shopify/hydrogen'

- export async function loader({request, params, context: {storefront}}) {

- return getSitemap({

- storefront,

- request,

- params,

- locales: ['EN-US', 'FR-CA'],

- getLink: ({type, baseUrl, handle, locale}) =>

- locale ? `${baseUrl}/${locale}/${type}/${handle}` : `${baseUrl}/${type}/${handle}`,

- })

- }

- ```

- ---

- ## Content Security Policy

- ```ts

- import {createContentSecurityPolicy, useNonce} from '@shopify/hydrogen'

- // In entry.server.tsx:

- const {nonce, header, NonceProvider} = createContentSecurityPolicy({

- shop: {

- checkoutDomain: env.PUBLIC_CHECKOUT_DOMAIN,

- storeDomain: env.PUBLIC_STORE_DOMAIN,

- },

- // Add extra sources as needed:

- scriptSrc: ['https://www.googletagmanager.com'],

- connectSrc: ['https://vitals.vercel-insights.com'],

- })

- responseHeaders.set('Content-Security-Policy', header)

- const body = await renderToReadableStream(

- <NonceProvider>

- <ServerRouter context={remixContext} url={request.url} nonce={nonce} />

- </NonceProvider>,

- {nonce, signal: request.signal}

- )

- // In any component:

- const nonce = useNonce()

- ```