前提

• Claude Code がインストール済みであること
• ~/.claude/settings.json または .claude/settings.json を編集できること
• Hook 内で実行するコマンド（Prettier・型チェッカー等）がプロジェクトに導入されていること

Hooks とは

Hooks は「Claude Code がツールを呼び出すとき」や「ファイルを変更したとき」などのイベントに反応して、指定したコマンドを自動実行する仕組みです。

Git の pre-commit hook に似ていますが、Claude Code 固有のイベントに対応しています。

設定方法

~/.claude/settings.json または .claude/settings.json に Hooks を定義します。

{
	"hooks": {
		"PreToolUse": [
			{
				"matcher": "Edit|Write",
				"hook": "echo 'ファイルを変更します'"
			}
		],
		"PostToolUse": [
			{
				"matcher": "Edit|Write",
				"hook": "pnpm lint --fix"
			}
		]
	}
}

イベントの種類

実用的な Hook の例

1. ファイル変更時に自動フォーマット

{
	"hooks": {
		"PostToolUse": [
			{
				"matcher": "Edit|Write",
				"hook": "prettier --write $CLAUDE_FILE_PATH"
			}
		]
	}
}

Claude Code がファイルを編集・作成するたびに、Prettier で自動フォーマットされます。

2. ファイル変更時に型チェック

{
	"hooks": {
		"PostToolUse": [
			{
				"matcher": "Edit|Write",
				"hook": "pnpm check 2>&1 | head -20"
			}
		]
	}
}

3. 特定のファイルの変更をブロック

{
	"hooks": {
		"PreToolUse": [
			{
				"matcher": "Edit|Write",
				"hook": "if echo $CLAUDE_FILE_PATH | grep -q '.env'; then echo 'BLOCK: .env ファイルの変更は許可されていません' && exit 1; fi"
			}
		]
	}
}

.env ファイルの変更を防止します。Hook が非ゼロで終了すると、ツールの実行がブロックされます。

4. 応答完了時に通知

{
	"hooks": {
		"Stop": [
			{
				"hook": "osascript -e 'display notification \"Claude Code の作業が完了しました\" with title \"Claude Code\"'"
			}
		]
	}
}

長いタスクの完了をデスクトップ通知で知らせます（macOS の場合）。

matcher パターン

matcher にはツール名の正規表現を指定します。

// Edit または Write ツールにマッチ
"matcher": "Edit|Write"

// Bash ツールにマッチ
"matcher": "Bash"

// すべてのツールにマッチ
"matcher": ".*"

環境変数

Hook のコマンド内では、以下の環境変数が使えます:

ブロックの仕組み

PreToolUse の Hook が以下の条件を満たすと、ツールの実行がブロックされます:

1. 終了コードが非ゼロ
2. stdout に BLOCK: で始まるメッセージがある

# ブロックする場合
echo "BLOCK: この操作は許可されていません" && exit 1

# ブロックしない場合（情報表示のみ）
echo "INFO: ファイルを変更します"

設定のスコープ

プロジェクト固有の Hook は、チームで共有できます（Git にコミット可能）。

注意点

• Hook のコマンドが長時間実行されると、Claude Code の応答が遅くなる
• エラーが発生した場合、Claude Code のフィードバックとして表示される
• Hook は同期的に実行される

まとめ

• Hooks はイベント駆動で自動コマンドを実行する機能
• PreToolUse でツール実行前のチェック、PostToolUse で後処理
• ファイルの自動フォーマット、型チェック、変更のブロックなどに活用
• settings.json で設定し、プロジェクト単位で管理できる

参照

• Claude Code Hooks ドキュメント

前提

• Claude Code がインストール済みであること
• プロジェクトにテストランナー（Vitest / Jest など）が導入されていること
• 本記事のサンプルコードは Vitest + vitest-browser-svelte を使った SvelteKit プロジェクトを想定

Claude Code とテスト

Claude Code はテストに関して以下のことができます:

• テストコードの生成
• テストの実行と結果の確認
• 失敗したテストの原因分析と修正
• テストカバレッジの確認

基本的なワークフロー

1. テストを書いてもらう

src/lib/utils/posts.ts の getAllPosts 関数のテストを書いて

Claude Code はソースコードを読み、適切なテストを生成します。

// src/lib/utils/posts.test.ts
import { describe, expect, it } from 'vitest';
import { getAllPosts } from './posts';

describe('getAllPosts', () => {
	it('記事が日付の降順で返される', async () => {
		const posts = await getAllPosts();
		for (let i = 1; i < posts.length; i++) {
			expect(new Date(posts[i - 1].date).getTime()).toBeGreaterThanOrEqual(
				new Date(posts[i].date).getTime()
			);
		}
	});

	it('下書き記事が含まれない', async () => {
		const posts = await getAllPosts();
		expect(posts.every((p) => !p.draft)).toBe(true);
	});

	it('すべての記事に必須フィールドがある', async () => {
		const posts = await getAllPosts();
		for (const post of posts) {
			expect(post.slug).toBeTruthy();
			expect(post.title).toBeTruthy();
			expect(post.date).toBeTruthy();
		}
	});
});

2. テストを実行する

テストを実行して

Claude Code が pnpm test を実行し、結果を確認します。

3. 失敗したテストを修正

失敗しているテストを確認して修正して

失敗の原因を分析し、テストコードまたは実装コードを修正します。

TDD のサイクル

Claude Code で TDD（Red → Green → Refactor）を回すことができます。

Red: まずテストを書く

記事をタグでフィルタリングする関数のテストを先に書いて。
関数はまだ実装しなくていい。

describe('getPostsByTag', () => {
	it('指定したタグの記事だけ返される', async () => {
		const posts = await getPostsByTag('svelte');
		expect(posts.length).toBeGreaterThan(0);
		expect(posts.every((p) => p.tags.includes('svelte'))).toBe(true);
	});

	it('存在しないタグは空配列を返す', async () => {
		const posts = await getPostsByTag('nonexistent-tag');
		expect(posts).toEqual([]);
	});
});

Green: テストを通す実装を書く

テストが通るように getPostsByTag 関数を実装して

Refactor: リファクタリング

テストが通ったまま、コードをリファクタリングして

コンポーネントテストの生成

PostCard コンポーネントのテストを書いて

// src/lib/components/blog/PostCard.svelte.test.ts
import { render } from 'vitest-browser-svelte';
import { expect, test } from 'vitest';
import PostCard from './PostCard.svelte';

test('記事タイトルが表示される', async () => {
	const screen = render(PostCard, {
		slug: 'test',
		title: 'テスト記事',
		description: '説明文',
		date: '2026-03-28',
		tags: ['svelte']
	});

	await expect.element(screen.getByText('テスト記事')).toBeVisible();
});

test('タグがバッジとして表示される', async () => {
	const screen = render(PostCard, {
		slug: 'test',
		title: 'テスト記事',
		description: '説明文',
		date: '2026-03-28',
		tags: ['svelte', 'typescript']
	});

	await expect.element(screen.getByText('svelte')).toBeVisible();
	await expect.element(screen.getByText('typescript')).toBeVisible();
});

効果的な指示のコツ

エッジケースを意識させる

getAllPosts のテストを書いて。
特に以下のケースを含めて:
- 記事が0件の場合
- draft: true の記事がある場合
- 日付が同じ記事が複数ある場合

テストの種類を指定する

ユニットテストだけ書いて（外部依存なし）
インテグレーションテストを書いて（実際のファイルシステムを使う）

既存のテストのスタイルに合わせる

既存のテストファイルのスタイルに合わせて書いて

Claude Code は既存のテストコードを読み、同じスタイル（describe/it の構造、アサーションの書き方）に合わせます。

テスト実行の自動化

テストを実行して、失敗があればすべて修正して。
全部通るまで繰り返して。

Claude Code はテスト → 修正のサイクルを自動で回してくれます。

まとめ

• Claude Code にテスト生成を任せると、基本的なケースからエッジケースまでカバーできる
• TDD のサイクル（Red → Green → Refactor）を AI と一緒に回せる
• 失敗したテストの原因分析と修正も自動化できる
• 既存のテストスタイルに合わせたコード生成が可能

参照

• Claude Code ドキュメント

前提

• Claude Code がインストール済みで、ターミナルから claude を起動できること
• 調査対象のコードベースが手元にあること（Plan モードはファイルを読んで設計するため）

Plan モードとは

Plan モードは、Claude Code に「読み取り専用」の制約を課すモードです。ファイルの読み込みや検索はできますが、ファイルの編集やコマンドの実行は行いません。

Plan モードの起動

/plan タグフィルタリング機能を追加したい

または、会話の途中で:

Plan モードに切り替えて

ワークフロー

Plan モードは以下のフェーズで進みます。

Phase 1: 調査

Claude Code がコードベースを探索して、現状を理解します。

• 関連するファイルの特定
• 既存の実装パターンの把握
• 再利用できる関数やコンポーネントの発見

Claude: 以下のファイルを確認しました:
- src/lib/utils/posts.ts — getAllPosts() でタグ情報を取得済み
- src/routes/tags/[tag]/+page.ts — タグ別一覧は既に実装済み
- src/lib/components/blog/PostCard.svelte — タグの表示なし

Phase 2: 設計

調査結果に基づいて、実装計画を立てます。

## 実装計画

### 変更するファイル

1. src/lib/components/blog/PostCard.svelte
   - tags props を追加
   - Badge コンポーネントでタグを表示

2. src/routes/+page.svelte
   - PostCard に tags を渡す

### 再利用する既存コード

- Badge コンポーネント（src/lib/components/ui/badge）
- getAllTags()（src/lib/utils/posts.ts）

Phase 3: 確認

ユーザーに計画の確認を求めます。

Claude: この計画で進めてよろしいですか？
修正したい点があればお知らせください。

Phase 4: 実行

Plan モードを終了して実装に移ります。計画ファイルに基づいて、効率的にコードを修正します。

