動的ルート

paths() を使って [slug].tsx や [...slug].tsx ページがビルドすべき具体的な URL を列挙し、URL ごとの props をコンポーネントへ渡す。

このページで扱う内容

paths() が、動的ページやキャッチオールページが出力すべき URL をどう列挙するか、それが返す { params, props } の契約、そしてページコンポーネントがそのデータをどう受け取るかを解説します。静的ルートの基礎については Routing を参照してください。

動的ルート — pages/blog/[slug].tsx — は単一の URL にマッピングされません。角かっこで囲まれたセグメントはパラメータであり、zfb はビルド時にそれをどの具体的な値で埋めればよいかを知る必要があります。それが paths() の仕事です。

キャッチオールルート — pages/docs/[...slug].tsx — も同じように動作しますが、その slug パラメータは単一のセグメントではなく、末尾の 1 つ以上のセグメントをキャプチャします。

`paths()` の契約

paths() は { params, props } オブジェクトの配列を返します。同期的に返しても、 Promise として返しても構いません。ルーターはその配列を消費し、1 エントリが 1 つのレンダリング済み URL になります。

type PathEntry<P = Record<string, unknown>> = {
  /** Values for the bracketed segments, keyed by parameter name. */
  params: Record<string, string | string[]>;
  /** Optional per-URL data threaded to the page component as `props`. */
  props?: P;
};

export function paths(): PathEntry[] | Promise<PathEntry[]>;

params のキーは、ファイル名の角かっこ内の名前と一致する必要があります。 [slug].tsx ならキーは slug です。[lang]/[slug].tsx なら lang と slug の両方を指定します。キャッチオール [...slug].tsx では、slug は末尾セグメントの string[] です。
props はオプションで、エンジンにとっては不透明な、あなたが管理するデータです。ただし props という名前のネストしたオブジェクトとしてコンポーネントへ渡されるわけでは ありません。各キーは params と並んで、コンポーネントの props の トップレベルに展開（spread） されます。paths() のエントリが props: { title: "..." } を返した場合、コンポーネントが受け取るのは { params, title } であり、 { params, props: { title } } ではありません。props のキーが params と衝突した場合は props 側の値が優先されます。

ソースとコンパイル済み entrypoint

動的ルートには、プロジェクトページでも injectRoute で登録したコンパイル済み .js モジュールでも、ESM の paths export が必要です。コンパイル出力では、ローカル binding を export clause で公開する形がよく使われます。

function paths() {
  return [{ params: { slug: "intro" } }];
}
export { paths };

zfb はこのローカル export-clause 形式を認識します。戻り値が静的にリテラルなら直接 URL を列挙できます。paths() が import、collection、非同期処理、その他の非リテラルなコードに依存するときは、ルート列挙中に実行時の export を評価します。そのためパッケージはビルド済みの dist/ ルートを直接注入でき、元の .tsx entrypoint を並行して用意する必要はありません。これはファイルシステムの検出を変更しません。pages/ に置いた .js ファイルはユーザーページとしてスキャンされません。

ブログ記事ページ

paths() の典型的な用途は、コンテンツコレクションから slug を列挙することです。

// pages/blog/[slug].tsx
import { getCollection } from "zfb/content";

export const frontmatter = { title: "Blog post" };

export function paths() {
  const posts = getCollection("blog");
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { title: post.data.title },
  }));
}

export default function BlogPost({ params, title }) {
  const post = getCollection("blog").find((e) => e.slug === params.slug);
  if (!post) return <p>Not found.</p>;
  return (
    <article>
      <h2>{title}</h2>
      <post.Content />
    </article>
  );
}

いくつか注目すべき点があります。

getCollection は同期的です。完全なコンテンツのスナップショットは、どの TSX が実行されるよりも前に Rust 側で事前構築されています。そのため、この例では async は不要です。ルート列挙に async module loading や Promise を返す別のヘルパーが必要な場合は、export async function paths() を使ってください。
params.slug が URL に現れるものです。slug: "hello-zfb" の記事は /blog/hello-zfb になります。
title は — props に入れた他のキーと同様に — エンジンにとって不透明です。props というキーの下にネストされるのではなく、上で説明したとおり params と並んでコンポーネントのトップレベル props に展開されて届きます。シリアライズ可能なものなら何でも入れられます。

