typescript-best-practices

TypeScript ベストプラクティス & プロジェクト初期設定スキル

メタデータ

• トリガー: 「TypeScript設定」「tsconfig設定」「TypeScriptプロジェクト初期設定」「型安全」
• 前提条件: Node.js プロジェクト

概要

TypeScript プロジェクトの初期設定と型安全なコーディングのベストプラクティスを提供するスキル。 tsconfig.json の最適設定、パス エイリアス、厳格モードの段階的導入をガイドする。

---

Phase 1: TypeScript 導入判定

1.1 新規プロジェクト

npm install --save-dev typescript @types/node
npx tsc --init

1.2 既存 JavaScript プロジェクトの移行

npm install --save-dev typescript @types/node
# allowJs: true で段階的に移行

---

Phase 2: tsconfig.json 推奨設定

2.1 厳格モード（推奨）

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],

    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": false,

    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,

    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "coverage", "**/*.test.ts"]
}

2.2 フレームワーク別追加設定

Next.js:

{
  "compilerOptions": {
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }]
  }
}

React (Vite):

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "bundler"
  }
}

---

Phase 3: 型安全コーディングガイドライン

3.1 避けるべきパターン

// BAD: any の使用
function process(data: any) { ... }

// GOOD: 適切な型定義
interface ProcessInput {
  id: string;
  value: number;
}
function process(data: ProcessInput) { ... }

// BAD: 型アサーション の乱用
const user = response as User;

// GOOD: 型ガードの使用
function isUser(obj: unknown): obj is User {
  return typeof obj === 'object' && obj !== null && 'id' in obj;
}
if (isUser(response)) { ... }

// BAD: Non-null assertion の乱用
const name = user!.name;

// GOOD: オプショナルチェーン + nullish coalescing
const name = user?.name ?? 'Unknown';