LoginSignup
22
13

More than 1 year has passed since last update.

@t-kurasawa(倉澤 孝明)in株式会社野村総合研究所

Shopify 公式ヘッドレスコマースフレームワーク "Hydrogen" ドキュメント和訳

Last updated at Posted at 2022-03-18

Hydrogen は React 18 をベースにした Shopify 公式ヘッドレスコマースフレームワークです。
本記事では Hydrogen フレームワークそのものを深堀り調査し、日本語訳していきたいと思います。

先日は Hydrogen の概要とフレームワークを用いた EC サイトの構築について解説しました。日本ではまだまだ Hydrogen の情報が少ないため正式リリースに向けて日本の開発者コミュニティを盛り上げていきたいです。React 18 がまもなくリリースという情報と GitHub に v1.x-2022-07 という表記があることからも Hydrogen は Shopify Unite 2022 で正式リリースの発表があるのではないかと勝手に推測しています。楽しみですね。

本記事の調査元となるソースコードやドキュメントは Hydrogen GitHub (MIT License) や開発者サイトです。掲載している文章や画像やソースコードは Shopify Japan の方に許可を頂き、引用・翻訳・加筆しています。

本記事執筆段階で各バージョンは以下です。隔週～毎月のペースで改善されバージョンが上がっていますので利用される際には最新をご確認ください。

@shopify/hydrogen@0.12.0
@shopify/hydrogen-cli@0.12.0
create-hydrogen-app@0.12.0
eslint-plugin-hydrogen@0.11.0

目次

  • Hydrogen フレームワーク

    • Hydrogen 機能概要
    • コンポーネント機能
    • フック機能
    • ユーティリティ機能

  • Hydrogen ツール郡

    • hydrogen-cli
    • create-hydrogen-app
    • eslint-plugin-hydrgen

Hydrogen フレームワーク

本章では、Hydrogen フレームワークの機能概要、コンポーネント、フック、ユーティリティ機能を説明します。

Hydrogen 機能概要

Hydrogen は React フレームワークと UI コンポーネント（SDK）です。高速でダイナミックなShopify カスタムストアを構築するために使用することができます。

フレームワーク

サーバーサイドレンダリング（SSR）、ミドルウェア、クライアントコンポーネントのコード変換（Vite）を提供します。

UI コンポーネント

Shopify の機能をサポートするコンポーネント、フック、ユーティリティが含まれています。

hydrogen-overview.png
（出典）Hydrogen overview を元に加筆・翻訳

データソース

Shopify の Storefront API を利用することが出来ます。後述のコンポーネント、フック、ユーティリティに渡されるデータは Storefront API の GraphQL の構造に対応しています。外部のサードパーティデータもサポートしています。外部データと組み合わせる場合は Hydrogen コンポーネント、フック、ユーティリティの型に変換して利用します。

hydrdata-sources.png

例えば、外部データが商品データと形式が違う際には ProductProvider コンポーネントが期待する形式に変換する必要があります。

もし、Shopify の商品データやショッピング体験に付随するデータ、例えばCMSコンテンツを他のプロバイダから取得したい場合は、useQuery フックを実装することで独自のコンポーネントをレンダリングすることができます。useQuery フックの内部では、サーバーコンポーネントの fetch() メソッドや、Axios のような HTTPクライアントを使用することができ、クライアントとサーバーの両方で使用することが可能です。

ProductProviderConverter.ts
const third_party_data = {
  "productId": <number>,
  "productHandle": "<string>",
  "productTitle": "<string>",
  "description": { plain: "<string>", html: "<string>" },
  ...
}


function converter(third_party_data) {
  return {
    id: third_party_data.productId.toString(),
    handle: third_party_data.productHandle,
    title: third_party_data.productTitle,
    description: third_party_data.description.plain,
    descriptionHtml: third_party_data.description.html,
    ...
  }
}

Shopify Storefront API については以下記事をご覧ください。

（出典）Hydrogen data sources を元に加筆・翻訳

コンポーネント機能

Hydrogen コンポーネントは EC のビジネスロジックを含むオブジェクトです。データのパースや処理に使用されます。

React Server Components