キャッチオール: ツリー全体のドキュメントページ

キャッチオールルートは末尾セグメントを任意の数だけキャプチャします。同じテンプレートが 1 つのプレフィックスの下で多くの深さをレンダリングする場合に便利です。slug パラメータは string[] として到着します。

// pages/docs/[...slug].tsx
import { getCollection } from "zfb/content";

export const frontmatter = { title: "Docs" };

export function paths() {
  const entries = getCollection("docs");
  return entries.map((entry) => ({
    // entry.slug looks like "guides/setup" or "concepts/routing"
    params: { slug: entry.slug.split("/") },
  }));
}

export default function DocsPage({ params }) {
  const slugPath = params.slug.join("/");
  const entry = getCollection("docs").find((e) => e.slug === slugPath);
  if (!entry) return <p>Not found.</p>;
  return <entry.Content />;
}

/docs/concepts/routing は params.slug === ["concepts", "routing"] でマッチします。/docs/guides/setup は params.slug === ["guides", "setup"] でマッチします。エントリをスラッシュ区切りの形で検索する必要があるときは、ルーターがその形（slug.join("/")）を再構築します。

静的・動的・キャッチオール — どう組み合わさるか

ファイル名	種類	URL の例	`params` の形
`pages/about.tsx`	静的	`/about`	なし
`pages/blog/[slug].tsx`	動的	`/blog/hello-zfb`	`{ slug: string }`
`pages/docs/[...slug].tsx`	キャッチオール	`/docs/a/b/c`	`{ slug: string[] }`
`pages/docs/[[...slug]].tsx`	オプショナルキャッチオール	`/docs` と `/docs/a/b/c`	`{ slug: string[] }`（素の URL では `[]`）
`pages/[lang]/[slug].tsx`	動的 × 2	`/ja/intro`	`{ lang: string, slug: string }`

2 つのパターンが同じ URL にマッチしうる場合は、より具体的なほうが勝ちます。静的が動的に勝ち、動的がキャッチオールに勝ちます。 ルーターはルートテーブルを構築するときにこれを強制します。完全なソート順については Routing を参照してください。

ルールと落とし穴

すべての params キーには値が必要です。キーが欠けていると、HTML が 1 つでも書き出される前にビルドエラーが発生します。
キャッチオールセグメントでは、params.slug は（要素が 1 つでも） string[] でなければなりません。素の文字列を渡すと型エラーになります。
必須キャッチオール（[...slug]）は空配列を拒否します。常に少なくとも 1 つのセグメントが必要です。素のディレクトリ URL（/docs）をビルドするには、ファイルをオプショナル形（[[...slug]]）にリネームし、明示的に { params: { slug: [] } } エントリを返してください。[""] と "" はどちらの形でも無効のままです。
paths() は 同期的にも async にも できます。コンテンツのスナップショット全体は、どのページが評価されるよりも前に読み込まれるため、コンテンツだけのルートはたいてい同期のままで十分です。Promise を返す paths() export もサポートされています。結果は純粋なデータで決定論的に保ってください。ルーターはレンダーのはるか前、ルート列挙の段階でこれを呼び出します。
ルート列挙はルートごと・ビルドごとに 1 回だけ行われます。静的にリテラルな paths の結果はモジュールを実行せずに読み取れます。実行時の paths() の結果は 1 回評価され、その後メモ化されて同じルートテンプレートからレンダリングされるすべてのページで再利用されます。paths() 内のエントリごとの処理（コレクションのマッピングなど）は安全で、出力 URL ごとに繰り返されることはありません。
同じテンプレートに解決される 2 つのルートは、ビルド時に RouterError::AmbiguousRoute を発生させます。また、2 つのルートがパラメータ名だけ異なり、同じ URL にマッチする場合（たとえば docs/[a].tsx と docs/[b].tsx）には RouterError::AmbiguousShape を、オプショナルキャッチオールが同じ位置で別のルートと重なる場合には RouterError::OptionalCatchallConflict を発生させます。ルーターが黙って勝者を選ぶことは決してありません。