Plan モードが有効な場面

大きなリファクタリング

影響範囲を事前に把握してから作業できます。

/plan コンポーネントの状態管理を Store から Runes に移行したい

新機能の追加

既存コードとの整合性を確認してから設計できます。

/plan RSS フィード生成機能を追加したい

アーキテクチャの検討

コードを読んで現状を把握し、改善案を提案してもらえます。

/plan パフォーマンス改善のためにできることを調査して

Plan モードの利点

1. 安全にコードを探索できる

ファイルが変更されないので、安心してコードベースを調査できます。

2. 実装の方向性を事前に合意できる

計画を確認してから実装に入るので、手戻りが減ります。

3. 見落としを防げる

Claude Code が関連するファイルを網羅的に調査してくれるので、影響範囲の見落としが減ります。

計画ファイル

Plan モード中に作成された計画は、ファイルとして保存されます。実装フェーズではこのファイルを参照しながら作業が進みます。

~/.claude/plans/
└── golden-popping-star.md  ← 計画ファイル

まとめ

• Plan モードはコード変更なしに調査・設計ができる
• 調査 → 設計 → 確認 → 実行のフェーズで進む
• 大きな変更やリファクタリングの前に使うと効果的
• 計画を事前に合意することで手戻りを減らせる

参照

• Claude Code ドキュメント

前提

• Claude Code がインストール済みであること
• メモリ機能をサポートしているバージョンであること（最近のリリースで利用可能）
• ~/.claude/projects/<project>/memory/ ディレクトリへの書き込み権限があること

メモリの仕組み

メモリはファイルベースのシステムで、~/.claude/projects/<project>/memory/ ディレクトリに Markdown ファイルとして保存されます。

~/.claude/projects/blog-app/memory/
├── MEMORY.md           ← インデックスファイル
├── user_role.md         ← ユーザー情報
├── feedback_testing.md  ← フィードバック
└── project_deploy.md    ← プロジェクト情報

MEMORY.md はインデックスで、各メモリファイルへのリンクと概要が記載されます。

メモリの種類

1. user — ユーザー情報

ユーザーの役割、経験、好みに関する情報です。

---
name: ユーザーの技術背景
description: ユーザーの技術スタックと経験レベル
type: user
---

バックエンドエンジニアで、Go を10年書いている。
フロントエンド（Svelte）は初めて触る。

この情報があると、Claude Code はフロントエンドの説明をするときにバックエンドの概念に例えて説明してくれます。

2. feedback — フィードバック

作業の進め方に関するユーザーからの指示です。

---
name: テストの書き方
description: テストに関するユーザーの好み
type: feedback
---

インテグレーションテストでは DB のモックを使わず、実際の DB に接続する。
**Why:** 過去にモックと本番の乖離でデプロイ障害が発生した。
**How to apply:** テストコードを書くときは、常に実 DB 接続を前提にする。

3. project — プロジェクト情報

進行中の作業、意思決定、締め切りなどの情報です。

---
name: マージフリーズ
description: モバイルリリースに伴うマージフリーズの予定
type: project
---

2026-03-25 以降、非クリティカルな PR のマージを凍結する。
**Why:** モバイルチームがリリースブランチを切るため。
**How to apply:** この日以降の PR 作成時に警告する。

4. reference — 外部リソースへの参照

外部システムやドキュメントの場所です。

---
name: バグトラッカー
description: バグ管理に使っているツールの情報
type: reference
---

パイプラインのバグは Linear プロジェクト「INGEST」で管理している。

メモリの保存方法

Claude Code に「覚えておいて」と伝えるだけです。

データベースのテストではモックを使わないでほしい。覚えておいて。

Claude Code がメモリファイルを作成し、MEMORY.md のインデックスを更新します。

メモリの活用場面

次回の会話で自動参照

新しい会話を始めたとき、Claude Code は MEMORY.md を読み込み、関連するメモリを参照します。

# 新しい会話
テストを書いて

# Claude Code は過去のフィードバックを参照して、
# DB モックを使わないテストを書いてくれる

明示的に参照

前に話したデプロイの件、どうなってたっけ？

メモリに保存すべきでないもの

• コードのパターンや規約 — コードを見れば分かる
• Git の履歴 — git log で確認できる
• 一時的な作業内容 — 現在の会話で完結する情報
• CLAUDE.md に書いてあること — 二重管理になる

メモリの管理

更新

情報が古くなったら、Claude Code に更新を依頼します。

マージフリーズは解除された。メモリを更新して。

削除

不要になったメモリも削除できます。

デプロイに関するメモリはもう不要。削除して。

まとめ

• メモリはファイルベースの永続化システム
• ユーザー情報、フィードバック、プロジェクト情報、外部参照の 4 種類
• 「覚えておいて」で保存、次回の会話で自動参照
• コードから分かる情報は保存しない
• 古くなったメモリは適宜更新・削除する

参照

• Claude Code メモリ ドキュメント

前提

• Claude Code がインストール済みで、ターミナルから claude コマンドを実行できること
• 設定対象のプロジェクトがあるか、グローバル設定の場合 ~/.claude/ ディレクトリが存在すること

CLAUDE.md とは

プロジェクトのルートに配置する Markdown ファイルで、Claude Code が会話開始時に自動で読み込みます。プロジェクト固有のルール、コマンド、アーキテクチャなどを記述します。

配置場所

グローバル設定には言語設定や共通ルールを、プロジェクト設定にはプロジェクト固有の情報を書きます。

書くべき内容

1. よく使うコマンド

## コマンド

- `pnpm dev` — 開発サーバー起動
- `pnpm build` — 本番ビルド
- `pnpm check` — 型チェック
- `pnpm lint` — リント実行
- `pnpm test` — テスト実行

Claude Code がビルドやテストを実行するとき、正しいコマンドを使ってくれます。

2. アーキテクチャの概要

## アーキテクチャ

- デプロイ先: Cloudflare Pages
- 記事は `src/posts/*.md` に Markdown で配置
- すべてのルートは `prerender = true`（静的生成）
- UI コンポーネントは shadcn-svelte ベース

3. コーディング規約

## 規約

- Svelte 5 Runes を使用（$state, $derived, $effect）
- `.md` ファイル以外は runes モード強制
- 日本語でコメント・ドキュメントを記述

4. 注意事項

## 注意

- 開発サーバーでは Pagefind（全文検索）が動作しない
- 検索機能のテストは `pnpm build && pnpm preview` で確認

このブログの CLAUDE.md

実際にこのプロジェクトで使っている CLAUDE.md の抜粋です:

# CLAUDE.md

## General

このプロジェクトのドキュメントやCLAUDE.mdは日本語で記述すること。

## コマンド

pnpm dev # 開発サーバー起動
pnpm build # 本番ビルド
pnpm check # 型チェック
pnpm test # 全テスト実行

## アーキテクチャ

**デプロイ先**: Cloudflare Pages
**記事管理**: src/posts/\*.md に Markdown ファイルを置く
**UI コンポーネント**: shadcn-svelte / bits-ui ベース
**Svelte**: Svelte 5 Runes モード強制

効果的な書き方のコツ

簡潔に書く

CLAUDE.md が長すぎると、重要な情報が埋もれます。箇条書きや表を使って簡潔にまとめましょう。

「なぜ」を書く

ルールだけでなく理由も書くと、Claude Code が意図を理解してエッジケースでも適切な判断をしてくれます。

# ❌ ルールだけ

- `adapter-static` を使わない

# ✅ 理由も書く

- `adapter-cloudflare` を使用（将来の SSR 対応を見据えて）

変更があったら更新する

プロジェクトの構成が変わったら CLAUDE.md も更新しましょう。古い情報があると、Claude Code が間違った前提で作業する可能性があります。

グローバル CLAUDE.md

~/.claude/CLAUDE.md にはプロジェクト横断の設定を書きます。

# グローバル設定

## 言語

- 常に日本語で回答する
- コード・コマンド・技術用語はそのまま英語

## 行動指針

- 破壊的な操作は事前に確認する
- 結論を先に伝える

まとめ

CLAUDE.md は Claude Code との「共有ドキュメント」です。プロジェクトのコンテキストを事前に伝えておくことで、毎回の説明が不要になり、より的確なアウトプットが得られます。Git にコミットしておけば、チームメンバーも同じコンテキストで Claude Code を使えます。

参照

• Claude Code 公式サイト
• Claude Code — CLAUDE.md ドキュメント

最初のステップ — プロジェクト設計

まず Claude Code にやりたいことを伝えました。

SvelteKit + Tailwind CSS + shadcn-svelte で
Markdown ベースの技術ブログを作りたい。
Cloudflare Pages にデプロイする。
全文検索は Pagefind を使う。

Claude Code はこの要件を受けて、プロジェクトの構成を提案くれます。ディレクトリ構造、必要なパッケージ、設定ファイルの内容まで、一通りの計画を立ててくれます。

段階的な実装

一度にすべてを作ろうとせず、機能ごとに段階的に進めました。

Phase 1: 基盤構築

1. SvelteKit プロジェクトの初期化
2. Tailwind CSS + shadcn-svelte の設定
3. 基本的なレイアウト（ヘッダー、フッター）

Phase 2: 記事管理

1. mdsvex の設定
2. 記事用レイアウトコンポーネント
3. 記事一覧ページ
4. 記事詳細ページ

Phase 3: 機能追加

1. タグによるフィルタリング
2. Pagefind による全文検索
3. ダークモード

Claude Code が特に役立った場面

設定ファイルの作成

svelte.config.js、vite.config.ts、ESLint、Prettier などの設定ファイルは、バージョンによって書き方が変わるため調べるのが大変です。Claude Code はプロジェクトの依存関係を確認した上で、適切なバージョンの設定を生成してくれます。

shadcn-svelte コンポーネントのカスタマイズ