Hydrogen は React Server Components をモデルにし React アプリのデータ取得とレンダリングのワークフローを管理しています。サーバーとクライアントが連携してアプリをレンダリングします。

例）
以下の React 要素ツリーは、他の React コンポーネントをレンダリングする React コンポーネントで構成されています。React Server Components では、一部のコンポーネントはサーバー上でレンダリングし、一部はサーバーサイドレンダリング（SSR）を使用してブラウザまたはサーバー上でレンダリングし、その他のコンポーネントはサーバーとクライアントの両方でレンダリングすることができます。

※ React Server Components の詳しい説明は React ブログの記事を参照ください。

react-element-tree.png

（出典）React Server Components overview を元に加筆・翻訳

コンポーネントタイプ

React Server Components には、以下の３つのコンポーネントタイプがあります。

Server

.server.jsx

サーバー上でデータを取得し、コンテンツをレンダリングするコンポーネントです。

  • クライアントでは実行されず、依存関係はクライアントバンドルに含まれません。
  • クライアントサイドのインタラクティビティを一切含みません。
  • サーバーコンポーネントのみが、Storefront API を呼び出すことができます。

Client

.client.jsx

  • ブラウザ、または SSR を使用してサーバーでレンダリングされるコンポーネントです。
  • 多くの React アプリは、パフォーマンスや SEO を向上させるために SSR を使用しています。
  • クライアントコンポーネントには、クライアントサイドのステートフルなインタラクティビティが含まれます。

Shared

.client.jsx または .server.jsx

  • サーバーとクライアントの両方でレンダリングするコンポーネントです。

（出典）Component types を元に加筆・翻訳

プリミティブコンポーネント

商品、バリエーション、カートなど、さまざまなコンポーネントタイプの構成要素です。

コンポーネント名 コンポーネントタイプ 説明 Git
ExternalVideo Shared Storefront API の ExternalVideo オブジェクトの埋め込み動画をレンダリングします。 :octocat:
Image Shared Storefront API の Image オブジェクトの画像をレンダリングします。 :octocat:
MediaFile Shared Storefront API の Media オブジェクトのメディアをレンダリングします。prop として提供されたメディアの mediaContentType に応じて、Image、Video、ExternalVideo、または ModelViewer のいずれかをレンダリングします。 :octocat:
Metafield Client Storefront API の Metafield オブジェクトの値をレンダリングします。 :octocat:
ModelViewer Client Storefront API の Model3d オブジェクトの 3D モデル (model-viewer タグ付き) をレンダリングします。 :octocat:
Money Client Storefront API の MoneyV2 オブジェクトの文字列をレンダリングします。 :octocat:
Seo Shared ウェブページにSEO情報を表示します。 :octocat:
ShopPayButton Client Shop Payのチェックアウトにリダイレクトするボタンをレンダリングします。 :octocat:
UnitPrice Client 単価の文字列を表示します。 :octocat:
Video Shared Storefront API の Video オブジェクトに対応した動画をレンダリングします。 :octocat:

（出典）Primitive components を元に加筆・翻訳

グローバルコンポーネント

グローバルコンポーネントは、アプリ全体をラップします。
ShopifyProvider コンポーネント は、フックのサポートを提供します。アプリのエントリーポイントコンポーネントに配置する必要があります。

App.server.jsx
import {ShopifyProvider} from '@shopify/hydrogen';
import shopifyConfig from '../shopify.config';

export default function App() {
  return (
    <ShopifyProvider shopifyConfig={shopifyConfig}>
      {/* Routes, Pages, etc */}
    </ShopifyProvider>
  );
}

注意点

  • ShopifyProvider は Hydrogen 固有のもので、現在のところ Next.js や他のフレームワークでは動きません。
  • アプリ内で ShopifyProvider の複数のインスタンスを持つことはできません。Context（サーバーコンポーネントでは現在サポートされていません）を使用していないので、すべての インスタンスは、各リクエストに対して同じ設定を共有します。
  • サーバーへの各リクエストに対して、動的に構成(shopifyConfig prop)を定義することができます。これは、1つの Hydrogen アプリで複数のストアフロントを集約する場合に便利です。

（出典）ShopifyProvider を元に加筆・翻訳

商品とバリエーションコンポーネント

