faststore-overrides

FastStore セクションとコンポーネントのオーバーライド

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

次の場合にこのスキルを使用します：

• テーマ設定やデザイントークンだけでは実現できない範囲で、FastStore ストアフロントのコンポーネントの動作や外観をカスタマイズする必要がある。
• ネイティブコンポーネントを完全に置き換えるカスタム実装が必要である。
• セクション内のネイティブコンポーネントにカスタムロジックを挿入するか、props を変更する必要がある。
• src/components/overrides/ 内のファイルを扱っている。

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

• 見た目のみの変更（色、タイポグラフィ、余白）— 代わりに faststore-theming スキルとデザイントークンを使用してください。
• カート、セッション、検索用のカスタム状態管理の構築 — faststore-state-management スキルを使用してください。
• GraphQL データレイヤーの拡張 — faststore-data-fetching スキルを使用してください。

判断ルール

• テーマ設定だけでは目的の変更を実現できない場合（例：コンポーネントの置き換え、ロジックの追加、動作の変更）にオーバーライドを使用します。
• ネイティブコンポーネントを完全に置き換える場合は、{ Component: CustomComponent } を指定した components マップを使用します。
• ネイティブコンポーネントを置き換えず、props のみを変更する場合は、{ props: { ... } } を指定した components マップを使用します。
• 動作の変更とあわせてラッパーレベルのスタイルを適用する場合は、getOverriddenSection() の className オプションを使用します。
• 見た目のみを変更する場合は、デザイントークンを使ったテーマ設定を優先してください。オーバーライドはより大掛かりで、依存関係も強くなります。
• FastStore ネイティブセクションのドキュメントでオーバーライド可能と記載されているコンポーネントのみをオーバーライドしてください。ドキュメントにないコンポーネント名は無視されます。
• __experimental がプレフィックスに付いたコンポーネントはオーバーライドできますが、その props にはアクセスできず、予告なく変更される可能性があります。

厳守事項

制約：Override API を使用する — FastStore のコアは変更しない

セクションをカスタマイズするには、@faststore/core の getOverriddenSection() を必ず使用してください。node_modules/@faststore/ 内のファイルを直接変更したり、内部ソースファイルをインポートしたりしてはいけません。

重要な理由 node_modules の変更は一時的なものであり（npm install を実行すると変更が失われます）、@faststore/core/src/ のような内部パスからインポートすると実装の詳細に強く依存するため、FastStore の更新のたびに動作しなくなる可能性があります。

検出方法 @faststore/core/src/（内部ソースパス）からのインポートが見つかった場合 → 作業を停止してください。これらは非公開の実装詳細です。インポートできるのは、公開 API の @faststore/core と @faststore/core/experimental のみです。node_modules/@faststore/ 内のファイルが直接編集されている場合 → 直ちに作業を停止し、代わりにオーバーライドシステムを使用してください。

正しい例

// src/components/overrides/ProductDetails.tsx
import { getOverriddenSection } from '@faststore/core'
import { ProductDetailsSection } from '@faststore/core'

import CustomProductTitle from '../CustomProductTitle'

const OverriddenProductDetails = getOverriddenSection({
  Section: ProductDetailsSection,
  components: {
    ProductTitle: { Component: CustomProductTitle },
  },
})

export default OverriddenProductDetails

誤った例

// WRONG: Importing from internal source paths
import { ProductDetails } from '@faststore/core/src/components/sections/ProductDetails'
// This path is an implementation detail that can change without notice.
// It bypasses the public API and will break on FastStore updates.

// WRONG: Modifying node_modules directly
// Editing node_modules/@faststore/core/dist/components/ProductDetails.js
// Changes are lost on every npm install and cannot be version-controlled.

---

制約：オーバーライドファイルは src/components/overrides/ に配置する

オーバーライドファイルは必ず src/components/overrides/ ディレクトリに配置し、オーバーライドするセクションの名前を付けてください（例：ProductDetails.tsx）。

重要な理由 FastStore のビルドシステムは src/components/overrides/ をスキャンして、セクションのオーバーライドを検出し、適用します。ほかの場所に配置したファイルは検出されず、エラーメッセージも表示されないままオーバーライドが失敗し、代わりにネイティブセクションがレンダリングされます。

検出方法 src/components/overrides/ 以外のファイルにオーバーライド関連のコード（getOverriddenSection の呼び出し）がある場合 → オーバーライドが適用されないことを警告してください。ファイル名が FastStore のセクション一覧にある有効なネイティブセクション名と一致しているか確認してください。

正しい例

// src/components/overrides/Alert.tsx
// File is in the correct directory and named after the Alert section
import { getOverriddenSection } from '@faststore/core'
import { AlertSection } from '@faststore/core'

import CustomIcon from '../CustomIcon'

const OverriddenAlert = getOverriddenSection({
  Section: AlertSection,
  components: {
    Icon: { Component: CustomIcon },
  },
})

export default OverriddenAlert

誤った例

// src/components/MyCustomAlert.tsx
// WRONG: File is NOT in src/components/overrides/
// FastStore will NOT discover this override.
// The native Alert section will render unchanged.
import { getOverriddenSection } from '@faststore/core'
import { AlertSection } from '@faststore/core'

const OverriddenAlert = getOverriddenSection({
  Section: AlertSection,
  components: {
    Icon: { Component: CustomIcon },
  },
})

export default OverriddenAlert

---

制約：オーバーライド可能と文書に記載されたコンポーネントのみをオーバーライドする

FastStore のネイティブセクションのドキュメントでオーバーライド可能と記載されているコンポーネントのみをオーバーライドしてください。__experimental がプレフィックスに付いているコンポーネントもオーバーライドできますが、props にはアクセスできません。