shadcn-svelte のコンポーネントを追加した後、ブログに合わせたカスタマイズも Claude Code に依頼しました。既存のコードスタイルを理解した上で修正してくれるので、一貫性のあるコードが維持できます。

デバッグ

ビルドエラーや型エラーが発生したとき、エラーメッセージを貼り付けるだけで原因を特定し、修正を提案してくれます。特に TypeScript の型エラーは、コンテキストを理解した上での修正が必要なので、AI の支援が効果的でした。

学んだこと

AI に任せて良いこと

• 定型的な設定ファイル — 正確さが求められるが創造性は不要
• ボイラープレートコード — ルーティング、データ取得のパターン
• リファクタリング — 既存のパターンに沿った改善

人間が判断すべきこと

• アーキテクチャの選択 — どの技術を使うか
• デザインの方向性 — 見た目の好み
• 機能の優先順位 — 何を先に作るか

ワークフローのコツ

1. CLAUDE.md を活用する

プロジェクトのルールや構成を CLAUDE.md に書いておくと、Claude Code が毎回コンテキストを理解してくれます。

# CLAUDE.md

## コマンド

- pnpm dev — 開発サーバー
- pnpm build — ビルド

## アーキテクチャ

- 記事は src/posts/\*.md に配置
- すべてのルートは prerender = true

2. 小さな単位で依頼する

「ブログ全体を作って」より「記事一覧ページを作って」の方が品質の高い結果が得られます。

3. 生成されたコードを理解する

AI が書いたコードをそのまま使うのではなく、内容を理解してから採用しましょう。理解できないコードは、説明を求めてから判断します。

まとめ

Claude Code との協業により、技術選定からデプロイまでの開発プロセスが大幅に効率化されました。特に設定ファイルの生成やデバッグでの時間節約が大きかった。AI は万能ではありませんが、適切に活用すれば強力な開発パートナーになります。

参照

• Claude Code 公式サイト
• Claude Code ドキュメント

前提

• Cloudflare Pages にデプロイ済みのプロジェクトがあること
• GitHub または GitLab とのリポジトリ連携が設定済みであること（プレビューは Git 連携プロジェクトでのみ有効）

プレビューデプロイの仕組み

Git 連携を設定している場合、以下のタイミングで自動デプロイされます:

PR へのコメント通知

PR を作成すると、Cloudflare Pages のボットが自動でコメントを投稿します。

Deploying with Cloudflare Pages

Latest commit: abc1234
Status: ✅ Deploy successful!
Preview URL: https://abc1234.blog-app.pages.dev

レビュアーはこの URL にアクセスするだけで、変更後のサイトを確認できます。

ブランチごとの URL

プレビューデプロイの URL はいくつかのパターンがあります:

• <commit-hash>.project.pages.dev — コミットハッシュベース
• <branch-name>.project.pages.dev — ブランチ名ベース

ブランチ名ベースの URL は、同じブランチの最新コミットを常に反映します。

プレビューブランチの制御

デフォルトではすべてのブランチがプレビュー対象ですが、設定で制御できます。

1. ダッシュボードでプロジェクトを開く
2. Settings → Builds & deployments
3. Configure preview deployments で設定:
   • All non-production branches — すべてのブランチ（デフォルト）
   • Custom branches — 特定のブランチパターンのみ
   • None — プレビュー無効

ビルド回数を節約したい場合は、特定のブランチパターン（例: feature/*）だけに限定できます。

プレビュー環境の環境変数

プレビュー環境用の環境変数を個別に設定できます。

1. Settings → Environment variables
2. Preview タブで変数を設定

# プレビュー環境専用の設定例
PUBLIC_SITE_URL=https://preview.blog-app.pages.dev
ENABLE_DRAFT_POSTS=true

これを利用して、プレビュー環境では下書き記事を表示するといった使い方もできます。

活用シーン

記事のレビュー

ブログ記事を書いたら、PR を作成してプレビュー URL を共有。実際の見た目を確認してからマージできます。

デザイン変更の確認

レイアウトやスタイルの変更時に、本番環境に影響を与えずに確認。スマートフォンでの表示もプレビュー URL で確認できます。

複数の変更を並行して確認

ブランチごとに別の URL が生成されるので、複数の変更を同時に確認・比較できます。

ローカルプレビューとの使い分け

pnpm preview  # ローカルで確認（自分だけ見える）

ローカルプレビュー（pnpm preview）は即座に確認できますが、他の人には共有できません。Cloudflare Pages のプレビューデプロイは URL を共有するだけでチームメンバーに確認してもらえます。

まとめ

• PR ごとにプレビュー URL が自動生成される
• 環境変数をプレビュー専用に設定できる
• ビルド対象ブランチを制限してビルド回数を節約できる
• 記事レビューやデザイン確認に活用できる

参照

• Cloudflare Pages プレビューデプロイ ドキュメント
• Cloudflare Pages 公式サイト

前提

• Cloudflare のアカウント（無料プラン可）
• デプロイ対象の SvelteKit プロジェクト
• GitHub または GitLab のリポジトリ（Git 連携を使う場合）
• Node.js v22 以上（v24 を推奨。本記事のビルド設定例で NODE_VERSION=24 を使用）

adapter-cloudflare のセットアップ

pnpm add -D @sveltejs/adapter-cloudflare

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

const config = {
	kit: {
		adapter: adapter({
			routes: {
				exclude: ['<build>', '<prerendered>', '<files>', '/pagefind/*']
			}
		})
	}
};

routes.exclude で静的ファイルや Pagefind のインデックスを Functions の処理対象から除外しています。

Cloudflare ダッシュボードからデプロイ

1. GitHub にリポジトリを push
2. Cloudflare ダッシュボード → Workers & Pages → Create → Pages → Connect to Git
3. ビルド設定を入力:

4. 環境変数を追加:

5. Save and Deploy をクリック

初回ビルドには数分かかります。完了すると https://<project-name>.pages.dev でサイトが公開されます。

wrangler CLI でのデプロイ

ダッシュボードを使わず、CLI からもデプロイできます。

pnpm build
pnpm wrangler pages deploy .svelte-kit/cloudflare

初回は対話的にプロジェクト名を聞かれます。2 回目以降はプロジェクト名を指定できます。

カスタムドメインの設定

1. Cloudflare ダッシュボードでプロジェクトを開く
2. Custom domains → Set up a custom domain
3. ドメイン名を入力（例: blog.example.com）
4. DNS レコードが自動で追加される

Cloudflare で DNS を管理している場合は、SSL 証明書も自動で発行されます。

環境変数とシークレット

ビルド時に必要な環境変数は、ダッシュボードの Settings → Environment variables で設定します。

# ビルド時に使う環境変数
PUBLIC_SITE_URL=https://blog.example.com

SvelteKit では $env/static/public や $env/static/private でアクセスできます。

import { PUBLIC_SITE_URL } from '$env/static/public';

ビルドキャッシュ

Cloudflare Pages はデフォルトで node_modules をキャッシュします。依存関係が変わらない限りインストールがスキップされ、ビルドが高速化されます。

Web Analytics

Cloudflare Pages には無料の Web Analytics が付属しています。

1. ダッシュボードでプロジェクトを開く
2. Web Analytics → Enable

JavaScript のスニペットが自動挿入され、ページビューやリファラーなどの基本的なアナリティクスが取得できます。プライバシーに配慮した設計で、Cookie を使用しません。

_headers と _redirects

静的ファイルで HTTP ヘッダーやリダイレクトを設定できます。

# static/_headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

/assets/*
  Cache-Control: public, max-age=31536000, immutable

# static/_redirects
/old-path /new-path 301
/blog/* /posts/:splat 301

料金

Cloudflare Pages の無料プラン:

• ビルド: 500 回/月
• 帯域: 無制限
• サイト数: 無制限
• カスタムドメイン: 無制限

個人ブログには十分すぎるスペックです。

まとめ

Cloudflare Pages は SvelteKit との相性が良く、無料で高速なデプロイ環境を提供してくれます。Git 連携による自動デプロイ、プレビュー環境、Web Analytics など、ブログ運営に必要な機能が揃っています。

参照

• Cloudflare Pages 公式サイト
• Cloudflare Pages ドキュメント
• @sveltejs/adapter-cloudflare GitHub

SvelteKit のプリレンダリングと satori を組み合わせると、ビルド時に各記事の OGP 画像を自動生成できます。

前提

• SvelteKit プロジェクト（本記事は adapter-cloudflare を使った構成を想定）
• prerender = true で静的出力する設計になっていること
• Node.js v22 以上（@resvg/resvg-js のネイティブモジュールが必要）
• 日本語を表示する場合は Noto Sans JP などの TTF フォントファイルを用意

使うパッケージ

• satori: HTML/CSS（Flexbox）の記述から SVG を生成するライブラリ（Vercel 製）
• @resvg/resvg-js: SVG → PNG 変換

pnpm add -D satori @resvg/resvg-js

日本語テキストをレンダリングするには、フォントファイルが必要です。Google Fonts から Noto Sans JP の TTF をダウンロードして src/lib/server/fonts/ に置きます。

画像生成関数

src/lib/server/og.ts に生成ロジックをまとめます。

import satori from 'satori';
import { Resvg } from '@resvg/resvg-js';
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';

const fontRegular = readFileSync(resolve('src/lib/server/fonts/NotoSansJP-Regular.ttf'));
const fontBold = readFileSync(resolve('src/lib/server/fonts/NotoSansJP-Bold.ttf'));

export async function generateOgImage(options: {
	title: string;
	date?: string;
	slug?: string;
}): Promise<Buffer> {
	const svg = await satori(
		{
			type: 'div',
			props: {
				style: {
					width: '100%',
					height: '100%',
					display: 'flex',
					flexDirection: 'column',
					background: '#0f0f23',
					padding: '60px 72px',
					fontFamily: 'Noto Sans JP'
				},
				children: [
					{
						type: 'h1',
						props: {
							style: {
								fontSize: '52px',
								fontWeight: 700,
								color: '#f1f5f9',
								margin: 0
							},
							children: options.title
						}
					}
				]
			}
		},
		{
			width: 1200,
			height: 630,
			fonts: [
				{ name: 'Noto Sans JP', data: fontRegular, weight: 400, style: 'normal' },
				{ name: 'Noto Sans JP', data: fontBold, weight: 700, style: 'normal' }
			]
		}
	);

	const resvg = new Resvg(svg, { fitTo: { mode: 'width', value: 1200 } });
	return resvg.render().asPng();
}

satori のレイアウトルール

satori は Flexbox のみ をサポートします。display: grid は使えません。また、children に文字列を直接渡す代わりに、テキストノードはプリミティブ値（文字列）で渡します。

// ✅ 正しい書き方
{ type: 'span', props: { children: 'テキスト' } }

// ❌ 動かない
{ type: 'span', props: { children: <span>テキスト</span> } }

ルートを作る

記事ごとの OGP 画像

src/routes/posts/[slug]/og.png/+server.ts を作成します。

import { generateOgImage } from '$lib/server/og';
import { getAllPosts } from '$lib/utils/posts';
import { error } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const prerender = true;

export async function entries() {
	const posts = await getAllPosts();
	return posts.map((p) => ({ slug: p.slug }));
}

export const GET: RequestHandler = async ({ params }) => {
	const posts = await getAllPosts();
	const post = posts.find((p) => p.slug === params.slug);
	if (!post) throw error(404);

	const png = await generateOgImage({
		title: post.title,
		date: post.date,
		slug: post.slug
	});

	return new Response(png, {
		headers: {
			'Content-Type': 'image/png',
			'Cache-Control': 'public, max-age=31536000, immutable'
		}
	});
};

entries() を定義することで、prerender = true のときにすべての記事スラッグに対して静的ファイルが生成されます。

サイト共通の OGP 画像

src/routes/og.png/+server.ts でトップページ用の画像も生成できます。

import { generateOgImage } from '$lib/server/og';
import type { RequestHandler } from './$types';

export const prerender = true;

export const GET: RequestHandler = async () => {
	const png = await generateOgImage({ title: "toishi's blog" });
	return new Response(png, {
		headers: { 'Content-Type': 'image/png' }
	});
};

<meta> タグを設定する

生成した画像を og:image として使うには、各ページの <svelte:head> に記述します。

src/lib/layouts/post.svelte（記事レイアウト）の場合:

<script lang="ts">
	import { siteConfig } from '$lib/config';
	let { title, date, slug, children } = $props();
	const ogImageUrl = `${siteConfig.url}/posts/${slug}/og.png`;
</script>

<svelte:head>
	<title>{title}</title>
	<meta property="og:title" content={title} />
	<meta property="og:image" content={ogImageUrl} />
	<meta name="twitter:card" content="summary_large_image" />
</svelte:head>

動作確認

OGP 画像は開発サーバーでは生成されません。pnpm build → pnpm preview で確認します。

pnpm build
pnpm preview
# http://localhost:4173/posts/your-slug/og.png でアクセスできる

注意点

ファイルパスの解決

readFileSync(resolve('src/lib/server/fonts/...')) は、Node.js の実行ディレクトリ（プロジェクトルート）からの相対パス で解決されます。Cloudflare Pages のビルド環境でも動作しますが、実行コンテキストが変わる場合は import.meta.url を使った方が確実です。

フォントサイズとテキストの折り返し

satori はデフォルトではテキストの折り返しが起きません。長いタイトルに対応するには、fontSize を文字数で動的に調整するか、maxWidth と flexWrap: 'wrap' を設定します。

fontSize: title.length > 30 ? '44px' : '52px';

Cloudflare Pages での Node.js 互換性

readFileSync など Node.js の API を使うには、wrangler.jsonc に以下が必要です。

{
	"compatibility_flags": ["nodejs_als"]
}

まとめ

• satori で HTML/CSS（Flexbox）から SVG を生成し、resvg-js で PNG に変換
• +server.ts + prerender = true + entries() でビルド時に全記事分を静的生成
• 日本語を含む場合は TTF フォントの明示的な指定が必要
• 確認は pnpm build + pnpm preview で行う

参照

• satori GitHub
• resvg-js GitHub
• SvelteKit +server.ts ドキュメント

前提

• 静的 HTML を出力するサイト（SvelteKit + prerender = true を想定）
• Node.js v22 以上
• ビルド出力ディレクトリにアクセスして Pagefind CLI を実行できる環境

Pagefind の仕組み

1. ビルド時: HTML ファイルをスキャンしてインデックスを生成
2. 実行時: ブラウザで JavaScript を使ってインデックスを検索

インデックスは分割されて必要な部分だけ遅延読み込みされるため、数千ページのサイトでも高速に動作します。

セットアップ

pnpm add -D pagefind

package.json の build スクリプトに pagefind を追加します。

{
	"scripts": {
		"build": "vite build && pagefind --site .svelte-kit/cloudflare"
	}
}

--site にビルド出力先ディレクトリを指定します。SvelteKit + adapter-cloudflare の場合は .svelte-kit/cloudflare です。

検索対象の指定

デフォルトでは <body> 全体がインデックス対象ですが、data-pagefind-body 属性でスコープを絞れます。

<!-- src/lib/layouts/post.svelte -->
<article class="prose">
	<h1>{title}</h1>
	<div data-pagefind-body>
		{@render children()}
	</div>
</article>

ナビゲーションやフッターを除外し、記事本文だけを検索対象にできます。

除外したい要素

<div data-pagefind-body>
	<p>この段落は検索対象</p>
	<nav data-pagefind-ignore>
		<!-- ここは検索対象外 -->
	</nav>
</div>

SvelteKit での検索コンポーネント

Pagefind は動的に JavaScript を読み込むため、SvelteKit では onMount 内でインポートします。

<script lang="ts">
	import { onMount } from 'svelte';

	let pagefind: any = $state(null);
	let query = $state('');
	let results = $state<any[]>([]);

	onMount(async () => {
		try {
			pagefind = await import(/* @vite-ignore */ '/pagefind/pagefind.js');
			await pagefind.init();
		} catch {
			console.warn('Pagefind not available');
		}
	});

	async function search() {
		if (!pagefind || !query) {
			results = [];
			return;
		}
		const response = await pagefind.debouncedSearch(query);
		if (!response) return;
		results = await Promise.all(response.results.map((r: any) => r.data()));
	}

	$effect(() => {
		query;
		search();
	});
