수소: Shopify의 상거래 프레임워크

Shopify 수소 상점 전면을 구축하기 위한 공식 React 프레임워크입니다. 헤드리스 Shopify. 현재 버전(Hydrogen 2.x)에서는 다음을 기반으로 합니다. 리믹스, 아키텍처에 대한 기본 웹 API 및 서버 작업을 활용하는 React 메타 프레임워크 점차적으로 개선되었습니다.

산소 수소 프로젝트를 위한 Shopify의 글로벌 호스팅 런타임입니다. 기반으로 Cloudflare 작업자 (V8 Isolates), 서버 측 코드 실행 엣지 - 최종 사용자에게 가장 가까운 데이터 센터. 결과는 하나 전 세계적으로 30-80ms의 TTFB(Time to First Byte), 서버로는 달성 불가능 전통적인 중앙집중식.

수소 프로젝트 설정

# Crea un nuovo progetto Hydrogen
npm create @shopify/hydrogen@latest my-store

# Rispondi alle domande:
# - Store domain: mystore.myshopify.com
# - Storefront API token: [da Shopify Admin > Apps > Develop apps]
# - Language: TypeScript
# - CSS: Tailwind CSS

cd my-store
npm run dev
# Apre su http://localhost:3000

Hydrogen 프로젝트의 구조는 Remix를 기반으로 하며 클래식과 매우 유사합니다. 파일 기반 라우팅: 

app/
├── components/           # Componenti UI riutilizzabili
│   ├── Cart.tsx          # Componente carrello
│   ├── ProductCard.tsx   # Card prodotto
│   └── Header.tsx        # Header con mini-cart
├── routes/              # File-based routing Remix
│   ├── _index.tsx        # Homepage (/)
│   ├── products.$handle.tsx  # Pagina prodotto (/products/[handle])
│   ├── collections.$handle.tsx  # Collection (/collections/[handle])
│   └── cart.tsx          # Pagina carrello (/cart)
├── lib/
│   ├── fragments.ts     # GraphQL fragments riutilizzabili
│   └── utils.ts         # Utility functions
├── root.tsx             # Root layout
└── entry.server.tsx     # Server-side entry point

매장 API: 수소 코어

수소는 다음을 통해 Shopify에 연결됩니다. 매장 전면 API GraphQL. 모든 작업 상거래는 GraphQL 쿼리 또는 변형입니다. Hydrogen은 사전 구성된 클라이언트를 제공합니다. 

// app/routes/products.$handle.tsx
// Pagina dettaglio prodotto

import {json} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';
import {Image, Money} from '@shopify/hydrogen';
import type {LoaderFunctionArgs} from '@shopify/remix-oxygen';

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!, $selectedOptions: [SelectedOptionInput!]!) {
    product(handle: $handle) {
      id
      title
      descriptionHtml
      vendor
      selectedVariant: variantBySelectedOptions(selectedOptions: $selectedOptions) {
        id
        availableForSale
        selectedOptions { name value }
        price { amount currencyCode }
        compareAtPrice { amount currencyCode }
        image { url altText width height }
      }
      options {
        name
        values
      }
      variants(first: 100) {
        nodes {
          id
          availableForSale
          selectedOptions { name value }
          price { amount currencyCode }
        }
      }
    }
  }
`;

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

  // Leggi le opzioni selezionate dalla URL (?color=red&size=M)
  const searchParams = new URL(request.url).searchParams;
  const selectedOptions = [];
  for (const [name, value] of searchParams) {
    selectedOptions.push({ name, value });
  }

  const { product } = await storefront.query(PRODUCT_QUERY, {
    variables: { handle, selectedOptions },
    cache: storefront.CacheShort(),    // cache di 1 minuto su Oxygen
  });

  if (!product) throw new Response('Not Found', { status: 404 });

  return json({ product });
}

export default function Product() {
  const { product } = useLoaderData<typeof loader>();
  const { selectedVariant } = product;

  return (
    <div className="product">
      {selectedVariant?.image && (
        <Image
          data={selectedVariant.image}
          className="product-image"
          sizes="(min-width: 768px) 50vw, 100vw"
        />
      )}
      <h1>{product.title}</h1>
      {selectedVariant && (
        <Money data={selectedVariant.price} />
      )}
      <AddToCartButton variant={selectedVariant} />
    </div>
  );
}

Cart API: 수소로 장바구니를 관리하세요

수소는 다음을 통해 카트를 관리합니다. Shopify의 장바구니 API (기준으로 GraphQL 돌연변이). 프레임워크에는 즉각적인 업데이트를 위한 낙관적인 UI 시스템이 포함되어 있습니다. 

// Aggiungere un prodotto al carrello
const ADD_TO_CART_MUTATION = `#graphql
  mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
    cartLinesAdd(cartId: $cartId, lines: $lines) {
      cart {
        id
        totalQuantity
        cost {
          totalAmount { amount currencyCode }
        }
        lines(first: 100) {
          nodes {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                product { title }
                price { amount currencyCode }
                image { url altText }
              }
            }
          }
        }
      }
    }
  }
