vtex-io-storefront-react

Storefront React コンポーネント

このスキルを使用する場面

ストアフロント向けのエクスペリエンスを構築するために、react ビルダーで購入者向けの React コンポーネントを作成する場合に、このスキルを使用します。

• 商品またはカテゴリーの UI ウィジェットを作成する
• カスタムバナー、フォーム、購入者向けのレイアウト要素を構築する
• ストアフロントのフックまたはコンテキストプロバイダーを使用する
• css-handles でコンポーネントをスタイリングする

次の場合には、このスキルを使用しないでください。

• 管理ページ
• ブロック登録と render-runtime のコントラクト
• サービスランタイムまたはバックエンドルートの設計
• GraphQL スキーマの設計

判断ルール

• ストアフロントのコンポーネントはブラウザー向けの UI として扱い、購入者が使用する環境で安全に動作するようにします。
• ストアフロントのコンポーネントは表示に専念させ、props でデータを受け取ることを優先し、複雑なデータ取得やビジネスロジックはフックまたはコンテナーコンポーネントに移します。
• ハードコードされたグローバルクラス名ではなく、vtex.css-handles を使用します。
• ブラウザーから VTEX API を直接呼び出したり、ストアフロントコードでアプリキーを使用したりするのではなく、props、または useProduct、useRuntime、useOrderForm などのドキュメント化されたストアフロントのフックやコンテキストを通じてデータを受け取ることを優先します。
• 商品または検索のコンテキストが読み込み中、空、あるいは利用できない状態でも、コンポーネントが適切に動作するようにします。
• 購入者向けの文言には、文字列リテラルではなく、vtex-io-messages-and-i18n で説明されている messages インフラストラクチャのメッセージ ID とヘルパーを使用します。
• ストアフロントのコンポーネントは、ストアフロントのアクセシビリティを担うものとして扱います。クリック可能な div ではなく button や a などのセマンティックな HTML 要素を使用し、重要なコンテンツには適切なラベルまたは代替テキストを設定します。
• window や document などのブラウザーグローバルにアクセスする場合は、たとえば useEffect を使用するか、typeof window !== 'undefined' を確認して、サーバーサイドで実行される場合に備えます。

厳守事項

制約：ストアフロントのスタイリングには css-handles を使用する必要があります

ストアフロントのコンポーネントは、任意のハードコードされたクラス名ではなく、css-handles を通じてスタイリングを公開する必要があります。

重要な理由

css-handles は、ストアフロントのコンポーネントをカスタマイズするためのコントラクトです。ハードコードされたクラス名や非公開のクラス名を使用すると、テーマを安全に拡張しにくくなります。

検出方法

ストアフロントのコンポーネントが css-handles を使わずに任意のグローバルクラス名を使用している場合は、作業を中止し、まず handles を通じてスタイリングを公開してください。

正しい例

const CSS_HANDLES = ['container', 'title'] as const

誤った例

return <div className="my-random-block-root">...</div>

制約：ストアフロントのコンポーネントはブラウザーで安全に動作する必要があります

ストアフロントの React コードは、Node 専用 API やサーバー専用の前提に依存してはなりません。

重要な理由

これらのコンポーネントは購入者向けのフロントエンドで動作します。サーバー専用の依存関係はレンダリングを妨げ、ブラウザーでのランタイムエラーを引き起こします。

検出方法

コンポーネントが Node 専用モジュール、ファイルシステムへのアクセス、またはサーバーランタイムを前提とする機能を使用している場合は、作業を中止し、ブラウザー向けに再設計してください。

正しい例

return <span>{label}</span>

誤った例

import fs from 'fs'

制約：購入者向けの文字列はローカライズ可能でなければなりません

ストアフロントで表示される文字列には、ハードコードされたテキストではなく、アプリの i18n パターンを使用する必要があります。

重要な理由

ストアフロントの UI は、さまざまなロケールやストアで使用されます。文字列をハードコードすると、コンポーネントの再利用性が低下し、VTEX IO のローカライズとの一貫性も損なわれます。

検出方法

購入者に表示される文言が JSX にハードコードされている場合は、作業を中止し、i18n の仕組みに移してください。

正しい例

<FormattedMessage id="storefront.cta" />

誤った例

<span>Buy now</span>

推奨パターン

ストアフロントのコンポーネントは、小さく保ち、props でデータを受け取り、css-handles を使用し、購入者が使用する環境で安全に動作するようにします。

css-handles の最小限のパターン：

import { useCssHandles } from 'vtex.css-handles'

const CSS_HANDLES = ['container', 'title'] as const

export function MyComponent() {
  const { handles } = useCssHandles(CSS_HANDLES)

  return (
    <div className={handles.container}>
      <h2 className={handles.title}>...</h2>
    </div>
  )
}

よくある失敗

• css-handles を使わずにクラス名をハードコードする。
• ブラウザーで安全に動作しない依存関係を使用する。
• 購入者に表示される文字列をハードコードする。
• VTEX のストアフロントパターンを使用せず、場当たり的な方法でデータを取得する。
• フックやコンテナーを使用せず、複雑なビジネスロジックや負荷の高いデータ取得を表示専用のコンポーネントに直接組み込む。
• button や a を使用すべき場面で、onClick を持つ div や span などのセマンティクスを持たないクリック可能な要素を使用する。

レビューチェックリスト

• このコンポーネントは本当に購入者向けですか？
• スタイルは css-handles を通じて公開されていますか？
• このコンポーネントはブラウザー上で安全に実行できますか？
• 表示される文字列はローカライズされていますか？
• データフローはストアフロントコンポーネントに適していますか？

関連スキル

• vtex-io-render-runtime-and-blocks - 主な確認事項がブロックの登録と Store Framework の接続である場合に使用します
• vtex-io-messages-and-i18n - 主な確認事項が購入者向けの文字列の翻訳と整理方法である場合に使用します

リファレンス

• Store Framework - ストアフロントアプリのコンテキスト、データ、フック
• CSS Handles - VTEX IO ストアフロントコンポーネントのスタイリング仕様