tech-stack

FMC の技術スタック

FixMyBerlin / FMC における地理情報を多用する React SPAの標準スタックです。アプリの新規作成や変更時の技術選定に使用してください。個々のライブラリを深く掘り下げるものではありません。

関連スキルは個別にインストールしてください：bunx skills add FixMyBerlin/fixmyskills --skill <name> -g -a claude-code -y

適用するタイミング

• 新規アプリのスキャフォールド（依存関係、ツール、フォルダー構成）
• package.json のスクリプトの追加または名前変更
• ライブラリやパターンの選定（「X を使うべきか？」）
• 既存アプリの横断的な規約の確認
• Postgres スキーマの調査、エージェントによるデータベースクエリ、またはブラウザー探索 MCP 用の Claude Code MCP セットアップ

LLM リソース

references/llm-resources.md は、タスクに関係する領域についてのみ読み込んでください。

マップ： スキル react-map-gl を読み込みます（また、スキルで参照されている場合は上流の React Map GL ドキュメント も読み込みます）。

専門スキル

スキルは名前で参照してください。不足しているスキルは上記のコマンドでインストールしてください。

領域	スキル
Rust/WASM の地理情報処理	rust-wasm-geo
マップ（react-map-gl）	react-map-gl
React TS のパターン、useEffect の運用	react-dev
TanStack Router（検索、ローダー、Query）	tanstack-router-conventions（参照：params-search-ui-routes.md、見やすい URL 用の router-search-serialization.md、router-and-query.md、devtools.md）
TanStack Start（境界、SSR、サーバー）	tanstack-start-conventions（フォルダー構成の参照：app-structure.md）
URL の状態管理（TanStack Router 使用時）	tanstack-router-conventions → params-search-ui-routes.md
URL の状態管理（Router を使わない Vite アプリ）	nuqs
クライアントのグローバル状態	zustand-state-management
Prisma スキーマの命名、マイグレーション	prisma
E2E / Playwright	playwright-skill

ランタイムとビルド

• ランタイム／パッケージマネージャー： Bun — インストール方針は bun-install.md を参照（≥ 1.3.14、グローバルストア、Vite では bun --bun、Prisma／Playwright では .nvmrc、Docker イメージのインストールと Netlify 関数のパッケージ化）
• ビルド： 最新の Vite（8+）
• Lint／フォーマット： 修正フラグ付きの oxlint と oxfmt。Prettier 互換のデフォルト設定：
  • クラスの並べ替え、インポートの並べ替え、package.json の並べ替え
  • printWidth 100、セミコロンは asNeeded、シングルクォート
  • 'typescript/switch-exhaustiveness-check': 'error'
  • React Compiler：oxlint の react プラグインと 'react/unsupported-syntax': 'error'。Vite では viteReact({ compiler: true }) と oxc-transform-react を使用（Babel は不使用）
  • テンプレート：examples/oxfmt.config.mjs、examples/oxlint.config.mjs
  • セットアップとプロジェクトごとの調整：references/oxc-config.md
• クライアントのブラウザー対象： package.json の browserslist が、Vite クライアントの build.target と oxlint の eslint-plugin-compat を設定します — references/browser-target.md

React と TypeScript

