11# AGENTS Guide (vuefes-japan-speakers)
22
3- このドキュメントは、本リポジトリで作業するエージェントや貢献者向けの実務ガイドです。セットアップ、構成、よくある変更、検証、デプロイの要点をまとめています 。
3+ このドキュメントは、本リポジトリで作業するエージェントや貢献者向けの実務ガイドです。セットアップ、構成、よくある変更、検証の要点をまとめています 。
44
55## プロジェクト概要
66
7- - フレームワーク: Nuxt 4 （Vue 3）
7+ - フレームワーク: vuerend （Vue 3 / Vite ）
88- 目的: 歴代の Vue Fes Japan スピーカーと発表タイトルを一覧できる非公式アーカイブ
9- - UI/スタイル: Nuxt UI 4 + Tailwind CSS 4 + カスタムコンポーネント
10- - データ供給: Nuxt サーバルート（` server/api ` ）から年別・全件データを返却
11- - デプロイ: NuxtHub / Cloudflare 系の設定を利用
9+ - UI/スタイル: Tailwind CSS 4 + カスタムコンポーネント
10+ - データ供給: ` server/data ` の静的データを vuerend ルートの props として渡す
1211
1312## 前提・セットアップ
1413
@@ -26,44 +25,47 @@ vp config
2625
2726## よく使うコマンド
2827
29- | 用途 | 推奨コマンド | npm script |
30- | --- | --- | --- |
31- | 開発サーバ | ` vp run dev ` | ` pnpm dev ` |
32- | ビルド | ` vp run build ` | ` pnpm build ` |
33- | 静的生成 | ` vp run generate ` | ` pnpm generate ` |
34- | プレビュー | ` vp run preview ` | ` pnpm preview ` |
35- | Lint | ` vp lint . ` | ` pnpm vp:lint ` |
36- | Format | ` vp fmt . ` | ` pnpm vp:fmt ` |
37- | Format 確認 | ` vp fmt . --check ` | - |
38- | Type Check | ` vp check ` | ` pnpm vp:check ` |
39- | Test | ` vp test run ` | ` pnpm vp:test ` |
40- | Test（watch） | ` vp test ` | ` pnpm vp:test:watch ` |
28+ | 用途 | 推奨コマンド | npm script |
29+ | ------------- | ------------------ | ----------------- --- |
30+ | 開発サーバ | ` vp run dev ` | ` pnpm dev ` |
31+ | ビルド | ` vp run build ` | ` pnpm build ` |
32+ | 静的生成 | ` vp run generate ` | ` pnpm generate ` |
33+ | プレビュー | ` vp run preview ` | ` pnpm preview ` |
34+ | Lint | ` vp lint . ` | ` pnpm vp:lint ` |
35+ | Format | ` vp fmt . ` | ` pnpm vp:fmt ` |
36+ | Format 確認 | ` vp fmt . --check ` | - |
37+ | Type Check | ` vp check ` | ` pnpm vp:check ` |
38+ | Test | ` vp test run ` | ` pnpm vp:test ` |
39+ | Test（watch） | ` vp test ` | ` pnpm vp:test:watch ` |
4140
4241作業前後の検証は、変更内容に応じて ` vp lint . ` 、` vp fmt . --check ` 、` vp check ` 、` vp test run ` を組み合わせます。
4342
4443## ディレクトリ構成（要点）
4544
4645- ` app/ `
47- - ` app.vue ` : ルート、SEO、フォント、アイコンなどの共通設定
48- - ` pages/ ` : トップ、年別一覧、スピーカー詳細ページ
46+ - ` app.ts ` : vuerend アプリとルート定義
47+ - ` routes/ ` : ルートコンポーネント
48+ - ` islands/ ` : クライアントで hydrate するページ island
49+ - ` island-definitions.ts ` : island 定義
50+ - ` islands.ts ` : クライアント island レジストリ
4951 - ` components/ ` : ヘッダー、フッター、マストヘッド、一覧・タイムライン、フィルタ UI
5052 - ` composables/ ` : ` useVfjsI18n ` 、` useColorScheme ` 、スピーカー取得・絞り込みロジック
5153 - ` utils/ ` : 年判定、文字列ソート、スピーカー集約などのユーティリティ
5254 - ` assets/css/main.css ` : Tailwind 読み込み、フォント、カラートークン、フォーカススタイル
5355- ` server/ `
54- - ` api/ ` : ` /api/speakers ` と ` /api/speakers/[year] `
55- - ` data/ ` : 年別スピーカーデータと集約ロジック
56+ - ` data/ ` : 年別スピーカーデータ（` speakers-YYYY.ts ` ）と集約ロジック
5657- ` types/ ` : ` SpeakerInfo ` 、` SpeakerWithYear ` 、` YEARS ` などの共有型
5758- ` public/ ` : ロゴ、favicon、OG 画像などの静的ファイル
5859- ` pnpm-workspace.yaml ` : catalog と依存バージョンの定義
59- - ` vite.config.ts ` : Vite+ の lint / staged 設定
60- - ` vitest.config.ts ` : Nuxt テスト環境と happy-dom 設定
61- - ` nuxt .config.ts ` : Nuxt モジュール、Nitro、NuxtHub、ESLint 設定
60+ - ` vite.config.ts ` : Vite / vuerend / Vite+ の設定
61+ - ` vitest.config.ts ` : Vitest Browser Mode（Playwright / Chromium）の設定
62+ - ` eslint .config.mjs ` , ` tsconfig.json ` : ツール設定
6263
63- ## API とデータ
64+ ## ルートとデータ
6465
65- - 全件: ` server/api/speakers.ts `
66- - 年別: ` server/api/speakers/[year].ts `
66+ - 全件: ` app/app.ts ` の ` / ` ルートで ` getAllSpeakersWithYear() ` を渡す
67+ - 年別: ` app/app.ts ` の ` /:year ` ルートで ` getSpeakersByYear(year) ` を渡す
68+ - スピーカー別: ` app/app.ts ` の ` /speakers/:name ` ルートで ` getSpeakerTalks(name) ` を渡す
6769- データ源: ` server/data/speakers-YYYY.ts `
6870- 集約: ` server/data/index.ts `
6971- 有効年: ` types/index.ts ` の ` YEARS `
@@ -75,16 +77,20 @@ vp config
7577- ` server/data/speakers-YYYY.ts ` を作成し、` SpeakerInfo[] ` に沿ってデータを定義する。
7678- ` server/data/index.ts ` に import と ` speakersByYear ` のエントリを追加する。
7779- ` types/index.ts ` の ` YEARS ` に年を追加する。UI の年表示はこの値を参照します。
78- - ` server/api/speakers/[year] .test.ts ` の有効年・エラーメッセージ期待値を更新する 。
80+ - ` server/data/index .test.ts ` や該当 island のテストで props と表示が期待通りか検証する 。
7981- 必要に応じて ` README.md ` の参考リンクも更新する。
8082- ` / ` 、` /[year] ` 、` /speakers/[name] ` で表示とリンクを確認する。
8183
8284## UI/ページの要点
8385
8486- ルーティング:
85- - ` app/pages/index.vue ` : 全体ビュー。タイムライン表示と一覧表示を切り替えます。
86- - ` app/pages/[year]/index.vue ` : 年別一覧ページ
87- - ` app/pages/speakers/[name]/index.vue ` : スピーカー詳細ページ
87+ - ` app/routes/HomeRoute.ts ` : 全体一覧ページ
88+ - ` app/routes/YearRoute.ts ` : 年別一覧ページ
89+ - ` app/routes/SpeakerRoute.ts ` : スピーカー詳細ページ
90+ - ページ island:
91+ - ` HomePageIsland.vue ` : 全体一覧のインタラクション
92+ - ` YearPageIsland.vue ` : 年別一覧のインタラクション
93+ - ` SpeakerPageIsland.vue ` : スピーカー詳細のインタラクション
8894- 主要コンポーネント:
8995 - ` AppHeader.vue ` : ナビゲーション、言語切替、配色切替
9096 - ` AppMasthead.vue ` : トップページの概要・統計表示
@@ -96,6 +102,7 @@ vp config
96102 - トップページの view は ` localStorage('vfjs:view') ` に保存されます。
97103 - density は ` localStorage('vfjs:density') ` に保存されます。
98104 - 言語は ` localStorage('vfjs:lang') ` に保存されます。
105+ - スタイル: Tailwind CSS 4 ユーティリティ + CSS カスタムプロパティ（` var(--paper) ` , ` var(--ink) ` , ` var(--accent) ` 等）
99106
100107## カラースキーム
101108
@@ -113,7 +120,7 @@ vp config
113120## テスト
114121
115122- ランナー: Vitest（Vite+ 経由）
116- - DOM: Nuxt テスト環境 + happy-dom
123+ - 実行環境: Vitest Browser Mode（Playwright / Chromium）
117124- 設定: ` vitest.config.ts `
118125- テスト位置:
119126 - ` app/**.test.ts `
@@ -129,8 +136,9 @@ vp test run
129136### テスト方針
130137
131138- ユニットテストは入出力と副作用の最小検証に集中する。
132- - API ルートは有効値、境界値、異常系を確認する。
133- - 年追加時は ` YEARS ` 、API のエラーメッセージ、UI 側の年表示が連動しているか確認する。
139+ - データ取得ロジックは有効値、境界値、異常系を確認する。
140+ - 年追加時は ` YEARS ` 、データ集約、UI 側の年表示が連動しているか確認する。
141+ - Browser Mode で落ちる場合は、まず ` vitest.config.ts ` の ` browser ` 設定と Playwright のブラウザ導入状況を確認する。
134142
135143## 型チェックと lint
136144
@@ -152,7 +160,7 @@ vp test run
152160
153161### コンポーネントを追加
154162
155- - ` app/components/ ` に追加し、該当ページで利用する 。
163+ - ` app/components/ ` に追加し、該当ページや island で利用する 。
156164- 既存の CSS カスタムプロパティと Tailwind ユーティリティに合わせる。
157165- グローバルな見た目やフォーカススタイルは ` app/assets/css/main.css ` を確認する。
158166- UI の振る舞いは小さな単位でテストする。
@@ -172,17 +180,7 @@ GitHub Actions は Vite+ セットアップ後に以下を実行します。
172180- ` vp check `
173181- ` vp test run `
174182
175- CI の対象 path は ` app/** ` 、` server/** ` 、` types/** ` 、各種設定ファイル、lockfile などです。ドキュメントのみの変更では一部の workflow が走らない場合があります。
176-
177- ## デプロイ
178-
179- NuxtHub へのデプロイは以下を使います。
180-
181- ``` bash
182- vpx nuxthub deploy
183- ```
184-
185- NuxtHub / Cloudflare 関連の依存は ` pnpm-workspace.yaml ` の ` cloudflare ` catalog にまとまっています。
183+ Browser Mode の test job では、テスト前に ` vp exec playwright install --with-deps chromium ` で Chromium を導入します。CI の対象 path は ` app/** ` 、` server/** ` 、` types/** ` 、各種設定ファイル、lockfile などです。ドキュメントのみの変更では一部の workflow が走らない場合があります。
186184
187185## 開発フロー（推奨）
188186
@@ -194,8 +192,8 @@ NuxtHub / Cloudflare 関連の依存は `pnpm-workspace.yaml` の `cloudflare` c
194192
195193## トラブルシュート
196194
197- - 依存関係の不整合 : ` vp install ` を実行し、必要なら ` vp config ` も実行する 。
198- - パッケージマネージャーの確認 : ` pnpm -v ` で ` 10.33.2 ` 系か確認する 。
199- - 型エラー: ` vp check ` で原因を洗い出し、型定義・import・データ構造を直す 。
200- - Nuxt 生成物の不整合: 開発サーバを再起動し、必要なら ` vp config ` を再実行する 。
201- - テスト環境の差異: ` vitest.config.ts ` の Nuxt 環境と happy-dom 設定を確認する 。
195+ - Node/pnpm の不整合 : ` node -v ` と ` pnpm -v ` を確認する 。
196+ - Vite+ 設定の不整合 : ` vp config ` を再実行する 。
197+ - 型エラー: ` vp check ` で先に洗い出す。型を消してエラーを隠さない 。
198+ - Browser Mode のブラウザ不足: ` vp exec playwright install chromium ` を実行する。Linux CI では ` --with-deps ` も付ける 。
199+ - キャッシュ問題: Vite や生成物のキャッシュが怪しい場合は開発サーバを再起動する 。
0 commit comments