データ

zfb で構造化データを取り込む 3 つの選択肢 — コンテンツコレクション、フロントマターのみのエントリ、プレーンな TS モジュール。

zfb は構造化データをページに取り込むための 3 つの異なる経路を用意しています。どれが正しい 選択かは、データの形と、その周りにどれだけの手続きを求めるかによって決まります。

1. コンテンツコレクション

データが 文章 のとき（ブログ記事、ドキュメント記事、レシピなど）はコンテンツコレクションを 使います。各エントリはフロントマター付きの Markdown ファイルで、フロントマターはスキーマに 対して検証され、本文はあなたのために HTML へレンダリングされます。詳しくは Content Collections を参照してください。

各エントリの本文が読まれることを意図している場合は、常にこれが正しい選択です。

2. フロントマターのみのエントリによる構造化レコード

データが 構造化されている とき（製品のリスト、チームメンバーのディレクトリ、料金ティアの 集合など）は、すべてのデータをフロントマターに持ち本文を空にしたエントリからなるコンテンツ コレクションを使えます。コレクションウォーカーは .md と .mdx ファイルを受け付けます。 フロントマターブロックだけで本文を持たないファイルは、まったく問題ありません。

---
name: "Widget Pro"
price: 49
featured: true
---

ディレクトリを zfb.config.ts で宣言し、フィールドごとの検証のために任意の schema を 指定します（defineConfig を参照）。

export default {
  collections: [
    {
      name: "products",
      path: "data/products",
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          price: { type: "number" },
          featured: { type: "boolean" },
        },
        required: ["name", "price"],
      },
    },
  ],
};

エントリはコンテンツエントリと同じ方法でロードします。entry.data には検証済みの フロントマターが入ります。entry.Content は（空の）本文をレンダリングするもので、無視して 構いません。

import { getCollection } from "zfb/content";

const products = getCollection("products");

この方法が真価を発揮するのは、エントリ単位のスキーマ検証、slug の導出、そして文章コンテンツと 同じ getCollection API が欲しいけれど、Markdown の本文は必須にしたくない、というときです。

3. data/ 配下のプレーンな TS モジュール

それ以外すべて（小さなルックアップ、ヘルパー関数、導出された定数など）には、通常の TypeScript モジュールが最も軽量な経路です。

// data/site.ts
export const siteName = "My Site";

export function formatDate(date: Date) {
  return date.toISOString().slice(0, 10);
}

任意のページやコンポーネントからインポートします。

import { siteName, formatDate } from "../data/site";

スキーマも slug もエントリ単位のオーバーヘッドもありません。「コレクション」というフレーミングが、 そのデータに見合う以上の手続きになってしまう場合に使います。

正しいツールを選ぶ

役に立つ目安:

• データが 読まれることを意図したコンテンツ → コンテンツコレクション。

• データが 同じ形を共有し、エントリ単位の検証から恩恵を受ける構造化レコード → コレクション内のフロントマターのみの .md エントリ。

• データが ひと握りの定数やヘルパー → data/ 配下の TS モジュール。

3 つすべてを同じプロジェクトの中で衝突なく混在させられます。