`;

// Componente AddToCartButton con Fetcher di Remix
import { useFetcher } from '@remix-run/react';

function AddToCartButton({ variant }: { variant: ProductVariant }) {
  const fetcher = useFetcher();
  const isAdding = fetcher.state !== 'idle';

  return (
    <fetcher.Form method="POST" action="/cart">
      <input type="hidden" name="intent" value="add" />
      <input type="hidden" name="variantId" value={variant.id} />
      <button
        type="submit"
        disabled={!variant.availableForSale || isAdding}
        className="add-to-cart-btn"
      >
        {isAdding ? 'Aggiunta...' : 'Aggiungi al Carrello'}
      </button>
    </fetcher.Form>
  );
}

산소 캐싱: 성능의 핵심

Oxygen은 Cloudflare Workers 에지에서 수소 코드를 실행합니다. 캐시는 다음을 통해 관리됩니다. Cloudflare 기본 API 및 수소 도우미: 

// Strategie di cache disponibili in Hydrogen
// Definiamo cache personalizzate per tipo di contenuto

// Cache lunga per pagine prodotto (aggiornamento raro)
export async function loader({ context }: LoaderFunctionArgs) {
  const { storefront } = context;

  const data = await storefront.query(PRODUCTS_QUERY, {
    cache: storefront.CacheLong(),        // cache di 1 ora
  });

  return json(data, {
    headers: {
      'Cache-Control': 'public, max-age=3600, stale-while-revalidate=86400',
    },
  });
}

// Cache breve per dati variabili (inventory, prezzi)
const inventoryData = await storefront.query(INVENTORY_QUERY, {
  cache: storefront.CacheShort(),         // cache di 60 secondi
});

// Nessuna cache per dati personalizzati (cart, customer)
const customerData = await storefront.query(CUSTOMER_QUERY, {
  cache: storefront.NoStore(),            // no-cache
});

액체에서 수소 테마로 마이그레이션

기존 Shopify 테마가 있는 경우 Hydrogen으로 마이그레이션하는 것은 중요한 프로젝트입니다. 권장되는 접근 방식은 점진적입니다.

  1. 우선순위 페이지 식별: 제품 페이지 및 컬렉션 페이지 그들은 더 많은 트래픽을 받습니다. 거기에서 시작하세요.
  2. Hydrogen을 하위 도메인으로 사용: shop.tuodominio.com 수소에 대해, tuodominio.com 액체 테마에. 성능을 테스트하고 측정합니다.
  3. 결제를 별도로 마이그레이션: Shopify는 자체적으로 결제를 처리합니다. 기본 시스템(Checkout Extensibility) — 처음부터 다시 작성할 필요가 없습니다.
  4. 점진적으로 이전: 페이지별로, 경로별로 경로를 지정합니다.

알아야 할 수소의 한계

  • Shopify에서 관리하는 결제: 결제는 항상 도메인에서 이루어집니다. 쇼피파이(checkout.shopify.com). Checkout으로 디자인을 맞춤설정할 수 있습니다. 확장성이 있지만 결제를 자신의 것으로 대체할 수는 없습니다.
  • 부분적인 벤더 종속: 수소/산소는 Shopify에서만 작동합니다. 백엔드. 커머스 플랫폼을 변경하려면 프런트엔드를 다시 작성해야 합니다.
  • API 비율 제한: Storefront API에는 속도 제한이 있습니다. 교통량이 많은 경우 공격적인 캐싱이나 서버 측 캐싱이 포함된 BFF 패턴을 고려하세요.

결론 및 다음 단계

수소 + 산소는 이미 생태계에 종사하는 사람들에게 가장 실용적인 선택입니다. Shopify는 머리가 없어지기를 원합니다. Remix, GraphQL, 엣지 컴퓨팅과 기본 결제 관리는 고성능 매장을 위한 탁월한 기반을 제공합니다.

다음 기사에서는 살펴보겠습니다. 메두사.js, 최고의 오픈 소스 대안 헤드리스: 완전히 자체 호스팅 가능한 모듈형 아키텍처이며 공급업체에 종속되지 않습니다.

이전 기사 ← 마하 아키텍처
시리즈의 다음 Medusa.js: 오픈 소스 전자상거래 →