コンポーネント名 コンポーネントタイプ 説明 Git
ProductDescription Client 商品の descriptionHtml を含む div コンポーネントをレンダリングします。 :octocat:
ProductMetafield Client 商品メタフィールドを持つメタフィールドコンポーネントをレンダリングします。 :octocat:
ProductPrice Client 商品 priceRange の maxVariantPrice または minVariantPrice、商品 compareAtPriceRange の maxVariantPrice または minVariantPrice で Money コンポーネントをレンダリングします。 :octocat:
ProductProvider Client 商品の詳細情報を含むコンテキストを設定します。 :octocat:
ProductTitle Client 商品のタイトルをspan要素で描画します。 :octocat:

（出典）Product and variant components を元に加筆・翻訳

カートコンポーネント

カートの中には、お客様が購入しようとする商品と、その購入にかかる見積金額が含まれています。お客様が商品を購入する準備ができたら、チェックアウトに進みます。

コンポーネント名 コンポーネントタイプ 説明 Git
AddToCartButton Client AddToCartButtonコンポーネントは、押されたときにカートに商品を追加するボタンをレンダリングします。 :octocat:
BuyNowButton Client BuyNowButtonコンポーネントは、商品をカートに追加し、チェックアウトにリダイレクトするためのボタンをレンダリングします。 :octocat:
CartEstimatedCost Client CartEstimatedCostコンポーネントは、amountTypeプロパティーに関連付けられたコストを持つMoneyコンポーネントをレンダリングします。 :octocat:
CartLineImage Client CartLineImageコンポーネントは、カートライン商品の画像用Imageコンポーネントをレンダリングします。 :octocat:
CartLinePrice Client CartLinePriceコンポーネントは、カートラインの商品価格または価格比較のためのMoneyコンポーネントをレンダリングします。 :octocat:
CartLineProductTitle Client CartLineProductTitleコンポーネントは、カートライン商品のタイトルをspan要素（またはasプロパティで指定されたHTML要素のタイプ）にレンダリングします。 :octocat:
CartLineProvider Client CartLineProviderコンポーネントは、カートラインを使用するためのコンテキストを作成します。 :octocat:
CartLineQuantity Client CartLineQuantityコンポーネントは、カートラインの数量をspan要素（またはas propで指定されたHTML要素のタイプ）にレンダリングします。 :octocat:
CartLineQuantityAdjustButton Shared CartLineQuantityAdjustButtonコンポーネントは、押されたときにカートラインの数量を調整するボタンをレンダリングします。 :octocat:
CartLines Shared CartLinesコンポーネントは、各カートラインを繰り返し、各カートラインのCartLineProvider内でその子をレンダリングします。 :octocat:
CartProvider Client CartProviderコンポーネントは、カートを使用するためのコンテキストを作成します。 :octocat:
CartShopPayButton Client CartShopPayButtonコンポーネントは、カート内のアイテムにShopPayButtonをレンダリングします。 :octocat:

（出典）Cart components を元に加筆・翻訳

ローカライゼーションコンポーネント

ローカライゼーションは、現地の言語や通貨でショッピング体験を提供することで、世界中の人々にビジネスを拡大することを可能にします。

LocalizationProviderコンポーネントは、Storefront APIのローカライズフィールドに、ISOコード、国名、有効な国を自動的に問い合わせ、情報をコンテキストに保持します。useCountryフックは、現在のローカライズの国と、更新するための関数を返します。LocalizationProviderコンポーネントの子孫である必要があります。

localization-provider.example.tsx
import {LocalizationProvider} from '@shopify/hydrogen';

export function Component() {
  return <LocalizationProvider>{children}</LocalizationProvider>;
}

（出典）LocalizationProvider を元に加筆・翻訳

コンポーネントのカスタマイズ

パススルーやレンダープロップを使って、Hydrogenコンポーネントをカスタマイズすることができます。

Passthrough props

Hydrogen コンポーネントに属性を渡すことができます。Hydrogen コンポーネントは、レンダリングされる HTML タグに属性を渡します。

Render props

JSX を返す関数を Hydrogen コンポーネントに子として渡すことができます。

（出典）Customizing Hydrogen components を元に加筆・翻訳