</script>

<input type="text" bind:value={query} placeholder="記事を検索..." />

<ul>
	{#each results as result}
		<li>
			<a href={result.url}>
				<strong>{result.meta.title}</strong>
				<p>{@html result.excerpt}</p>
			</a>
		</li>
	{/each}
</ul>

ポイント

• /* @vite-ignore */ で Vite の静的解析を回避
• debouncedSearch で入力中の無駄なリクエストを抑制
• result.data() は遅延評価 — 表示する結果だけデータを取得
• result.excerpt には検索語がハイライトされた HTML が含まれる

開発時の注意

Pagefind のインデックスはビルド時に生成されるため、開発サーバー（pnpm dev）では検索が動作しません。検索機能を確認するには:

pnpm build    # ビルド + インデックス生成
pnpm preview  # ビルド結果をローカルプレビュー

メタデータの活用

Pagefind はページのメタデータも自動で収集します。

<!-- title タグが meta.title になる -->
<title>記事のタイトル</title>

<!-- meta description が meta.description になる -->
<meta name="description" content="記事の説明" />

カスタムメタデータも追加できます。

<div data-pagefind-meta="category:技術">
	<!-- この要素のテキストが category メタデータに -->
</div>

フィルタリング

タグやカテゴリでフィルタリングすることも可能です。

<div data-pagefind-filter="tag:svelte">Svelte の記事</div>

const results = await pagefind.search('query', {
	filters: { tag: 'svelte' }
});

Cloudflare Pages との相性

Pagefind はクライアントサイドで完結するため、Cloudflare Pages のような静的ホスティングと相性が抜群です。サーバーサイドの処理が不要なので、追加コストなしで検索機能を提供できます。

まとめ

• Pagefind はビルド時にインデックスを生成するクライアントサイド検索
• 外部サービス不要、無料で使える
• data-pagefind-body で検索範囲を制御
• 開発サーバーでは動かない（ビルド後に確認）
• 静的ホスティングとの相性が良い

参照

• Pagefind 公式サイト
• Pagefind GitHub

前提

• TypeScript 4.9 以上が動作するプロジェクト
• tsconfig.json で strict: true を有効にしておくと、satisfies の効果がより分かりやすい

従来の問題

型アノテーションを使うと、リテラル型の情報が失われます。

type Route = {
	path: string;
	method: 'GET' | 'POST';
};

// 型アノテーション — method が 'GET' | 'POST' に広がる
const route: Route = {
	path: '/api/posts',
	method: 'GET'
};

// route.method は 'GET' | 'POST' 型
// 'GET' であることが失われている

satisfies の登場

const route = {
	path: '/api/posts',
	method: 'GET'
} satisfies Route;

// route.method は 'GET' 型（リテラル型が保持される！）
// かつ Route 型の制約も検証済み

satisfies は「この値が型 Route を満たすことを検証するが、推論された型をそのまま使う」という意味です。

実践的な活用パターン

1. 設定オブジェクト

type Config = {
	theme: 'light' | 'dark';
	language: string;
	features: Record<string, boolean>;
};

const config = {
	theme: 'dark',
	language: 'ja',
	features: {
		search: true,
		comments: false,
		analytics: true
	}
} satisfies Config;

// config.theme は 'dark' 型（'light' | 'dark' ではない）
// config.features.search は boolean（Record の制約も満たす）

2. ルーティング定義

type Routes = Record<string, { path: string; prerender?: boolean }>;

const routes = {
	home: { path: '/', prerender: true },
	about: { path: '/about', prerender: true },
	search: { path: '/search', prerender: false }
} satisfies Routes;

// routes.home が存在することが型で保証される
// routes.notExist はコンパイルエラー

型アノテーション（const routes: Routes = ...）だと、キー名が string に広がって routes.home の補完が効きません。

3. カラーパレット

type Color = `#${string}` | `rgb(${string})`;
type Palette = Record<string, Color>;

const palette = {
	primary: '#3b82f6',
	secondary: '#64748b',
	accent: 'rgb(236, 72, 153)'
} satisfies Palette;

// palette.primary は '#3b82f6' 型
// palette.unknown はエラー

4. イベントハンドラのマップ

type EventHandlers = Record<string, (...args: any[]) => void>;

const handlers = {
	click: (e: MouseEvent) => console.log(e.clientX),
	keydown: (e: KeyboardEvent) => console.log(e.key),
	submit: (data: FormData) => console.log(data)
} satisfies EventHandlers;

// handlers.click の引数が MouseEvent として推論される

satisfies vs 型アノテーション

as const satisfies

as const と組み合わせることで、さらに厳密な型推論が得られます。

const endpoints = {
	users: '/api/users',
	posts: '/api/posts',
	tags: '/api/tags'
} as const satisfies Record<string, `/${string}`>;

// endpoints.users は '/api/users' リテラル型（readonly）
// 値が '/api/' で始まることも検証済み

このブログでの活用パターン

このブログでも、サイト設定や JSON-LD スキーマの組み立てなど、いくつかの場所で satisfies が活躍します。

サイト設定の凍結

siteConfig は全ページから参照するため、キーや値の型が緩むと参照側で面倒です。as const satisfies で「キー名はリテラルのまま」「URL は https:// で始まる文字列」を同時に保証できます。

// src/lib/config.ts
type SiteConfig = {
	title: string;
	description: string;
	url: `https://${string}`;
};

export const siteConfig = {
	title: "toishi's blog",
	description: 'SvelteKit で作った技術ブログ',
	url: 'https://toishi.dev'
} as const satisfies SiteConfig;

// siteConfig.url は 'https://toishi.dev' リテラル型のまま
// 'http://' で始めるとコンパイルエラー

PostMeta のデフォルト値

下書き記事のテンプレートやテスト用のフィクスチャを書くとき、PostMeta 型を満たしつつフィールドの値を具体的に保持しておきたい場面があります。

// src/lib/utils/posts.ts
import type { PostMeta } from './posts';

const draftFixture = {
	slug: 'draft-post',
	title: '下書き記事',
	description: '',
	date: '2026-04-30',
	tags: ['svelte'],
	draft: true
} satisfies PostMeta;

// draftFixture.draft は true 型（boolean ではない）
// テストで draft 記事のみのケースを書くときに便利

JSON-LD のスキーマ定義

構造化データのキー名を厳密に保ちたいときも、as const satisfies が効きます。@type 等のフィールドを文字列リテラル型のまま渡せるので、Google の構造化データテストツール側で定義された値とのミスマッチが起きにくくなります。

type JsonLd = Record<string, unknown> & { '@context': string; '@type': string };

const websiteLd = {
	'@context': 'https://schema.org',
	'@type': 'WebSite',
	name: siteConfig.title,
	url: siteConfig.url
} as const satisfies JsonLd;

まとめ

satisfies は「型チェックは厳密に、推論はリッチに」を実現する演算子です。設定オブジェクトやルーティング定義など、型の制約を守りつつリテラル型の情報を保持したい場面で活躍します。

参照

• TypeScript 4.9 リリースノート（satisfies 演算子）
• TypeScript 公式サイト

前提

• SvelteKit プロジェクト（Svelte 5 を想定）
• Node.js v22 以上
• Playwright のブラウザバイナリをダウンロードできるネットワーク環境（初回 npx playwright install でセットアップ）

セットアップ

pnpm add -D vitest @vitest/browser-playwright playwright vitest-browser-svelte

vite.config.ts にテスト設定を追加:

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [sveltekit()],
	test: {
		include: ['src/**/*.{test,spec}.{js,ts}'],
		browser: {
			enabled: true,
			provider: 'playwright',
			instances: [{ browser: 'chromium' }]
		}
	}
});

