content-collections

Content Collections

ステータス: 本番環境対応済み ✅ 最終更新日: 2025-11-07 依存関係: なし 最新バージョン: @content-collections/[email protected]、@content-collections/[email protected]、[email protected]

---

Content Collections とは？

Content Collections は、ローカルのコンテンツファイル（Markdown/MDX）を、ビルド時の自動検証を備えた型安全な TypeScript データに変換します。

解決する問題: コンテンツの手動パース、型安全性の欠如、無効なフロントマターによる実行時エラー。

仕組み:

1. content-collections.ts でコレクションを定義します（名前、ディレクトリ、Zod スキーマ）
2. CLI／プラグインがファイルシステムをスキャンし、フロントマターをパースして、スキーマに照らして検証します
3. .content-collections/generated/ に TypeScript モジュールを生成します
4. コレクションをインポートします: import { allPosts } from "content-collections"

最適な用途: ブログ、ドキュメントサイト、Cloudflare Workers、Vite、Next.js を利用するコンテンツ中心のアプリ。

---

クイックスタート（5 分）

1. 依存関係をインストールする

# Bun (recommended)
bun add -d @content-collections/core @content-collections/vite zod

# npm
npm install -D @content-collections/core @content-collections/vite zod

# pnpm
pnpm add -D @content-collections/core @content-collections/vite zod

2. TypeScript のパスエイリアスを設定する

tsconfig.json に追加します:

{
  "compilerOptions": {
    "paths": {
      "content-collections": ["./.content-collections/generated"]
    }
  }
}

3. Vite プラグインを設定する

vite.config.ts に追加します:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import contentCollections from "@content-collections/vite";

export default defineConfig({
  plugins: [
    react(),
    contentCollections(), // MUST come after react()
  ],
});

4. .gitignore を更新する

.content-collections/

5. コレクション設定を作成する

プロジェクトのルートに content-collections.ts を作成します:

import { defineCollection, defineConfig } from "@content-collections/core";
import { z } from "zod";

const posts = defineCollection({
  name: "posts",
  directory: "content/posts",
  include: "*.md",
  schema: z.object({
    title: z.string(),
    date: z.string(),
    description: z.string(),
    content: z.string(),
  }),
});

export default defineConfig({
  collections: [posts],
});

6. コンテンツディレクトリを作成する

mkdir -p content/posts

content/posts/first-post.md を作成します:

---
title: My First Post
date: 2025-11-07
description: Introduction to Content Collections
---

# My First Post

Content goes here...

7. インポートして使用する

import { allPosts } from "content-collections";

console.log(allPosts); // Fully typed!

結果: オートコンプリート、検証、HMR を備えた型安全なコンテンツが利用できます。

---

重要なルール

✅ 必ず行うこと:

1. tsconfig.json にパスエイリアスを追加する - インポートを機能させるために必要です
2. .content-collections を .gitignore に追加する - 生成ファイルはコミットしないでください
3. Standard Schema バリデーターを使用する - Zod、Valibot、ArkType に対応しています
4. スキーマに content フィールドを含める - フロントマターのパースに必要です
5. 変換処理内で compileMDX を await する - MDX のコンパイルは非同期です
6. Vite では react() の後に contentCollections() を配置する - プラグインの順序が重要です

❌ 絶対に行わないこと:

1. .content-collections ディレクトリをコミットする - 常に生成されるため、コミットしないでください
2. 標準準拠でないバリデーターを使用する - StandardSchema 仕様への対応が必要です
3. 設定変更後に開発サーバーを再起動し忘れる - 新しいコレクションには再起動が必要です
4. 非同期処理で同期変換を使用する - 変換処理は非同期である必要があります
5. パスエイリアスを二重にラップする - ./content-collections ではなく content-collections を使用します
6. 誤ったパッケージからインポートする - 設定には @content-collections/core、データには content-collections を使用します

---

既知の問題を防ぐ

問題 #1: モジュールが見つかりません: 'content-collections'

エラー: Cannot find module 'content-collections' or its corresponding type declarations

発生する理由: TypeScript のパスエイリアス設定がありません。

防止方法:

tsconfig.json に追加します:

{
  "compilerOptions": {
    "paths": {
      "content-collections": ["./.content-collections/generated"]
    }
  }
}

VS Code で TypeScript サーバーを再起動します: Cmd+Shift+P → "TypeScript: Restart TS Server"

出典: よくあるユーザーエラー

---

問題 #2: Vite が絶えず再起動するループ

エラー: 開発サーバーが継続的に再起動し、無限ループになります。

発生する理由: Vite が .content-collections ディレクトリの変更を監視しており、それによって再生成が引き起こされます。

防止方法:

1. .gitignore に追加します:

.content-collections/

2. まだ発生する場合は、vite.config.ts に追加します:

export default defineConfig({
  server: {
    watch: {
      ignored: ["**/.content-collections/**"],
    },
  },
});

出典: GitHub Issue #591（TanStack Start）

---

問題 #3: 変換後の型が反映されない

エラー: TypeScript の型が変換後のドキュメントと一致しません。

発生する理由: TypeScript は変換関数の戻り値の型を自動的に推論しません。

防止方法:

変換の戻り値の型を明示的に指定します:

const posts = defineCollection({
  name: "posts",
  // ... schema
  transform: (post): PostWithSlug => ({ // Type the return!
    ...post,
    slug: post._meta.path.replace(/\.md$/, ""),
  }),
});

type PostWithSlug = {
  // ... schema fields
  slug: string;
};

出典: GitHub Issue #396

---

