Hydrogen과 헤드리스 커머스

모든 스토어프론트가 Liquid 테마 모델에 적합한 것은 아닙니다. 브랜드가 픽셀 단위의 정밀한 커스텀 디자인, 앱과 같은 인터랙티비티, 또는 Shopify 외부 데이터 소스와의 통합이 필요할 때 헤드리스 방식을 선택합니다. Hydrogen은 Shopify의 솔루션으로, Remix 기반의 React 프레임워크이며 헤드리스 Shopify 커머스를 위해 특별히 설계되었습니다. 이 레슨에서는 Hydrogen을 언제, 어떻게 사용하는지, 아키텍처, 그리고 첫 번째 헤드리스 스토어프론트를 구축하는 방법을 다룹니다.

헤드리스 커머스란?

전통적인 Shopify 구성에서 스토어프론트(고객이 보는 부분)와 백엔드(데이터가 존재하는 곳)는 긴밀하게 결합되어 있습니다. Shopify는 서버에서 Liquid 템플릿을 렌더링하고 완성된 HTML 페이지를 전달합니다.

헤드리스 커머스에서는 스토어프론트가 백엔드로부터 분리됩니다. 커스텀 프론트엔드가 Storefront API를 통해 Shopify에서 데이터를 가져오고 원하는 방식으로 UI를 렌더링합니다. Shopify는 여전히 상품, 주문, 결제 및 결제 처리를 담당하며, 프레젠테이션 레이어만 직접 제어하게 됩니다.

Hydrogen과 Liquid 테마 선택 기준

시나리오	권장 사항
표준 전자상거래 스토어	Liquid 테마
판매자가 테마 에디터로 콘텐츠 관리	Liquid 테마
예산이 제한된 프로젝트	Liquid 테마
완전한 커스텀 디자인 시스템	Hydrogen
앱과 같은 인터랙션 (애니메이션, 전환)	Hydrogen
다중 소스 콘텐츠 (CMS + Shopify + 커스텀 API)	Hydrogen
React 전문성을 갖춘 개발팀	Hydrogen
하나의 Shopify 백엔드에서 여러 스토어프론트	Hydrogen
고성능 요구 사항 (스트리밍 SSR)	Hydrogen

대부분의 스토어는 Liquid를 사용해야 합니다

Hydrogen은 강력하지만 항상 올바른 선택은 아닙니다. Liquid 테마는 더 빠르게 구축할 수 있고, 판매자가 유지 관리하기 쉬우며, 사용 사례의 90%를 커버합니다. Liquid로 충족할 수 없는 특정 요구 사항이 있고 React 애플리케이션을 장기적으로 지원할 수 있는 팀이 있을 때 Hydrogen을 선택하십시오.

Hydrogen 아키텍처

Hydrogen은 풀스택 React 프레임워크인 Remix 위에 구축되어 있습니다. Remix를 알고 있다면 Hydrogen의 대부분을 이미 알고 있는 것입니다. Shopify는 그 위에 커머스 전용 유틸리티 레이어를 추가합니다.

주요 Hydrogen 패키지

@shopify/hydrogen: 핵심 커머스 컴포넌트 및 유틸리티 (Cart, Analytics, SEO, Money, Image)
@shopify/hydrogen-react: 프레임워크에 독립적인 Shopify용 React hooks (Hydrogen 외부에서도 사용 가능)
@shopify/remix-oxygen: Oxygen 호스팅용 Remix 어댑터
@shopify/cli-hydrogen: Hydrogen 프로젝트 생성 및 관리를 위한 CLI 명령어

Hydrogen 프로젝트 생성

# 새 Hydrogen 스토어프론트 생성
npm create @shopify/hydrogen@latest -- --template demo-store

# CLI에서 다음과 같이 묻습니다:
# ? Where would you like to create your app? hydrogen-store
# ? Choose a language: TypeScript
# ? Connect to Shopify: Use mock.shop (or connect your store)

프로젝트 구조

hydrogen-store/
├── app/
│   ├── components/           # 재사용 가능한 UI 컴포넌트
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   ├── ProductCard.tsx
│   │   └── CartDrawer.tsx
│   ├── routes/               # 파일 기반 라우팅 (Remix)
│   │   ├── ($locale)._index.tsx       # 홈페이지
│   │   ├── ($locale).products.$handle.tsx  # 상품 페이지
│   │   ├── ($locale).collections.$handle.tsx
│   │   ├── ($locale).cart.tsx
│   │   ├── ($locale).account.tsx
│   │   └── [sitemap.xml].tsx
│   ├── lib/
│   │   └── fragments.ts      # 재사용 가능한 GraphQL 프래그먼트
│   ├── styles/
│   │   └── app.css
│   ├── entry.server.tsx       # 서버 진입점
│   └── root.tsx               # 루트 레이아웃
├── public/
│   └── favicon.svg
├── server.ts                  # Oxygen/Node 서버
├── storefrontapi.generated.d.ts  # 자동 생성된 타입
├── .env                       # 환경 변수
└── hydrogen.config.ts         # Hydrogen 설정