テストの種類

このプロジェクトでは 2 種類のテスト環境を使い分けています:

コンポーネントテストの書き方

vitest-browser-svelte の render を使ってコンポーネントをレンダリングします。

// src/lib/components/Counter.svelte.test.ts
import { render } from 'vitest-browser-svelte';
import { expect, test } from 'vitest';
import Counter from './Counter.svelte';

test('初期値が表示される', async () => {
	const screen = render(Counter, { count: 0 });
	await expect.element(screen.getByText('0')).toBeVisible();
});

test('クリックでカウントが増える', async () => {
	const screen = render(Counter, { count: 0 });
	const button = screen.getByRole('button');
	await button.click();
	await expect.element(screen.getByText('1')).toBeVisible();
});

Props の渡し方

render(PostCard, {
	title: 'テスト記事',
	description: '説明文',
	date: '2026-03-15',
	slug: 'test-post',
	tags: ['svelte', 'test']
});

イベントのテスト

test('ボタンクリックでイベントが発火する', async () => {
	let clicked = false;
	const screen = render(Button, {
		onclick: () => {
			clicked = true;
		}
	});

	await screen.getByRole('button').click();
	expect(clicked).toBe(true);
});

ユーティリティ関数のテスト

// src/lib/utils/posts.test.ts
import { describe, expect, it } from 'vitest';
import { getAllPosts, getAllTags } from './posts';

describe('getAllPosts', () => {
	it('記事が日付の降順で返される', async () => {
		const posts = await getAllPosts();
		for (let i = 1; i < posts.length; i++) {
			expect(new Date(posts[i - 1].date).getTime()).toBeGreaterThanOrEqual(
				new Date(posts[i].date).getTime()
			);
		}
	});

	it('下書き記事が含まれない', async () => {
		const posts = await getAllPosts();
		expect(posts.every((p) => !p.draft)).toBe(true);
	});
});

describe('getAllTags', () => {
	it('タグとカウントのマップが返される', async () => {
		const tags = await getAllTags();
		expect(tags).toBeInstanceOf(Map);
		for (const [, count] of tags) {
			expect(count).toBeGreaterThan(0);
		}
	});
});

テストの実行

pnpm test          # 全テスト実行（単発）
pnpm test:unit     # ウォッチモード（開発中に便利）

テストのコツ

1. アクセシビリティロールで要素を探す

// ❌ テスト ID やクラス名に依存
screen.getByTestId('submit-btn');

// ✅ アクセシビリティロールを使う
screen.getByRole('button', { name: '送信' });

2. 非同期の変更を待つ

Svelte のリアクティビティは非同期で反映されるため、await を使います。

await button.click();
await expect.element(screen.getByText('更新後のテキスト')).toBeVisible();

3. テストごとにクリーンアップ

render は各テスト後に自動でクリーンアップされるので、手動での cleanup は不要です。

まとめ

• Vitest + Playwright でブラウザ上のコンポーネントテストが可能
• .svelte.test.ts はブラウザ環境、.test.ts は Node.js 環境
• vitest-browser-svelte の render でコンポーネントをレンダリング
• アクセシビリティロールでの要素取得を推奨

参照

• Vitest 公式サイト
• Vitest ブラウザモード ドキュメント
• vitest-browser-svelte GitHub

前提

• Node.js v22 以上
• ESLint v9 以上（Flat Config 前提）
• Prettier v3 以上
• 本記事は SvelteKit プロジェクトを対象としているが、Node.js プロジェクト全般に応用可能

パッケージのインストール

SvelteKit のプロジェクト作成時に ESLint と Prettier を選択すると自動でインストールされますが、手動で追加する場合:

pnpm add -D eslint prettier \
  eslint-plugin-svelte \
  eslint-config-prettier \
  prettier-plugin-svelte \
  prettier-plugin-tailwindcss \
  typescript-eslint \
  globals

ESLint の設定（Flat Config）

ESLint v9 以降は Flat Config（eslint.config.js）が標準です。

// eslint.config.js
import js from '@eslint/js';
import prettier from 'eslint-config-prettier';
import svelte from 'eslint-plugin-svelte';
import globals from 'globals';
import ts from 'typescript-eslint';

export default ts.config(
	js.configs.recommended,
	...ts.configs.recommended,
	...svelte.configs.recommended,
	prettier,
	...svelte.configs.prettier,
	{
		languageOptions: {
			globals: {
				...globals.browser,
				...globals.node
			}
		}
	},
	{
		files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
		languageOptions: {
			parserOptions: {
				parser: ts.parser
			}
		}
	},
	{
		ignores: ['build/', '.svelte-kit/', 'dist/', '.wrangler/', '.vercel/']
	}
);

ポイント

• eslint-config-prettier で Prettier と競合するルールを無効化
• eslint-plugin-svelte で .svelte ファイルを解析
• svelte.configs.prettier で Svelte 固有の Prettier 競合ルールも無効化
• ignores でビルド出力を除外

Prettier の設定

// .prettierrc
{
	"useTabs": true,
	"singleQuote": true,
	"trailingComma": "none",
	"printWidth": 100,
	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
	"overrides": [
		{
			"files": "*.svelte",
			"options": {
				"parser": "svelte"
			}
		}
	]
}

プラグインの役割

• prettier-plugin-svelte — .svelte ファイルのフォーマット対応
• prettier-plugin-tailwindcss — Tailwind CSS のクラス名を推奨順序に自動ソート

.prettierignore

# .prettierignore
build/
.svelte-kit/
dist/
.wrangler/
pnpm-lock.yaml

npm スクリプト

{
	"scripts": {
		"lint": "prettier --check . && eslint .",
		"format": "prettier --write ."
	}
}

lint はチェックのみ（CI 用）、format は自動修正です。