• UI： React 19
• TypeScript（デフォルト）： typescript@^7（ネイティブ移植版。7.0 リリース）。bun run type-check 経由で tsc --noEmit を使って型チェックします。ワークスペースの typescript パッケージは CLI（tsc）とエディターの言語サービスの両方を提供します。型チェック用に別のコンパイラーバイナリを追加しないでください。ナイトリービルド：typescript@next（廃止された @typescript/native-preview パッケージではありません）。
• エディターと CLI の整合性： js/ts.tsdk.path は、tsc と同じ devDependencies.typescript のインストール先（lib/ ではなくパッケージルート）を指す必要があります。不整合があると、IDE の診断結果が bun run type-check と食い違います。
• スキャフォールド（TS 7）： package.json — devDependencies.typescript は ^7、スクリプトは "type-check": "tsc --noEmit"（tsconfig を分割している場合は -p を追加）。CI が開発環境とは異なるプラットフォームで実行される場合は、@typescript/typescript-darwin-arm64 / @typescript/typescript-linux-x64 を同じバージョンで optionalDependencies に固定します（typescript パッケージではこれらはオプションとして列挙されています。必要に応じて他のプラットフォームも追加してください）。bunfig.toml — bun-install.md。.vscode/settings.json（テンプレート：examples/vscode.settings.typescript.json.template）をコミットし、.vscode/extensions.json で TypeScript 7 拡張機能を推奨します（examples/vscode.extensions.json.template）。
• モノレポ： TypeScript がパッケージのサブフォルダーにある場合は、js/ts.tsdk.path にそのパッケージの node_modules/typescript へのパスを指定します（例：app/node_modules/typescript — tilda-geo）。
• Cursor / VS Code： TypeScript 7（TypeScriptTeam.native-preview — マーケットプレイス ID は変更なし）をインストールします。コマンドパレットの TypeScript: Enable TypeScript 7 または設定テンプレートを使って有効にします。examples/vscode.settings.typescript.json.template を .vscode/settings.json にコピーします（references/oxc-config.md の oxc キーとマージしてください）。エディタープラグインが TS 6 を必要とする場合（Vue、Astro、Svelte、Angular のテンプレート — リリースノートを参照）は、Disable TypeScript 7 Language Server で切り替えます。
• Claude Code MCP（ユーザーレベル）： claude mcp add --scope user のみ（~/.claude.json）— examples/mcp.json.template。Postgres：references/postgres-mcp.md。ブラウザーでの調査：references/agent-browser-mcp.md。
• Claude Code ルール（アプリレベル）： スキャフォールド時に examples/package-json-scripts.md.template を .claude/rules/package-json-scripts.md にコピーします — references/package-json-scripts.md

確認： node -e "console.log(require('typescript/package.json').version)"、tsc --version、bun run type-check を実行し、すべてが 7.x であることを確認します。エディターでは、TypeScript 7 が有効になっていることを確認します（ステータスバー／コマンドパレット）。このスキルのモノレポのように TS ソースがないリポジトリには、typescript を追加しないでください。

• React Compiler： デフォルトで有効です。メモ化と型付けの規約については、スキル react-dev を参照してください
• GeoJSON： すべての GeoJSON ペイロードに @types/geojson を使用します
• 日付／時刻： @date-fns/tz
• バリデーション： Zod 4

tsconfig のテンプレート

2 つのプロファイルを使用してください。アプリとスクリプトを 1 つの設定にまとめないでください。

プロファイル	テンプレート	プロファイルの相当例
アプリ（DOM、TanStack Start）	examples/tsconfig.app.json	total-typescript bundler/dom
スクリプト（CLI、DOM なし）	examples/tsconfig.scripts.json	total-typescript bundler/no-dom

compilerOptions.types に bun-types / web を含める場合は、必ず型パッケージが必要です。これらの名前は組み込みではなく npm パッケージです。直接の devDependencies としてインストールしてください（Knip と globalStore は推移的な依存関係を自分の依存関係として扱いません。knip.md / bun-install.md）：

• Bun の最低バージョンに合わせて @types/bun を固定します（1.3.14）
• bun-types を直接の依存関係として追加します（その最低バージョンに対する ^）。types はパッケージ名 bun-types を検索するため、@types/bun だけでは不十分です
• 設定に "web" が記載されている場合は @types/web も追加します

スクリプトプロファイル（types: ["bun-types"]）では、DOM がなくても @types/bun と bun-types の両方が必要です。Bun スクリプトでは Glob / Bun.file() を使用してください。これらの依存関係を追加して初めて、型安全に使用できます。追加しない場合、エージェントは node:fs に頼ることになります。