Storefront API 연동

Hydrogen은 모든 데이터 가져오기에 Storefront API를 사용합니다. API 클라이언트는 서버 진입점에서 설정되며 Remix 컨텍스트를 통해 라우트 로더에 전달됩니다.

클라이언트 설정

// server.ts
import {createStorefrontClient} from '@shopify/hydrogen';

const {storefront} = createStorefrontClient({
  storeDomain: env.PUBLIC_STORE_DOMAIN,
  publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
  privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
  storefrontApiVersion: '2026-04',
});

라우트 로더에서 데이터 가져오기

Hydrogen은 서버에서 실행되는 로더 함수에서 데이터를 로드하는 Remix 패턴을 따릅니다:

// app/routes/($locale).products.$handle.tsx
import {json, type LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';
import {Image, Money, ShopPayButton} from '@shopify/hydrogen';

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
      descriptionHtml
      vendor
      tags
      featuredImage {
        url
        altText
        width
        height
      }
      priceRange {
        minVariantPrice {
          amount
          currencyCode
        }
      }
      variants(first: 100) {
        nodes {
          id
          title
          availableForSale
          price {
            amount
            currencyCode
          }
          selectedOptions {
            name
            value
          }
          image {
            url
            altText
            width
            height
          }
        }
      }
      seo {
        title
        description
      }
    }
  }