エディタ連携

VS Code

.vscode/settings.json:

{
	"editor.formatOnSave": true,
	"editor.defaultFormatter": "esbenp.prettier-vscode",
	"[svelte]": {
		"editor.defaultFormatter": "svelte.svelte-vscode"
	},
	"eslint.validate": ["javascript", "typescript", "svelte"]
}

推奨拡張機能

• Svelte for VS Code — Svelte 言語サポート
• ESLint — リアルタイム ESLint チェック
• Prettier — 保存時自動フォーマット

Tailwind CSS クラスの自動ソート

prettier-plugin-tailwindcss により、クラス名が Tailwind の推奨順序に自動ソートされます。

<!-- Before -->
<div class="p-4 flex bg-white rounded-lg shadow-md items-center">

<!-- After（自動ソート） -->
<div class="flex items-center rounded-lg bg-white p-4 shadow-md">

CI での実行

GitHub Actions で lint を自動実行する例:

- name: Lint
  run: pnpm lint

- name: Type check
  run: pnpm check

pnpm lint が失敗すると PR のマージをブロックできます。

まとめ

• ESLint で静的解析、Prettier でフォーマット
• eslint-config-prettier で競合を解消
• .svelte ファイルは専用プラグインで対応
• prettier-plugin-tailwindcss でクラス名を自動ソート
• 保存時の自動フォーマットでストレスフリーに

参照

• ESLint 公式サイト
• Prettier 公式サイト
• eslint-plugin-svelte GitHub
• prettier-plugin-tailwindcss GitHub

前提

• SvelteKit プロジェクト（Svelte 5 Runes モードを想定）
• Tailwind CSS v4 が導入済みで、@custom-variant dark (&:is(.dark *)) のようなクラスベースのダークモード設定が可能なこと
• shadcn-svelte を使う場合は CSS 変数（--background 等）が :root と .dark の両方で定義されていること

Tailwind CSS のダークモード

Tailwind CSS は dark: プレフィックスでダークモード用のスタイルを記述できます。

<div class="bg-white text-black dark:bg-gray-900 dark:text-white">
	ライトモードでは白背景、ダークモードでは暗い背景
</div>

テーマの管理方法

テーマの管理には 3 つのアプローチがあります。

1. システム設定に従う（prefers-color-scheme）

@media (prefers-color-scheme: dark) {
	:root {
		color-scheme: dark;
	}
}

OS やブラウザの設定に自動で追従します。最もシンプルですが、ユーザーが手動で切り替えられません。

2. クラスベース（手動切り替え）

<html> 要素にクラスを付与してテーマを制御します。

<html class="dark">
	<!-- dark: プレフィックスが有効になる -->
</html>

3. ハイブリッド（推奨）

システム設定をデフォルトにしつつ、ユーザーが手動でも切り替えられるアプローチです。

実装

テーマの状態管理

// theme.svelte.ts
type Theme = 'light' | 'dark' | 'system';

let theme = $state<Theme>('system');

export function getTheme() {
	return theme;
}

export function setTheme(newTheme: Theme) {
	theme = newTheme;
	localStorage.setItem('theme', newTheme);
	applyTheme(newTheme);
}

function applyTheme(t: Theme) {
	const isDark =
		t === 'dark' || (t === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);

	document.documentElement.classList.toggle('dark', isDark);
}

export function initTheme() {
	const saved = localStorage.getItem('theme') as Theme | null;
	theme = saved ?? 'system';
	applyTheme(theme);

	// システム設定の変更を監視
	window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
		if (theme === 'system') {
			applyTheme('system');
		}
	});
}

テーマ切り替えボタン

<script lang="ts">
	import { getTheme, setTheme } from './theme.svelte.ts';
	import Sun from '@lucide/svelte/icons/sun';
	import Moon from '@lucide/svelte/icons/moon';
	import Monitor from '@lucide/svelte/icons/monitor';

	const themes = [
		{ value: 'light', icon: Sun, label: 'ライト' },
		{ value: 'dark', icon: Moon, label: 'ダーク' },
		{ value: 'system', icon: Monitor, label: 'システム' }
	] as const;
</script>

<div class="flex gap-1">
	{#each themes as t}
		<button
			onclick={() => setTheme(t.value)}
			class="rounded-md p-2"
			class:bg-muted={getTheme() === t.value}
			aria-label={t.label}
		>
			<t.icon size={16} />
		</button>
	{/each}
</div>

フラッシュ防止

SSG（静的サイト生成）では、HTML が読み込まれてから JavaScript が実行されるまでの間にデフォルトテーマが表示されてしまう「フラッシュ」が発生します。

これを防ぐために、<head> にインラインスクリプトを追加します。

<!-- src/app.html -->
<head>
	<script>
		(function () {
			const theme = localStorage.getItem('theme') ?? 'system';
			const isDark =
				theme === 'dark' ||
				(theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
			if (isDark) document.documentElement.classList.add('dark');
		})();
	</script>
</head>

このスクリプトは HTML パース時に同期的に実行されるため、ページが表示される前にテーマが適用されます。

shadcn-svelte のダークモード対応

shadcn-svelte のコンポーネントは CSS 変数でテーマカラーを管理しているため、ダークモードに自動対応しています。

:root {
	--background: 0 0% 100%;
	--foreground: 222.2 84% 4.9%;
}

.dark {
	--background: 222.2 84% 4.9%;
	--foreground: 210 40% 98%;
}

dark クラスの有無で CSS 変数が切り替わり、すべてのコンポーネントの色が連動して変わります。

@tailwindcss/typography のダークモード

<article class="prose dark:prose-invert">
	<!-- Markdown コンテンツ -->
</article>

dark:prose-invert を追加するだけで、記事のテキスト色が反転します。

まとめ

• Tailwind CSS の dark: プレフィックスでスタイルを切り替え
• localStorage + システム設定のハイブリッドが実用的
• app.html のインラインスクリプトでフラッシュを防止
• shadcn-svelte は CSS 変数で自動対応

参照

• Tailwind CSS ダークモード ドキュメント
• Svelte 公式サイト

前提

• Tailwind CSS v4 が導入済みのプロジェクト（v3 でも動作するが本記事は v4 の @plugin 構文を使用）
• Markdown を HTML に変換する仕組みがあること（mdsvex / MDX / Markdown-it 等）

セットアップ

pnpm add -D @tailwindcss/typography

Tailwind CSS v4 では、CSS ファイルでプラグインを読み込みます。

@import 'tailwindcss';
@plugin '@tailwindcss/typography';

基本の使い方

prose クラスを親要素に付けるだけです。

<article class="prose">
	<h1>記事タイトル</h1>
	<p>Markdown から生成された HTML に、自動的に適切なスタイルが当たります。</p>
	<ul>
		<li>リストアイテム 1</li>
		<li>リストアイテム 2</li>
	</ul>
	<pre><code>console.log('コードブロックも整形される');</code></pre>
</article>

prose が適用する主なスタイル:

• 見出し（h1〜h4）のサイズ・余白・太さ
• 段落の行間（line-height）と余白
• リスト（ul / ol）のマーカーとインデント
• コードブロックの背景色とパディング
• リンクの色と下線
• blockquote のボーダーとスタイル
• テーブルのボーダーとセルパディング

ダークモード対応

dark:prose-invert を追加すると、ダークモードで配色が反転します。

<article class="prose dark:prose-invert">
	<!-- コンテンツ -->
</article>

サイズバリエーション

コンテンツの表示サイズを変更できます。

<article class="prose prose-sm"><!-- 小さめ --></article>
<article class="prose"><!-- デフォルト --></article>
<article class="prose prose-lg"><!-- 大きめ --></article>
<article class="prose prose-xl"><!-- さらに大きめ --></article>

カスタマイズ

prose 内の要素を個別にスタイリング

prose クラスの中でも、Tailwind のユーティリティクラスで上書きできます。

@layer components {
	.prose pre {
		@apply bg-muted text-foreground;
	}

	.prose code {
		@apply rounded bg-muted px-1 py-0.5 text-sm;
	}

	.prose a {
		@apply text-primary underline-offset-4;
	}
}

not-prose で一部を除外

prose の中で、特定の要素にスタイルを当てたくない場合は not-prose を使います。

<article class="prose">
	<p>ここは prose スタイルが当たる</p>

	<div class="not-prose">
		<!-- ここは prose の影響を受けない -->
		<div class="grid grid-cols-2 gap-4">
			<div class="rounded-lg bg-blue-100 p-4">カード 1</div>
			<div class="rounded-lg bg-blue-100 p-4">カード 2</div>
		</div>
	</div>

	<p>ここも prose スタイルが当たる</p>
</article>

このブログでは、タグのバッジ表示部分に not-prose を使って、prose のスタイルが干渉しないようにしています。

最大幅の制御

デフォルトでは prose に max-width: 65ch が設定されています。記事の読みやすさのためですが、全幅にしたい場合は max-w-none で解除できます。

<article class="prose max-w-none">
	<!-- 全幅で表示 -->
</article>

SvelteKit ブログでの実践例

mdsvex のレイアウトコンポーネントで prose を適用するのが一般的です。

<!-- src/lib/layouts/post.svelte -->
<script lang="ts">
	let { title, date, children } = $props();
</script>

<article class="mx-auto prose px-4 py-12 dark:prose-invert">
	<h1>{title}</h1>
	<time class="text-muted-foreground">
		{new Date(date).toLocaleDateString('ja-JP')}
	</time>
	<div data-pagefind-body>
		{@render children()}
	</div>
</article>

まとめ

@tailwindcss/typography は、Markdown コンテンツの見た目を劇的に改善する必須プラグインです。prose クラス一つで、見出し・段落・リスト・コード・テーブルすべてに適切なタイポグラフィが適用されます。ブログや技術ドキュメントを作るなら、まず入れておきたいプラグインです。

参照

• @tailwindcss/typography ドキュメント
• tailwindcss-typography GitHub

前提

• Vite ベースのプロジェクト（PostCSS 経由でも使えるが本記事は @tailwindcss/vite を推奨構成として扱う）
• Node.js v22 以上
• v3 から移行する場合は、既存の tailwind.config.js の内容を CSS に書き換える準備があること

最大の変更: CSS ベースの設定

v3 までは tailwind.config.js（JavaScript）で設定していましたが、v4 では CSS ファイル内で設定 します。

Before（v3）

// tailwind.config.js
module.exports = {
	theme: {
		extend: {
			colors: {
				brand: '#3b82f6'
			}
		}
	}
};

After（v4）

/* app.css */
@import 'tailwindcss';

@theme {
	--color-brand: #3b82f6;
}

tailwind.config.js は不要になり、@theme ディレクティブで CSS 変数としてテーマを定義します。

Vite プラグインとして動作

v4 は PostCSS プラグインではなく、Vite プラグインとして動作します（PostCSS 経由でも使えますが、Vite プラグインが推奨）。

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
	plugins: [tailwindcss()]
});