スキャフォールド時にコピーして調整してください。プロジェクトの構成に合わせて paths（./src/* と ./*）を調整します。リポジトリに .js ファイルが残っている場合に限り、allowJs: true を追加してください。

TanStack Start（アプリのみ）： verbatimModuleSyntax: false にしてください。型のみのインポートが空のランタイムインポートになり、サーバーコードがクライアントバンドルに漏れる可能性があります。tsconfig.app.json の冒頭のコメントを参照してください。

@total-typescript/tsconfig は絶対にインストールしたり、extends で指定したりしないでください。設定は逸脱理由のコメントとともにインラインで記述してください。

型チェック：

tsc --noEmit -p tsconfig.app.json && tsc --noEmit -p tsconfig.scripts.json

単一設定のリポジトリ（アプリとスクリプトをカバーするルートの tsconfig.json が 1 つだけある場合など）も許容されます。新規の TanStack Start アプリでは、設定を分けることを推奨します。

Astro / 単一設定： extends: astro/tsconfigs/strict を維持してください。types は ["bun-types", "web"] に設定します。vite/client は追加しないでください（Astro のクライアント型は .astro/types.d.ts から提供されます）。同じ tsconfig 内のスクリプトにも、Bun の型が必要です（上記と同じパッケージ）。

任意で、両方の子設定への "references" を含むルート tsconfig.json を追加できます。

ES2025： target と lib は同期させてください。ES2025 の新しいランタイム API は、クライアントでは意図的に使用し、サーバー / Bun / スクリプトでは問題なく使用できます。クライアントバンドルの対象となるブラウザーについては、references/browser-target.md を参照してください。

コンポーネントの型付け、Compiler、oxlint の React ルール、useEffect の運用規律については、スキル react-dev を参照してください。マップのカメラ、クリック、レイヤーについては、スキル react-map-gl を参照してください（useEffect + map.on() は使用しないでください）。

データと状態

必要なもの	選択
サーバー／非同期データ	TanStack Query — 生の useEffect によるフェッチは避けます。ルーターが対応している場合は Suspense を使用します
フォーム（複雑なもの）	TanStack Form
ルーティング	TanStack Router / Start
共有可能な URL の状態（TanStack Router を使用する場合）	ルートの validateSearch（Zod）を使用し、nuqs は使いません — tanstack-router-conventions → params-search-ui-routes.md を参照
共有可能な URL の状態（TanStack Router を使用しない Vite アプリ）	nuqs — スキル nuqs を参照
頻繁に更新される URL	@tanstack/react-pacer — https://tanstack.com/pacer/latest を参照
グローバルなクライアント状態	Zustand（tkdodo のパターン）— スキル zustand-state-management を参照
ローカル UI 状態	useState
Prisma スキーマ／マイグレーション	スキル prisma — 命名、リレーションフィールド、マイグレーションのワークフロー

Loader と Query の統合：スキル tanstack-router-conventions → router-and-query.md を参照してください。

スタイリングと UI

• CSS： Tailwind CSS、@tailwindcss/forms、@tailwindcss/typography
• クラスのマージ： twJoin、twMerge を使った tailwind-merge
• フォント： Fontsource のインポート
• アクセシビリティ： セマンティック HTML、キーボードで操作できるマップコントロール

地図と地理空間（JS）

選択肢のみです。地図コンポーネントのパターン、レイヤー、イベント、URL のビューポートについては、スキル react-map-gl を参照してください。

選択項目	デフォルト
ライブラリ	コンポーネント内では生の MapLibre ではなく、react-map-gl/maplibre を使用します
ベースマップ	OpenFreeMap。必要に応じて Maptiler を使用します
座標	API 境界では WGS84 を使用し、Zod で検証します
Turf	関数ごとに @turf/* をインポートします。import * as turf は使用しません
フィーチャーの編集	@osm-editor-kit/react-map-gl-draw（制御対象の value / onChange、スタイルはレイヤースタイルとして指定）。例：tilda-geo の描画。以前使用され、現在も代替候補となるもの：TerraDraw と maplibre-gl-terradraw

Rust / WASM による地理空間処理

Turf と WASM の比較、クレート、Vite の連携については、スキル rust-wasm-geo を参照してください。

依存関係の更新（Dependabot）

• プロジェクトの種類に応じてスケジュールを設定します。不明な場合はAskUserQuestionを使用してください。FixMyCity：毎週月曜日。Private OSS と Astro：毎月第1金曜日。同じテンプレートを使用します。詳細：dependabot.md。
• エコシステムごとにオープン PR は一度に1件まで（open-pull-requests-limit: 1）。
• テンプレート：examples/dependabot.yml.template
• **PR のレビューとマージ：**スキル review-dependabot（変更履歴のトリアージ、リスク区分、リベースマージ）

CI（GitHub Actions）

• PR の依存関係レビュー：制限の緩い allow-licenses（非推奨の deny-licenses ではありません）。プロジェクトが AGPL の場合は AGPL-3.0 と AGPL-3.0-or-later を含めます。テンプレート：examples/ci.yml.template

テストと品質

必要な内容	スキル／ツール
単体テスト／コンポーネントテスト	Vitest（常に使用）
ルート間、マップ、または認証フロー	playwright-skill
純粋なロジック／ユーティリティのみ	Vitest — Playwright は使用しません
明示的な依存関係／未使用のエクスポート	knip.md · スクリプトを確認 package-json-scripts.md