Astro Content Collectionsの使い方。スキーマ定義から型の使い回しまで

Markdownの記事が増えてくると、タイトルや公開日、カテゴリの書き忘れが気になってくる。Content Collectionsを使うと、記事をひとまとまりのデータとして扱いながら、決めた形式に沿っているかをビルド時にチェックできる。 Content Collectionsは「同じ形を持つコンテンツの集まり」のこと。ブログ記事なら、どの記事にもタイトル・説明文・公開日・カテゴリがある、という共通ルールを作れる。ローカルのMarkdownだけでなく、JSONやYAML、CMSやAPIから取得したデータも同じ仕組みで扱える。

Content Collectionsの定義はsrc/content.config.tsに書く。「どこから記事を集めるか」を決めるのがローダー、「集めた記事がどんな形か」を決めるのがスキーマだ。 このブログではglob()ローダーでsrc/content/blog配下のMarkdownを読み込み、スキーマはZodというバリデーションライブラリで組み立てている。

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';
import { categorySlugs } from './data/categories';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: ({ image }) => z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    category: z.enum(categorySlugs),
    tags: z.array(z.string()).optional(),
    // 実際にはサムネイル・会話データなどの項目がこの後に続く
  }),
});

export const collections = { blog };

Zodの便利なところは、「文字列であること」よりもう一歩踏み込んだ制約を書けることだ。 たとえばカテゴリはz.enum(categorySlugs)にしてある。categorySlugsはsrc/data/categories.tsで定義しているカテゴリのslug一覧で、ここに無い値を書くとビルドが失敗する。

category: z.enum(categorySlugs),   // daily / money / travel ... 以外は弾く
pubDate: z.coerce.date(),          // 文字列をDateへ変換。日付にならない値はエラー
tags: z.array(z.string()).optional(),
needsReview: z.boolean().optional().default(false),

z.coerce.date()は、Markdownに書いた2026-07-27のような文字列をDateオブジェクトへ変換してくれる。日付として解釈できない値を書いた場合はその場でエラーになるので、並び替えたときに初めて順番のおかしさに気づく、ということがなくなる。.optional()を付けた項目は省略でき、.default(false)まで付ければ、書かなかったときの値まで1か所で決められる。

スキーマの定義が({ image }) => z.object({...})という形になっているのは、Astroが渡してくれるimage()ヘルパーを使うためだ。

thumbnail: z
  .object({
    src: image(),
    alt: z.string(),
  })
  .optional(),

image()で受け取ったパスは、ただの文字列ではなくAstroの画像アセットとして扱われる。存在しないファイルを指していればビルドで止まり、実在すれば最適化やサイズ指定の対象になる。記事側では../../assets/blog/<slug>/thumbnail.pngのように、Markdownファイルからの相対パスで書く。

定義したコレクションはgetCollection('blog')でまとめて取得できる。返ってくる各記事には、ファイル名から作られるidと、スキーマに沿ったdataが入っている。 注意したいのは、取得順が保証されていないこと。日付順に見せたいなら自分で並べ替える必要がある。このブログでは取得と並べ替えをまとめた関数を1つ用意して、一覧ページから共通で呼んでいる。

import { getCollection, type CollectionEntry } from 'astro:content';

export async function getAllPosts(): Promise<CollectionEntry<'blog'>[]> {
  const all = await getCollection('blog');
  return all.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
}

ここからが、Content Collectionsを使っていて一番おいしいと感じている部分だ。 スキーマで決めた形は、実行時のチェックに使われるだけでなく、TypeScriptの型としても取り出せる。CollectionEntry<'blog'>['data']と書けば記事データ全体の型が手に入り、そこからさらにキーをたどれば一部だけの型も取り出せる。

import type { CollectionEntry } from 'astro:content';

// 会話1ターン分の型をスキーマから導出する
export type ConversationTurn = CollectionEntry<'blog'>['data']['conversation'][number];

// 任意項目は、値が入っている場合の形だけをNonNullableで取り出す
export type TurnImage = NonNullable<ConversationTurn['image']>;
export type TurnLink = NonNullable<ConversationTurn['link']>;

最後に、スキーマを活かすための習慣を1つ。 記事を書いたら、まずastro checkで型とスキーマの問題を確認し、そのあと本番ビルドまで通す。Content Collectionsのチェックはビルド時に走るので、ここを省くと「書いたつもりで抜けている項目」に気づけない。

pnpm astro check
pnpm build