これにより、ビルドパフォーマンスが大幅に向上しています。

@import による取り込み

v3 では @tailwind base; @tailwind components; @tailwind utilities; の 3 行が必要でしたが、v4 では 1 行です。

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import 'tailwindcss';

新しいカラーパレット

v4 ではカラーパレットが OKLCH ベースに更新されました。より広い色域をサポートし、色の知覚的な均一性が向上しています。

@theme {
	--color-primary: oklch(0.6 0.2 250);
}

コンテナクエリのネイティブサポート

v3 では @tailwindcss/container-queries プラグインが必要でしたが、v4 ではビルトインです。

<div class="@container">
	<div class="grid grid-cols-1 @lg:grid-cols-2">
		<!-- コンテナ幅に応じてレイアウト変更 -->
	</div>
</div>

移行のポイント

1. tailwind.config.js → @theme

設定を CSS に移行します。多くのプロジェクトでは @theme ブロックに移すだけで済みます。

2. content の設定が不要に

v4 は自動でソースファイルを検出するため、content の設定が不要になりました。

3. プラグインの互換性

v3 のプラグインがそのまま動かない場合があります。@tailwindcss/typography は v4 対応版を使いましょう。

pnpm add -D @tailwindcss/typography@latest

4. 一部のクラス名の変更

SvelteKit での設定例

このブログで実際に使っている設定を抜粋します。vite.config.ts 側はプラグインを並べるだけです。

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [tailwindcss(), sveltekit()]
});

CSS 側がやや複雑になります。ポイントは 4 つです。

/* src/routes/layout.css */
@import 'tailwindcss';
@import 'tw-animate-css';
@import 'shadcn-svelte/tailwind.css';
@import '@fontsource-variable/geist';

@custom-variant dark (&:is(.dark *));
@plugin '@tailwindcss/typography';

:root {
	--background: oklch(1 0 0);
	--foreground: oklch(0.145 0 0);
	--primary: oklch(0.45 0.16 155);
	--muted: oklch(0.97 0 0);
	/* ... */
}

.dark {
	--background: oklch(0.145 0 0);
	--foreground: oklch(0.985 0 0);
	--primary: oklch(0.65 0.18 155);
	/* ... */
}

@theme inline {
	--font-sans: 'Geist Variable', sans-serif;
	--color-background: var(--background);
	--color-foreground: var(--foreground);
	--color-primary: var(--primary);
	/* ... */
}

ポイント

1. @import 'tailwindcss' を先頭に置く — その後にプラグインや shadcn-svelte の追加 CSS を読み込む
2. @custom-variant dark でクラスベースのダークモードを定義 — v3 の darkMode: 'class' 相当
3. :root と .dark で CSS 変数を上書き — JavaScript で <html class="dark"> をトグルすれば配色が一斉に切り替わる
4. @theme inline で CSS 変数を Tailwind ユーティリティへ橋渡し — bg-background や text-primary などのクラスが、上で定義した --background / --primary を参照するようになる

@theme inline の inline は、変数の値を埋め込まずに var() 参照のまま展開する指定です。これにより .dark での再定義が遅延評価され、同じ bg-background クラスがライト/ダークで適切に切り替わります。

まとめ

Tailwind CSS v4 は設定方法が大きく変わりましたが、「CSS の中で完結する」というシンプルな方向への進化です。パフォーマンスも向上しているので、新規プロジェクトでは v4 を選択するのが良いでしょう。

参照

• Tailwind CSS 公式サイト
• Tailwind CSS v4 アップグレードガイド

前提

• 移行元の Svelte 4 プロジェクト（writable / derived / readable を使ったコードがあること）
• Svelte 5 にバージョンアップ済み、または並行で動作確認できる環境
• Svelte 5 は Svelte 4 の Store と後方互換性があるため、段階的な移行が可能

writable → $state

最も基本的な移行パターンです。

Before（Svelte 4）

// stores.ts
import { writable } from 'svelte/store';
export const count = writable(0);

<!-- Component.svelte -->
<script>
	import { count } from './stores';
</script>

<button on:click={() => $count++}>{$count}</button>

After（Svelte 5）

コンポーネント内で完結する状態なら、そのまま $state に置き換えます。

<script lang="ts">
	let count = $state(0);
</script>

<button onclick={() => count++}>{count}</button>

コンポーネント間で共有する状態

複数コンポーネントで状態を共有していた場合、.svelte.ts ファイルで Runes を使えます。

// counter.svelte.ts
let count = $state(0);

export function getCount() {
	return count;
}

export function increment() {
	count++;
}

export function reset() {
	count = 0;
}

<script lang="ts">
	import { getCount, increment } from './counter.svelte.ts';
</script>

<button onclick={increment}>{getCount()}</button>

ポイントは ファイル拡張子が .svelte.ts であること。これにより、ファイルのトップレベルで $state などの Runes が使えます。

derived → $derived

Before

import { writable, derived } from 'svelte/store';

const items = writable([1, 2, 3]);
const total = derived(items, ($items) => $items.reduce((a, b) => a + b, 0));

After

// cart.svelte.ts
let items = $state([1, 2, 3]);
let total = $derived(items.reduce((a, b) => a + b, 0));

$derived は依存関係を自動追跡するので、明示的に依存元を指定する必要がありません。

readable → $state（読み取り専用の公開）

外部に読み取り専用で公開したい場合は、getter 関数を使います。

Before

import { readable } from 'svelte/store';

export const time = readable(new Date(), (set) => {
	const interval = setInterval(() => set(new Date()), 1000);
	return () => clearInterval(interval);
});

After

// time.svelte.ts
let time = $state(new Date());

const interval = setInterval(() => {
	time = new Date();
}, 1000);

// getter で読み取り専用として公開
export function getTime() {
	return time;
}

クラスベースのアプローチ

より構造化したい場合は、クラスで状態をカプセル化できます。

// todo-store.svelte.ts
export class TodoStore {
	items = $state<{ text: string; done: boolean }[]>([]);

	get remaining() {
		return this.items.filter((item) => !item.done).length;
	}

	get completed() {
		return this.items.filter((item) => item.done).length;
	}

	add(text: string) {
		this.items.push({ text, done: false });
	}

	toggle(index: number) {
		this.items[index].done = !this.items[index].done;
	}

	remove(index: number) {
		this.items.splice(index, 1);
	}
}

<script lang="ts">
	import { TodoStore } from './todo-store.svelte.ts';

	const todos = new TodoStore();
</script>