重要な理由 オーバーライド可能と記載されていないコンポーネントをオーバーライドしようとしても、何も通知されずに失敗します。オーバーライド設定は無視され、ネイティブコンポーネントがレンダリングされます。__experimental とマークされたコンポーネントは、予告なく変更される可能性のある不安定な prop インターフェースを持っています。

検出方法 components オーバーライドマップにあるコンポーネント名が、そのセクションの FastStore オーバーライド可能コンポーネントの一覧にない場合 → このオーバーライドが機能しない可能性があることを警告してください。コンポーネント名に __experimental がプレフィックスとして付いている場合 → props にアクセスできないことと不安定であることを警告してください。

正しい例

// src/components/overrides/ProductDetails.tsx
// ProductTitle is a documented overridable component of ProductDetails section
import { getOverriddenSection } from '@faststore/core'
import { ProductDetailsSection } from '@faststore/core'

const OverriddenProductDetails = getOverriddenSection({
  Section: ProductDetailsSection,
  components: {
    ProductTitle: {
      props: {
        refNumber: true,
        showDiscountBadge: false,
      },
    },
  },
})

export default OverriddenProductDetails

誤った例

// src/components/overrides/ProductDetails.tsx
// "InternalPriceCalculator" is NOT a documented overridable component
import { getOverriddenSection } from '@faststore/core'
import { ProductDetailsSection } from '@faststore/core'

const OverriddenProductDetails = getOverriddenSection({
  Section: ProductDetailsSection,
  components: {
    // This component name does not exist in the overridable list.
    // The override will be silently ignored.
    InternalPriceCalculator: { Component: MyPriceCalculator },
  },
})

export default OverriddenProductDetails

推奨パターン

推奨されるファイル構成：

src/
├── components/
│   ├── overrides/
│   │   ├── ProductDetails.tsx    ← override file (named after section)
│   │   ├── Alert.tsx
│   │   └── simple-alert.module.scss
│   ├── CustomBuyButton.tsx       ← custom component
│   └── BoldIcon.tsx

最小限のオーバーライド — コンポーネントを置き換える：

// src/components/overrides/ProductDetails.tsx
import { getOverriddenSection } from '@faststore/core'
import { ProductDetailsSection } from '@faststore/core'

import CustomBuyButton from '../CustomBuyButton'

const OverriddenProductDetails = getOverriddenSection({
  Section: ProductDetailsSection,
  components: {
    BuyButton: { Component: CustomBuyButton },
  },
})

export default OverriddenProductDetails

コンポーネントを置き換えずに props をオーバーライドする：

// src/components/overrides/ProductDetails.tsx
import { getOverriddenSection } from '@faststore/core'
import { ProductDetailsSection } from '@faststore/core'

const OverriddenProductDetails = getOverriddenSection({
  Section: ProductDetailsSection,
  components: {
    BuyButton: {
      props: {
        size: 'small',
        iconPosition: 'left',
      },
    },
  },
})

export default OverriddenProductDetails

カスタムスタイルでオーバーライドする：

// src/components/overrides/Alert.tsx
import { getOverriddenSection } from '@faststore/core'
import { AlertSection } from '@faststore/core'
import styles from './simple-alert.module.scss'

import BoldIcon from '../BoldIcon'

const OverriddenAlert = getOverriddenSection({
  Section: AlertSection,
  className: styles.simpleAlert,
  components: {
    Icon: { Component: BoldIcon },
  },
})

export default OverriddenAlert

よくある失敗例

• オーバーライドシステムで対応できる変更に対して、node_modules/@faststore/ をモンキーパッチしたり、patch-package を使用したりする。変更はインストール時に失われ、メンテナンスの負担が増えます。
• 動作の変更にはオーバーライド API を、見た目の変更にはデザイントークンを使用せず、CSS !important で見た目を強制的に変更する。
• getOverriddenSection() を使用せず、ネイティブセクションをラップするコンポーネントを作成する。ラッパーを使用すると、CMS 連携、分析トラッキング、セクションの検出が機能しなくなります。
• オーバーライドファイルを src/components/overrides/ の外に配置する — ファイルは通知されずに無視されます。
• FastStore のオーバーライド可能コンポーネントのドキュメントに記載されていないコンポーネント名をオーバーライドする — オーバーライドは通知されずに無視されます。

レビューチェックリスト

• オーバーライドファイルは src/components/overrides/ にあり、対象セクションの名前が付けられていますか？
• ファイルでは @faststore/core の getOverriddenSection() を使用していますか？
• オーバーライドするコンポーネント名はすべて、そのセクションでオーバーライド可能と文書に記載されていますか？
• インポート元は @faststore/core または @faststore/core/experimental のみですか（内部ソースパスは使用していませんか）？
• この変更はオーバーライドではなく、デザイントークンで実現できますか？
• オーバーライドはデフォルトエクスポートされていますか？

参考資料

• オーバーライドの概要 — FastStore のオーバーライドシステムの概要と使用する場面
• getOverriddenSection 関数 — コアオーバーライド関数の API リファレンス
• ネイティブコンポーネントと props のオーバーライド — コンポーネントの props をオーバーライドする手順ガイド
• ネイティブコンポーネントのオーバーライド — ネイティブコンポーネント全体を置き換えるガイド
• ネイティブセクションとオーバーライド可能なコンポーネントの一覧 — セクションごとにオーバーライド可能なコンポーネントの完全なリファレンス
• 新しいセクションの作成 — オーバーライドでは不十分な場合にカスタムセクションを作成するガイド
• オーバーライドのトラブルシューティング — オーバーライドが機能しない場合によくある問題と解決策
• faststore-theming — オーバーライドを必要としない視覚的なカスタマイズに関連するスキル