問題 #4-8：高度なトラブルシューティング

references/advanced-troubleshooting.md で扱うその他の問題：

問題	エラー	すぐにできる対処
#4	コレクションが更新されない	glob パターンを確認し、開発サーバーを再起動する
#5	MDX/Shiki のエラー	互換性のあるバージョンを使用する（shiki ^1.0.0）
#6	MDX のパスエイリアスが機能しない	MDX のインポートでは相対パスを使用する
#7	検証エラーの内容が不明瞭	Zod のカスタムエラーメッセージを追加する
#8	Ctrl+C で停止できない	kill -9 を使用するか、watch コマンドを別途実行する

---

設定パターン

パターン	用途	テンプレート
基本的なブログ	単一のコレクション、Markdown のみ	templates/content-collections.ts
複数コレクション	投稿 + ドキュメント、ネストされたフォルダー	templates/content-collections-multi.ts
変換関数	計算フィールド（slug、readingTime）	references/transform-cookbook.md を参照
MDX + React	シンタックスハイライト、React コンポーネント	templates/content-collections-mdx.ts

スキーマパターン（日時、タグ、検証）の詳細については、references/schema-patterns.md を読み込んでください。

---

React コンポーネントとの統合

React でのコレクションの使用

import { allPosts } from "content-collections";

export function BlogList() {
  return (
    <ul>
      {allPosts.map((post) => (
        <li key={post._meta.path}>
          <h2>{post.title}</h2>
          <p>{post.description}</p>
          <time>{post.date}</time>
        </li>
      ))}
    </ul>
  );
}

---

MDX コンテンツのレンダリング

import { MDXContent } from "@content-collections/mdx/react";

export function BlogPost({ post }: { post: { mdx: string } }) {
  return (
    <article>
      <MDXContent code={post.mdx} />
    </article>
  );
}

---

Cloudflare Workers へのデプロイ

Content Collections はCloudflare Workers に最適です（ビルド時のみ使用し、実行時のファイルシステムは不要です）。設定にはテンプレート templates/wrangler.toml を使用してください。

パターン：vite build → wrangler deploy（Vite プラグインが content-collections を自動的に処理します）

デプロイの詳細なガイドについては、references/deployment-guide.md を読み込んでください。

---

同梱リソース

テンプレート（コピーしてすぐに使える9個のファイル）

content-collections.ts、content-collections-multi.ts、content-collections-mdx.ts、tsconfig.json、vite.config.ts、BlogList.tsx、BlogPost.tsx、blog-post.md、wrangler.toml

スクリプト

init-content-collections.sh - 1つのコマンドでセットアップを自動化

---

依存関係

必須

{
  "devDependencies": {
    "@content-collections/core": "^0.12.0",
    "@content-collections/vite": "^0.2.7",
    "zod": "^3.23.8"
  }
}

オプション（MDX）

{
  "devDependencies": {
    "@content-collections/markdown": "^0.1.4",
    "@content-collections/mdx": "^0.2.2",
    "shiki": "^1.0.0"
  }
}

---

公式ドキュメント

• 公式サイト：https://www.content-collections.dev
• ドキュメント：https://www.content-collections.dev/docs
• GitHub：https://github.com/sdorra/content-collections
• Vite プラグイン：https://www.content-collections.dev/docs/vite
• MDX 統合：https://www.content-collections.dev/docs/mdx

---

パッケージのバージョン（2025-11-07に確認）

パッケージ	バージョン	状態
@content-collections/core	0.12.0	✅ 最新の安定版
@content-collections/vite	0.2.7	✅ 最新の安定版
@content-collections/mdx	0.2.2	✅ 最新の安定版
@content-collections/markdown	0.1.4	✅ 最新の安定版
zod	3.23.8	✅ 最新の安定版

---

簡単なトラブルシューティング

問題	解決策
TypeScript がモジュールを見つけられない	tsconfig.json にパスエイリアスを追加し、TS サーバーを再起動する
Vite が何度も再起動する	.content-collections/ を .gitignore に追加する
変更が反映されない	開発サーバーを再起動し、glob パターンを確認する
MDX のコンパイルエラー	Shiki のバージョンに互換性があるか確認する
検証エラーの内容が不明瞭	Zod のカスタムエラーメッセージを追加する

---

参照資料を読み込むタイミング

参照資料	読み込むタイミング
schema-patterns.md	複雑なスキーマ、日時の検証、オプションフィールドを設定するとき
transform-cookbook.md	計算フィールド、非同期変換、スラッグを追加するとき
mdx-components.md	MDX で React コンポーネントやシンタックスハイライトを統合するとき
deployment-guide.md	Cloudflare Workers やその他のプラットフォームにデプロイするとき
advanced-troubleshooting.md	問題 #4-8（ファイル監視、パスエイリアス、プロセスのハング）が発生したとき

---

完全セットアップチェックリスト

• @content-collections/core と @content-collections/vite をインストールしました
• スキーマ検証用に zod をインストールしました
• tsconfig.json にパスエイリアスを追加しました
• vite.config.ts に contentCollections() を追加しました（react() の後）
• .content-collections/ を .gitignore に追加しました
• プロジェクトのルートに content-collections.ts を作成しました
• コンテンツディレクトリ（例：content/posts/）を作成しました
• Zod スキーマを使ってコレクションを定義しました
• frontmatter を含む最初のコンテンツファイルを作成しました
• React コンポーネントでコレクションをインポートしました
• 型が機能することを確認しました（自動補完）
• ホットリロードをテストしました（コンテンツファイルを変更）