<p>残り {todos.remaining} 件</p>
{#each todos.items as todo, i}
	<label>
		<input type="checkbox" checked={todo.done} onchange={() => todos.toggle(i)} />
		{todo.text}
	</label>
{/each}

まとめ

1. 段階的に移行できる — Svelte 5 は Store との後方互換性を持っています。一気に書き換える必要はありません
2. .svelte.ts を忘れずに — Runes をモジュールのトップレベルで使うには .svelte.ts 拡張子が必要です
3. $: ラベルは $derived / $effect に — 値の計算は $derived、副作用は $effect に分離しましょう
4. on:click → onclick — イベントハンドラの書き方も変わっています

Store はまだ使えますが、新しいコードでは Runes を使うことで、よりシンプルで直感的な状態管理ができます。

参照

• Svelte 5 移行ガイド
• Svelte Runes とは

前提

• Vite ベースのプロジェクト（SvelteKit / Vue / 素の Vite アプリなど）
• 本記事のサンプルは SvelteKit + mdsvex を使った構成を想定

基本の使い方

遅延インポート（デフォルト）

const modules = import.meta.glob('/src/posts/*.md');

返り値は、ファイルパスをキー、動的 import 関数を値とするオブジェクトです:

{
  '/src/posts/hello-world.md': () => import('/src/posts/hello-world.md'),
  '/src/posts/blog-setup.md': () => import('/src/posts/blog-setup.md'),
}

各モジュールは関数を呼び出したときに初めて読み込まれます（遅延ロード）。

即時インポート（eager）

const modules = import.meta.glob('/src/posts/*.md', { eager: true });

eager: true を指定すると、ビルド時にすべてのモジュールが即座に読み込まれます:

{
  '/src/posts/hello-world.md': { metadata: {...}, default: Component },
  '/src/posts/blog-setup.md': { metadata: {...}, default: Component },
}

ブログでの活用 — 記事一覧の取得

このブログで実際に使っているパターンです。

// src/lib/utils/posts.ts
export type PostMeta = {
	slug: string;
	title: string;
	description: string;
	date: string;
	tags: string[];
	draft?: boolean;
};

export async function getAllPosts(): Promise<PostMeta[]> {
	const modules = import.meta.glob('/src/posts/*.md', { eager: true });
	const posts: PostMeta[] = [];

	for (const [path, mod] of Object.entries(modules)) {
		const m = mod as { metadata: Omit<PostMeta, 'slug'> };
		const slug = path.split('/').pop()!.replace('.md', '');
		if (m.metadata.draft) continue;
		posts.push({ slug, ...m.metadata });
	}

	return posts.sort((a, b) => +new Date(b.date) - +new Date(a.date));
}

ポイント

• eager: true — SSG ではビルド時にすべて読み込むので eager が適切
• mod.metadata — mdsvex が Markdown のフロントマターを metadata として export
• mod.default — Svelte コンポーネントとしてレンダリング可能

glob パターン

import.meta.glob は glob パターンを受け付けます。

// 特定のディレクトリ
import.meta.glob('/src/posts/*.md');

// ネストしたディレクトリも含む
import.meta.glob('/src/posts/**/*.md');

// 複数パターン
import.meta.glob(['/src/posts/*.md', '/src/drafts/*.md']);

// 除外パターン
import.meta.glob('/src/posts/*.md', {
	// _で始まるファイルを除外
});

import オプション

as: 'raw' — 生のテキストとして取得

const files = import.meta.glob('/src/data/*.json', {
	eager: true,
	import: 'default',
	query: '?raw'
});

import — 特定の export だけ取得

// metadata だけ取得（コンポーネント本体は不要な場合）
const metas = import.meta.glob('/src/posts/*.md', {
	eager: true,
	import: 'metadata'
});

動的ルートとの組み合わせ

SvelteKit の動的ルートで、プリレンダリング対象のパスを列挙するのに使えます。

// src/routes/posts/[slug]/+page.ts
export async function entries() {
	const modules = import.meta.glob('/src/posts/*.md');
	return Object.keys(modules).map((path) => ({
		slug: path.split('/').pop()!.replace('.md', '')
	}));
}

export async function load({ params }) {
	const post = await import(`/src/posts/${params.slug}.md`);
	return {
		content: post.default,
		meta: post.metadata
	};
}

タグ一覧の生成

記事のメタデータから全タグを収集する例:

export async function getAllTags(): Promise<Map<string, number>> {
	const posts = await getAllPosts();
	const tagMap = new Map<string, number>();

	for (const post of posts) {
		for (const tag of post.tags ?? []) {
			tagMap.set(tag, (tagMap.get(tag) ?? 0) + 1);
		}
	}

	return tagMap;
}

注意点

1. glob パターンは静的でなければならない — 変数を使ったパターンは不可
2. ビルド時に解決される — ファイルの追加・削除は再ビルドが必要
3. パスは /src/ から始まる — プロジェクトルートからの絶対パス

// ❌ 変数は使えない
const dir = 'posts';
import.meta.glob(`/src/${dir}/*.md`);

// ✅ リテラルで指定
import.meta.glob('/src/posts/*.md');

まとめ

import.meta.glob は Vite の強力な機能で、ファイルシステムベースのコンテンツ管理に最適です。ブログの記事一覧、タグ一覧、動的ルートの生成など、SvelteKit の静的サイト構築で欠かせないツールです。

参照

• Vite Glob Import ドキュメント

前提

• SvelteKit プロジェクト（Svelte 5 を想定）
• Node.js v22 以上
• 既に svelte.config.js が存在し、vitePreprocess() などの preprocess を設定できる状態

セットアップ

pnpm add -D mdsvex

svelte.config.js に設定を追加します。

import { mdsvex } from 'mdsvex';

const config = {
	extensions: ['.svelte', '.svx', '.md'],
	preprocess: [
		vitePreprocess(),
		mdsvex({
			extensions: ['.svx', '.md']
		})
	]
};

.md ファイルを extensions に追加することで、Markdown ファイルが Svelte コンポーネントとして処理されます。

フロントマター

Markdown ファイルの先頭に YAML 形式でメタデータを記述できます。

---
title: 記事のタイトル
description: 記事の説明
date: 2026-03-06
tags:
  - svelte
  - markdown
---

本文がここから始まります。

フロントマターの値は metadata として export されるので、import で取得できます。

const post = await import('./my-post.md');
console.log(post.metadata.title); // "記事のタイトル"

カスタムレイアウト

すべての記事に共通のレイアウトを適用するには、layout オプションを使います。

mdsvex({
	extensions: ['.svx', '.md'],
	layout: {
		_: './src/lib/layouts/post.svelte'
	}
});

_ はデフォルトレイアウトを意味します。レイアウトコンポーネントではフロントマターの値が Props として渡されます。

<!-- src/lib/layouts/post.svelte -->
<script lang="ts">
	let { title, date, tags = [], children } = $props();
</script>

<article class="prose dark:prose-invert">
	<h1>{title}</h1>
	<time>{new Date(date).toLocaleDateString('ja-JP')}</time>
	{@render children()}
</article>

Markdown 内で Svelte コンポーネントを使う

mdsvex の強力な機能の一つが、Markdown 内での Svelte コンポーネントの利用です。

---
title: インタラクティブな記事
---

<script>
  import Counter from '$lib/components/Counter.svelte';
</script>

普通の Markdown テキストです。

<Counter />

↑ ボタンをクリックしてみてください。

これにより、静的な Markdown に動的なインタラクションを追加できます。

rehype / remark プラグイン

mdsvex は rehype（HTML 処理）と remark（Markdown 処理）のプラグインに対応しています。

rehype-slug — 見出しに ID を自動付与

pnpm add -D rehype-slug

import rehypeSlug from 'rehype-slug';

mdsvex({
	rehypePlugins: [rehypeSlug]
});

これにより ## セットアップ が <h2 id="セットアップ"> になり、見出しへの直接リンクが可能になります。

コードブロックのシンタックスハイライト

mdsvex はデフォルトで PrismJS によるシンタックスハイライトをサポートしています。Markdown のコードブロックに言語を指定するだけです。

```ts
const message: string = 'Hello, mdsvex!';
```

Shiki を使いたい場合は、rehype プラグインとして組み込むことも可能です。

import.meta.glob で記事を一括取得

SvelteKit の import.meta.glob と組み合わせて、すべての記事のメタデータを取得できます。

export async function getAllPosts() {
	const modules = import.meta.glob('/src/posts/*.md', { eager: true });
	const posts = [];

	for (const [path, mod] of Object.entries(modules)) {
		const slug = path.split('/').pop()!.replace('.md', '');
		const { metadata } = mod as { metadata: PostMeta };
		if (!metadata.draft) {
			posts.push({ slug, ...metadata });
		}
	}

	return posts.sort((a, b) => +new Date(b.date) - +new Date(a.date));
}

まとめ

mdsvex を使うことで、Markdown の手軽さと Svelte の表現力を両立できます。ブログや技術ドキュメントの構築に最適です。

• Markdown ファイルを Svelte コンポーネントとして処理
• フロントマターでメタデータを管理
• カスタムレイアウトで統一的なデザイン
• Svelte コンポーネントを記事に埋め込み可能
• rehype / remark プラグインで拡張できる

参照

• mdsvex 公式サイト
• mdsvex GitHub

前提

• SvelteKit プロジェクト（Svelte 5 を想定）
• Node.js v22 以上
• 全ページ静的化を想定する場合は、ユーザー固有データやクエリパラメータに依存するページを含まないこと

prerender の基本

ページごとに +page.ts で prerender を true に設定します。

// src/routes/+page.ts
export const prerender = true;

レイアウトに設定すると、配下のすべてのページに適用されます。

// src/routes/+layout.ts
export const prerender = true;

動的ルートのプリレンダリング

[slug] のような動的ルートは、ビルド時にどのパスを生成するか知る必要があります。entries 関数でパスの一覧を返します。

// src/routes/posts/[slug]/+page.ts
export const prerender = true;

export async function entries() {
	const modules = import.meta.glob('/src/posts/*.md');
	return Object.keys(modules).map((path) => ({
		slug: path.split('/').pop()!.replace('.md', '')
	}));
}

SvelteKit はページ内のリンクを辿って自動的にプリレンダリング対象を発見する クローリング も行います。トップページからリンクされているページは entries なしでもプリレンダリングされることがあります。ただし、確実に生成するためには entries を明示するのが安全です。

adapter-static vs adapter-cloudflare

全ページを静的にするなら adapter-static も選択肢ですが、このブログでは adapter-cloudflare を使っています。

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

const config = {
	kit: {
		adapter: adapter()
	}
};

adapter-cloudflare でも prerender = true のページは静的ファイルとして出力されるので、実質的に SSG と同じ動作になります。将来的にサーバーサイドの処理（API ルート、フォーム処理など）を追加したくなったときに柔軟に対応できるメリットがあります。

prerender できないケース

以下のようなページはプリレンダリングできません。

• ユーザー固有のデータを表示するページ — ログイン状態に依存する場合は SSR が必要
• 動的な検索結果 — クエリパラメータに基づく結果は静的に生成できない
• フォーム送信を処理するページ — +page.server.ts の actions を使う場合

// これは prerender できない
export async function load({ url }) {
	const q = url.searchParams.get('q'); // 無限のパターンがある
	return { results: await search(q) };
}

handleHttpError の設定

プリレンダリング中にリンク切れがあるとビルドが失敗します。開発中は warn に設定しておくと便利です。

// svelte.config.js
const config = {
	kit: {
		prerender: {
			handleHttpError: 'warn'
		}
	}
};

本番環境では fail（デフォルト）にしてリンク切れを検知するのがおすすめです。

ビルドと確認

pnpm build    # プリレンダリング実行
pnpm preview  # ビルド結果をローカルで確認

.svelte-kit/cloudflare/ に生成された HTML ファイルを確認すると、各ページが静的ファイルとして出力されていることが分かります。

まとめ

• prerender = true でページを静的に出力できる
• 動的ルートは entries でパスを列挙する
• adapter-cloudflare でも prerender は使える — 静的と動的のハイブリッド構成が可能
• 全ページ prerender にすれば実質 SSG として運用できる

参照

• SvelteKit プリレンダリング ドキュメント
• SvelteKit ドキュメント