フック機能

フック機能は、Hydrogenコンポーネント内部でstateなどのメソッドを利用できるようにするための関数です。

プリミティブフック

プリミティブフックは、商品、バリエーション、カートなど、さまざまなコンポーネントタイプの構成要素です。

フック名 説明 Git
useLoadScript useLoadScriptフックは、クライアントサイドで外部スクリプトタグをロードします。 :octocat:
useMoney useMoneyフックはMoneyV2オブジェクトを受け取り、正しい通貨表示を持つ金額のデフォルトフォーマット文字列と、Intl.NumberFormatが提供するいくつかの部品を返します。 :octocat:

（出典）Primitive hooks を元に加筆・翻訳

グローバルフック

グローバルフックは、アプリ全体に関係するReactフックです。グローバルフックは、サーバーコンポーネントからデータを取得するために使用します。

フック名 説明 Git
useServerState useServerStateフックは、React Server ComponentフレームワークとしてHydrogenを使用する際に、サーバーの状態を管理するためのフックです。 :octocat:
useShop useServerStateフックは、React Server ComponentフレームワークとしてHydrogenを使用する際に、サーバーの状態を管理するためのフックです。 :octocat:
useShopQuery useShopQuery フックを使用すると、Storefront API に対してサーバのみの GraphQL クエリを実行できます。 :octocat:
useQuery useQueryフックは、Fetchなどの非同期処理をSuspenseに対応した形で実行します。 :octocat:
useUrl useUrlフックは、サーバーやクライアントコンポーネントの現在のURLを取得します。 :octocat:

（出典）Global hooks を元に加筆・翻訳

商品とバリエーションフック

フック名 説明 Git
useProduct useProduct フックは、最も近い ProductProvider の商品オブジェクトを返す。 :octocat:
useProductOptions useProductOptions フックは、状態を修正するためのコールバックと同様に、選択された variant や販売計画の状態を追跡することを可能にするオブジェクトを返します。 :octocat:

（出典）Product and variant hooks を元に加筆・翻訳

カートフック

フック名 説明 Git
useCart useCart フックは、cart オブジェクトへのアクセスを提供します。 :octocat:
useCartLine useCartLine フックは、カートラインオブジェクトへのアクセスを提供します。 :octocat:

（出典）Cart hooks を元に加筆・翻訳

ローカライゼーションフック

フック名 説明 Git
useAvailableCountries useAvailableCountriesフックは、ローカライズに使用される利用可能な国の配列を返します。 :octocat:
useCountry useCountryフックは、現在のローカライズの国とそれを更新するための関数をタプルで返します。 :octocat:

（出典）Localization hooks を元に加筆・翻訳

メタフィールドフック

フック名 説明 Git
useParsedMetafields useParsedMetafieldsフックは、MetafieldConnectionを、メタフィールドの種類に応じて値がパースされたメタフィールドの配列に変換するフックです。 :octocat:

（出典）Metafield hooks を元に加筆・翻訳

ユーティリティ機能

ユーティリティ名 説明 Git
flattenConnection 接続オブジェクトをフラットな配列に変換します。 :octocat:
isClient クライアントでコードが実行されたかどうかを示す。 :octocat:
isServer サーバー上でコードが実行されたかどうかを示す。 :octocat:
log アプリケーションに関するデバッグ情報、警告情報、エラー情報をログに記録します。 :octocat:
parseMetafieldValue メタフィールドの値を、文字列からメタフィールドの型に対応するセンシブルな型にパースします。 :octocat:
queryShop Storefront API への問い合わせを支援します。 :octocat:

（出典）utilities を元に加筆・翻訳

Hydrogen ツール郡

本章では、Hydrogen の開発に役立つツール郡を説明します。

hydrogen-cli

create-hydrogen-app

eslint-plugin-hydrogen

変更履歴

更新日 更新内容
2022-03-18 初版作成
2022-03-20 Shopify Storefront API 解説記事を追加

本記事の調査元となるソースコードやドキュメントは Hydrogen GitHub (MIT License) や開発者サイトです。掲載している文章や画像やソースコードは Shopify Japan の方に許可を頂き、引用・翻訳・加筆しています。

22
13
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
22
13