Fragmente構築ログ：Astro 5.xと型定義の戦い

プロジェクトの目的

Fragmente（フラグメンテ）は、知識の断片（Fragments）を積み上げる場所。

哲学：「完璧を目指すな、断片を積み上げろ」

• 記事の完成度よりログを残すことを最優先
• 未完成でもログを残す。後から別の断片と繋がり、知識が形成される
• 即座に公開（draft: false）

技術スタック

• Astro 5.17.1 + Starlight 0.37.6
• TypeScript 5.9.3
• Cloudflare Pages（デプロイ先）
• Vibe Coding（Gemini + Perplexity + Claude）

セットアップの戦い

1. package.jsonが不完全

最初の npm install 後、npx astro check を実行したら必要な依存関係が不足していることが判明。

# 欠けていたパッケージ
npm install astro @astrojs/starlight
# 357パッケージ追加

教訓: プロジェクト初期化時は依存関係を手動で確認すべし。

2. Starlight social 設定の罠

Starlight v0.33.0 から social の設定構文が変更されていた。

// ❌ 古い形式（v0.32以前）
social: {
  github: 'https://github.com/...'
}

// ✅ 新しい形式（v0.33+）
social: [
  {
    label: 'GitHub',
    icon: 'github',
    href: 'https://github.com/...'
  }
]

しかし最終的にはプライベートリポジトリのため、social 設定自体を削除した。

3. awesome-altitude の亡霊

npx astro check を実行したら、謎の awesome-altitude ディレクトリ内で 97個の TypeScript エラー が発生。

Cannot find module 'astro/errors'
Consider updating to 'node16', 'nodenext', or 'bundler'.

原因は2つ:

1. tsconfig.json が存在しない
2. awesome-altitude ディレクトリが不要な残骸

解決策:

rm -rf awesome-altitude

4. TypeScript 設定の正解

Astro 5.x では、tsconfig.json をシンプルに保つのが正解。

tsconfig.json の最小構成:

{
  "extends": "astro/tsconfigs/base"
}

これだけで Astro が適切な moduleResolution を設定してくれる。

5. src/content/config.ts のミス

SETUP.md にあった設定をそのまま使ったら、空の extend でエラー。

// ❌ エラー
export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      extend: (z) => ({
        // 空のオブジェクト
      }),
    }),
  }),
};

// ✅ 正解（カスタムフィールド不要なら extend ごと削除）
export const collections = {
  docs: defineCollection({
    schema: docsSchema(),
  }),
};

6. ロゴファイルがないと起動しない

astro.config.mjs で logo を指定していたが、ファイルが存在しなかった。

logo: {
  src: './src/assets/logo.svg',
}

シンプルな「F」のSVGアイコンを作成して解決:

<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100' width='32' height='32'>
  <rect width='100' height='100' rx='20' fill='#202020' />
  <text x='50' y='70' font-family='sans-serif' font-size='60' font-weight='bold' text-anchor='middle' fill='#ffffff'>F</text>
</svg>

学んだこと

1. エラーが出たら推測せずPerplexityで検証する

Vibe Coding の原則：

• Claude が1回で直せないエラー → 即座に停止
• Perplexity で最新の正しい情報を確認
• Gemini で実装指示を再構築

これにより、Claude のハルシネーション（古い知識による誤った修正）を防ぐ。

2. npx astro check は偉大

型チェックツールは開発初期から活用すべき。エラーを早期発見できる。

npx astro check
# Result: 0 errors, 0 warnings, 0 hints

この一行が、全てが正しく設定されていることを保証してくれる。

3. ドキュメントのバージョン確認が重要

Starlight は v0.33.0 で breaking change があったが、古いドキュメントをそのまま使うとエラーになる。

対策:

• Perplexity で「2026年2月現在」と明記して検証
• 公式 CHANGELOG を確認

4. SESSION_LOG.md の重要性

セットアップ中のエラーと解決策を記録することで：

• 同じ問題に再度直面した時に即座に解決できる
• 未来の自分への引き継ぎ書になる
• この記事のネタになる

最終構成

fragmente/
├── src/
│   ├── assets/
│   │   └── logo.svg          # Fアイコン
│   ├── content/
│   │   ├── docs/
│   │   │   ├── index.mdx     # トップページ
│   │   │   ├── tech/         # 技術断片
│   │   │   └── journal/      # 思考断片
│   │   └── config.ts         # シンプルなschema
│   └── env.d.ts              # Astro型定義
├── docs/
│   ├── SESSION_LOG.md        # 進捗記録
│   └── SPEC.md               # 仕様書
├── astro.config.mjs          # Starlight設定
├── tsconfig.json             # astro/tsconfigs/base継承
└── package.json              # 依存関係

次のステップ

1. 開発サーバー起動: npm run dev
2. Cloudflare Pages デプロイ設定
3. 断片を積み上げる

完璧を目指さない。今日の理解を記録する。それが Fragmente の精神。

---

この記事自体が断片: セットアップの記録として残すことで、未来の誰かの時間を節約できるかもしれない。