typescript

TypeScript ガイドライン

最新のツールを用いた TypeScript 開発の標準とベストプラクティスです。TypeScript コードの作成や変更時には、以下のガイドラインに従ってください。

設計原則

DRY、KISS、SOLID を一貫して適用します。該当する場合は関数型のアプローチを優先し、状態を持つ動作にはクラスを使用します。継承よりもコンポジションを優先します。各モジュールは単一の責務を持つようにします。クラスの依存関係には依存性注入を使用します。

コードスタイル

• 命名：変数、関数、クラスには、説明的でありながら簡潔な名前を付けます
• ドキュメント：公開 API、複雑なロジック、明白でない設計上の判断には JSDoc コメントを記述します
• 型注釈：推論時間を短縮するため、明示的に型を指定します。必要な場合を除き、any は避けます
• インポート：循環依存を防ぐため、バレルエクスポートは避け、直接インポートを優先します

型安全性

• Strict TypeScript：適切な型定義とともに strict モードを使用します。該当する場合は、検証用の Zod スキーマや型安全な DOM ヘルパーなど、型安全なパターンを使用します。
• any を避ける：型が本当に不明な場合は、any の代わりに unknown を使用します。型を適切に絞り込みます。
• 型推論：推論時間を短縮し、明確さを高めるため、明示的に型を指定します

型のパターン

• ユニオン型：複数の型のいずれかになり得る値には、ユニオン型を使用します
• 判別可能なユニオン：型安全な状態機械には、判別可能なユニオンを使用します
• ジェネリック制約：型安全性を確保するため、ジェネリック制約を使用します
• ユーティリティ型：TypeScript のユーティリティ型（Pick、Omit、Partial など）を活用します

アーキテクチャ

モジュールの構成

• 各モジュールは、明確な境界を設けて1つの関心事に集中します
• 重複を避けるため、再利用可能な関数を切り出します
• さまざまなコンテキストで再利用できるように設計します
• 型は使用箇所の近く、または専用の型ファイルに配置します
• 型は適切なモジュール境界に配置します

依存関係の管理

• テスト容易性のために依存性注入を使用します
• 継承よりもコンポジションを優先します
• 依存関係は最小限にし、目的を絞ります

テスト

構成

• テストは src/ ディレクトリの構成に合わせます
• テストファイル：*.test.ts または *.spec.ts
• 説明的なテスト名を使用します
• コードを変更する際は、適切な単体テストがあるか必ず確認します

品質

• AAA（準備、実行、検証）パターンを使用します
• テストは有用で、読みやすく、簡潔で、保守しやすいものにします
• エッジケースとエラー条件をテストします
• 重要な処理経路のテストカバレッジを維持します

ツール

• Vitest：単体テストと統合テストには Vitest を使用します（Jest より推奨）
• カバレッジには @vitest/coverage-v8 を使用します
• 必要に応じて DOM テストに jsdom を使用します
• 外部依存関係は適切にモックします
• Playwright：エンドツーエンド（E2E）テストには Playwright を使用します

コードのフォーマットとリンティング

Prettier

• 一貫したコードフォーマットには Prettier を使用します
• 設定：printWidth: 120、singleQuote: true、jsxSingleQuote: true
• pnpm format を実行してコードをフォーマットします
• pnpm format:check を実行してフォーマットを確認します

ESLint

• TypeScript プラグインとともに ESLint を使用します
• @typescript-eslint/parser と @typescript-eslint/eslint-plugin を使用します
• pnpm lint を実行してリンティングを確認します
• pnpm lint:fix を実行して問題を自動修正します

フレームワークの推奨事項

クライアントとのやり取りが少ない場合

• Astro：コンテンツ中心のサイト、ブログ、ドキュメントに最適です
  • デフォルトで JavaScript を最小限に抑えます
  • 必要に応じてサーバーアイランドを使用した静的生成が可能です
  • 優れたパフォーマンスと SEO を実現します
  • TypeScript を第一に考えた設計で、優れた DX を提供します

クライアントとのやり取りが多い場合

• TypeScript と React、Svelte、または SolidJS を使用します
• チームの好みとプロジェクトの要件に基づいて選択します

ビルドツール

• Vite：開発と本番環境で推奨するビルドツールです（特に指定がない限り）
• 最新の Rust ベースのツール：Rolldown などの低レベル言語ツールを優先します
  • 特に必要な場合を除き、Webpack などの旧式の JavaScript ベースのバンドラーは避けます

パッケージ管理

• pnpm：推奨パッケージマネージャーです（npm／yarn より高速で効率的です）
• package.json の packageManager フィールドを使用します
• モノレポでは pnpm ワークスペースを使用します

実装

TypeScript コードを実装する際は、次の点に注意してください。

• コミット前に、コードが型チェックを通過することを確認します
• 関連する変更とテストをまとめて、アトミックコミットにします
• 既存のワークフローパターン（仕様先行、TDD など）を確認し、それに従います

参考資料

pnpm を使用するモノレポ固有のパターンについては、references/pnpm-monorepo.md を参照してください。