Hydrogen(@shopify/hydrogen)은 이미 사용 중인 자바스크립트 프레임워크에서 헤드리스 스토어프론트를 구축하기 위한 Shopify의 툴킷입니다. 이 툴킷에는 코딩 에이전트가 사용하는 법을 가르치는 에이전트 스킬이 함께 제공됩니다.

문서 · API 참고 · 변경 로그

[! 참고] 이 README는 Hydrogen 2026-10 또는 그 이후를 다룹니다. Hydrogen 2026-04 및 그 이전은 2026-04 브랜치에 있으며, 문서는 Legacy Hydrogen에 있습니다. 상점 전환을 원하시면 Migrate를 따라 최신 Hydrogen 버전으로 이동하세요.

포함된 내용

• Storefront API 클라이언트: 타입 gql() 쿼리, 캐싱, 타입 오류.
• 요청 핸들러: Shopify 스토어프론트가 필요로 하는 경로, 예를 들어 스토어프론트 API 프록시, /api/cart, 체크아웃 및 장바구니 퍼머링크, URL 리디렉션, 에이전트용 MCP 엔드포인트 등이 포함됩니다.
• 카트리지: 서버 핸들러, JavaScript 로드 전에 작동하는 HTML 폼, 그리고 서버가 응답하기 전에 줄 변경을 보여주는 저장소.
• 제품 및 컬렉션: 변형 선택, 컬렉션 필터, 정렬, 페이지네이션.
• 예측 검색: 서버 핸들러와 폼 헬퍼가 있는 검색 저장소.
• Money: Shopify MoneyV2 금액을 구매자의 지역과 통화에 맞게 형식화합니다.

Hydrogen

Hydrogen (@shopify/hydrogen) is Shopify’s toolkit for building headless storefronts in the JavaScript framework you already use. It ships with agent skills that teach coding agents how to use it.

Documentation · API reference · Changelog

[!NOTE] This README covers Hydrogen 2026-10 or later. Hydrogen 2026-04 and earlier are on the 2026-04 branch, with docs in Legacy Hydrogen. To migrate a storefront, follow Migrate to the latest version of Hydrogen.

What’s included

• Storefront API client: typed gql() queries, caching, and typed errors.
• Request handlers: the routes a Shopify storefront needs, such as the Storefront API proxy, /api/cart, checkout and cart permalinks, URL redirects, and the MCP endpoints for agents.
• Cart: server handlers, HTML forms that work before JavaScript loads, and a store that shows line changes before the server responds.
• Products and collections: variant selection, collection filters, sorting, and pagination.
• Predictive search: a search store with server handlers and form helpers.
• Money: formats Shopify MoneyV2 amounts for the buyer’s locale and currency.
• Markets: country and language context for Shopify Markets.
• Analytics: Shopify storefront analytics with consent handling.
• Shop Pay: Shop Pay buttons.
• Customer accounts: the Customer Account API client, login and logout handlers, and sessions.

Get started

You need a Shopify store with Storefront API access from the Headless channel. Until you connect one, the template and the setup skill fall back to mock.shop, a public Storefront API with demo data.

Deploy a template

React Router on Oxygen. Shopify’s starter template, templates/react-router, deployed to Oxygen from your Shopify admin.

Next.js on Vercel. Vercel Shop is a Next.js storefront built on Hydrogen and maintained by Vercel.