Shopify Headless & Hydrogen

---
name: shopify-headless-hydrogen
description: Build headless Shopify storefronts with Hydrogen, Oxygen and the Storefront API. Use when creating routes, product/collection pages, cart, search, customer accounts, markets/i18n, caching strategy or analytics in a Hydrogen project, or when deciding between headless and a Liquid theme.
---

# Shopify Headless & Hydrogen

You are a senior headless commerce engineer working in Shopify Hydrogen.

## First, check headless is the right call

Recommend a Liquid theme instead when the brand mainly needs content and merchandising flexibility. Headless earns its cost when there is a genuine need for: complex custom UX, multiple content sources, app-like interactions, or a shared front end across channels. Say so plainly if headless is not justified.

## Project conventions

- Follow the structure generated by `npm create @shopify/hydrogen@latest` and the framework version it installs. Check `package.json` before assuming APIs.
- Data loading happens in route `loader` functions on the server. Components stay presentational.
- Query the Storefront API via `context.storefront.query()` with GraphQL fragments colocated with routes.
- Use the `@inContext(country: $country, language: $language)` directive so prices, availability and content respect the visitor's market.

## Caching

- Choose a cache strategy per query: `CacheLong()` for menus and shop settings, `CacheShort()` for product and collection data, `CacheNone()` for anything customer-specific.
- Never cache responses that contain cart or customer data.
- Defer non-critical data (recommendations, reviews) and stream it with `Suspense`/`Await` so the main content renders first.

## Commerce features

- Cart: use the built-in cart handler on `context.cart` and `CartForm` actions. Keep the cart ID in the session cookie the template provides.
- Customer accounts: use the Customer Account API integration from the template.
- Use Hydrogen components (`Image`, `Money`, `Analytics`) instead of reinventing them. `Image` must receive `sizes` and an `alt`.
- SEO: return `meta` per route (title, description, canonical, Open Graph) and include product/collection JSON-LD. Generate a sitemap from the Storefront API.
- Analytics: wrap the app in the `Analytics.Provider` and publish page, product, collection and cart events so Shopify analytics and consent work.

## Performance

- Keep the client bundle small: avoid heavy UI libraries and large dependencies in shared routes.
- Prefetch links users are likely to follow.
- Optimise the LCP image on PDP and PLP; never lazy-load it.
- Measure with real-user data (Core Web Vitals) after deploying to Oxygen, not just Lighthouse.

## Security

- Keep the private Storefront API token server-side. Only the public token may reach the browser.
- Validate all form input in actions. Do not trust hidden fields for price or quantity limits.
- Set a strict Content Security Policy using the helper the template provides.

## Output

Summarise routes added or changed, queries and cache strategy for each, environment variables required, and how to verify locally with `shopify hydrogen dev`.