`;

export async function loader({params, context}: LoaderFunctionArgs) {
  const {handle} = params;
  const {storefront} = context;

  const {product} = await storefront.query(PRODUCT_QUERY, {
    variables: {handle},
    cache: storefront.CacheLong(),
  });

  if (!product) {
    throw new Response('Product not found', {status: 404});
  }

  return json({product});
}

export default function ProductPage() {
  const {product} = useLoaderData<typeof loader>();
  const firstVariant = product.variants.nodes[0];

  return (
    <div className="product-page">
      <div className="product-grid">
        <div className="product-image">
          {product.featuredImage && (
            <Image
              data={product.featuredImage}
              sizes="(min-width: 768px) 50vw, 100vw"
            />
          )}
        </div>

        <div className="product-info">
          <h1>{product.title}</h1>
          <p className="vendor">{product.vendor}</p>

          <Money
            data={firstVariant.price}
            className="product-price"
          />

          <div
            className="product-description"
            dangerouslySetInnerHTML={{
              __html: product.descriptionHtml,
            }}
          />

          <ShopPayButton
            variantIds={[firstVariant.id]}
            storeDomain={context.env.PUBLIC_STORE_DOMAIN}
          />
        </div>
      </div>
    </div>
  );
}

캐싱 전략

Hydrogen은 성능에 매우 중요한 내장 캐싱 유틸리티를 제공합니다:

// storefront 클라이언트에서 사용 가능한 캐시 전략
storefront.query(query, {
  cache: storefront.CacheNone(),      // 캐시 없음 (실시간 데이터)
  cache: storefront.CacheShort(),     // 1초 스테일, 60초 최대
  cache: storefront.CacheLong(),      // 1시간 스테일, 1일 최대
  cache: storefront.CacheCustom({
    mode: 'public',
    maxAge: 60,           // 초
    staleWhileRevalidate: 300,
  }),
});

캐시 전략 가이드라인

상품 페이지: CacheLong() -- 상품 데이터는 자주 변경되지 않습니다
컬렉션 페이지: CacheLong() -- 상품과 유사합니다
장바구니: CacheNone() -- 항상 실시간이어야 합니다
검색 결과: CacheShort() -- 신선하되 짧은 지연은 허용 가능합니다
홈페이지: CacheLong() 및 콘텐츠 변경 시 수동 무효화

서버 사이드 렌더링과 스트리밍

Hydrogen은 Remix의 스트리밍 SSR을 활용하여 빠른 초기 페이지 로드를 제공합니다. 모든 데이터가 해결될 때까지 기다린 후 HTML을 전송하는 대신, 서버가 즉시 HTML 셸을 스트리밍하고 데이터가 도착하는 대로 동적 콘텐츠를 채웁니다.

// app/routes/($locale).collections.$handle.tsx
import {defer, type LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {Await, useLoaderData} from '@remix-run/react';
import {Suspense} from 'react';

export async function loader({params, context}: LoaderFunctionArgs) {
  const {handle} = params;
  const {storefront} = context;

  // 중요 데이터: 즉시 await
  const collection = await storefront.query(COLLECTION_QUERY, {
    variables: {handle, first: 12},
  });

  // 중요하지 않은 데이터: 스트리밍을 위해 defer
  const recommendations = storefront.query(RECOMMENDATIONS_QUERY, {
    variables: {handle},
  });

  return defer({
    collection: collection.collection,
    recommendations,  // await하지 않은 Promise
  });
}

export default function CollectionPage() {
  const {collection, recommendations} = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{collection.title}</h1>

      {/* 중요 콘텐츠는 즉시 렌더링 */}
      <ProductGrid products={collection.products.nodes} />

      {/* 지연된 콘텐츠는 준비되면 스트리밍 */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Await resolve={recommendations}>
          {(data) => (
            <RecommendedProducts products={data.products.nodes} />
          )}
        </Await>
      </Suspense>
    </div>
  );
}

이 패턴은 일부 데이터가 로드되는 데 시간이 걸리더라도 고객이 밀리초 내에 의미 있는 콘텐츠를 볼 수 있도록 보장합니다.

Oxygen 호스팅

Oxygen은 Hydrogen 스토어프론트를 위해 특별히 설계된 Shopify의 엣지 호스팅 플랫폼입니다.

배포

Oxygen은 GitHub와 통합되어 자동 배포가 가능합니다:

Shopify Admin의 판매 채널 > Hydrogen에서 GitHub 리포지토리를 연결합니다
메인 브랜치에 푸시하면 Oxygen이 자동으로 배포합니다
다른 브랜치에 푸시하면 Oxygen이 미리보기 배포를 생성합니다

# Shopify CLI를 통한 수동 배포
shopify hydrogen deploy

환경 변수

Shopify Admin 또는 CLI를 통해 환경 변수를 관리합니다:

# 프로덕션용 환경 변수 설정
shopify hydrogen env push

# 로컬 .env로 환경 변수 가져오기
shopify hydrogen env pull

Oxygen을 선택하는 이유

무설정: 서버 설정, CDN 구성, 스케일링 결정이 필요 없습니다
글로벌 엣지 네트워크: 워커가 전 세계 고객 가까이에서 실행됩니다
Shopify 최적화: Shopify의 Storefront API에 대한 최저 지연 경로
미리보기 배포: 모든 브랜치에 고유한 URL이 제공됩니다
내장 분석: Shopify Admin에서 성능 모니터링

Oxygen은 필수가 아닙니다

Hydrogen을 모든 Node.js 호스팅 제공업체에 배포할 수 있습니다 -- Vercel, Netlify, Cloudflare Workers, Fly.io 또는 자체 서버. Oxygen은 편리하고 Shopify에 최적화되어 있지만 종속되지는 않습니다.

스타터 템플릿

Shopify는 여러 Hydrogen 스타터 템플릿을 제공합니다:

템플릿	설명
`demo-store`	모든 페이지를 갖춘 완전한 스토어프론트
`hello-world`	최소한의 시작점
`skeleton`	라우팅이 포함된 기본 구조, 스타일링 없음

# 특정 템플릿으로 생성
npm create @shopify/hydrogen@latest -- --template demo-store

# 또는 복제 후 커스터마이즈
npm create @shopify/hydrogen@latest -- --template skeleton

demo-store 템플릿에는 상품 페이지, 컬렉션 페이지, 장바구니 기능, 고객 계정, 검색, 블로그, SEO가 포함되어 있습니다 -- 커스터마이즈할 수 있는 완전한 스토어프론트입니다.

핵심 요약

Hydrogen은 헤드리스 Shopify 스토어프론트를 구축하기 위한 React + Remix 프레임워크입니다
완전한 디자인 제어, React 전문성, 또는 다중 소스 데이터 통합이 필요할 때 사용합니다
Storefront API가 데이터 레이어입니다 -- 라우트 로더에서 타입이 지정된 GraphQL 쿼리로 접근합니다
defer와 Await를 사용한 스트리밍 SSR이 빠른 초기 페이지 로드를 제공합니다
Oxygen은 GitHub 통합과 미리보기 배포를 갖춘 무설정 엣지 호스팅을 제공합니다
대부분의 스토어는 Liquid 테마를 사용해야 합니다 -- Hydrogen은 특정 고급 사용 사례를 위한 것입니다

다음으로 Shopify Functions를 살펴봅니다 -- Shopify 인프라 내에서 커머스 로직을 커스터마이즈할 수 있게 해주는 WebAssembly 런타임입니다.

헤드리스 커머스란?​

Hydrogen과 Liquid 테마 선택 기준​

Hydrogen 아키텍처​

주요 Hydrogen 패키지​

Hydrogen 프로젝트 생성​

프로젝트 구조​

Storefront API 연동​

클라이언트 설정​

라우트 로더에서 데이터 가져오기​

캐싱 전략​

서버 사이드 렌더링과 스트리밍​

Oxygen 호스팅​

배포​

환경 변수​

Oxygen을 선택하는 이유​

스타터 템플릿​

핵심 요약​