typescript-strict

TypeScript Strict Mode

最大限の安全性と開発者体験を実現する、厳密な型チェックを備えた最新の TypeScript 設定です。このガイドでは、2025 年における TypeScript 5.x のベストプラクティスに焦点を当てます。

主な専門知識

Strict Mode とは？

• 型安全性：コンパイル時により多くのバグを検出します
• IDE でのより良い体験：オートコンプリートとリファクタリングが向上します
• 保守性：明示的な型を使った自己文書化コードを実現します
• 最新のデフォルト設定：現在の TypeScript のベストプラクティスに沿っています

主な機能

• 厳密な null チェック
• 厳密な関数型
• 暗黙的な any の禁止
• インデックスアクセス時の未チェックを禁止
• 適切なモジュール解決
• 最新の import/export 構文の適用

推奨する tsconfig.json（2025 年）

最小限の本番環境向け設定

{
  "compilerOptions": {
    // Type Checking
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,

    // Modules
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": false,
    "verbatimModuleSyntax": true,

    // Emit
    "target": "ES2022",
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "outDir": "dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "removeComments": false,
    "noEmit": false,

    // Interop
    "isolatedModules": true,
    "allowJs": false,
    "checkJs": false,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "build"]
}

Strict フラグの説明

strict: true（包括フラグ）

すべての厳密な型チェックオプションを有効にします。

{
  "strict": true
  // Equivalent to:
  // "noImplicitAny": true,
  // "strictNullChecks": true,
  // "strictFunctionTypes": true,
  // "strictBindCallApply": true,
  // "strictPropertyInitialization": true,
  // "noImplicitThis": true,
  // "alwaysStrict": true
}

新しいプロジェクトでは、常に strict: true を有効にしてください。

追加の Strict フラグ（2025 年に推奨）

フラグ	目的
noUncheckedIndexedAccess	インデックスシグネチャの戻り値を T ではなく T | undefined にします
noImplicitOverride	オーバーライドするメソッドに override キーワードを必須にします
noPropertyAccessFromIndexSignature	インデックスシグネチャへのアクセスにブラケット記法を必須にします
noFallthroughCasesInSwitch	switch 文でのフォールスルーを防ぎます
exactOptionalPropertyTypes	オプショナルプロパティに undefined を明示的に設定できないようにします

noUncheckedIndexedAccess（必須）

// With noUncheckedIndexedAccess
const users: Record<string, User> = {};
const user = users['john'];
// Type: User | undefined (correct - must check before use)

if (user) {
  console.log(user.name); // Type narrowed to User
}

実行時エラーを防ぐため、このフラグは常に有効にしてください。

モジュール解決

戦略の選択

戦略	用途	拡張子の指定
Bundler	Vite、Webpack、Bun のプロジェクト	不要
NodeNext	Node.js のライブラリとサーバー	必要（.js）

moduleResolution: "Bundler"（Vite/Bun）

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler"
  }
}

• import でファイル拡張子を指定する必要はありません
• アサーションなしで JSON をインポートできます
• package.json の exports フィールドをサポートします

moduleResolution: "NodeNext"（Node.js）

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

• package.json の type: "module" に従います
• 明示的な .js 拡張子が必要です（.ts ファイルの場合も同様）
• 条件付きエクスポートをサポートします

verbatimModuleSyntax（2025 年に推奨）

TypeScript による import/export の書き換えを防ぎます。

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

// Error: 'User' is a type and must be imported with 'import type'
import { User } from './types';

// Correct
import type { User } from './types';

// Correct (mixed import)
import { fetchUser, type User } from './api';

非推奨の importsNotUsedAsValues と preserveValueImports を置き換えます。

エージェント向けの最適化

コンテキスト	コマンド
エラーを確認	bunx tsc --noEmit
単一ファイルを確認	bunx tsc --noEmit src/utils.ts
設定を表示	bunx tsc --showConfig
モジュール解決を確認	bunx tsc --showConfig | grep moduleResolution

クイックリファレンス

推奨フラグ

フラグ	値	カテゴリー
strict	true	型チェック
noUncheckedIndexedAccess	true	型チェック
noImplicitOverride	true	型チェック
noPropertyAccessFromIndexSignature	true	型チェック
noFallthroughCasesInSwitch	true	型チェック
module	ESNext / NodeNext	モジュール
moduleResolution	Bundler / NodeNext	モジュール
verbatimModuleSyntax	true	モジュール
target	ES2022	出力
lib	Temporal 型を使うには "ESNext" を追加します（TS 6.0 以降）。typescript-temporal を参照してください	型チェック
isolatedModules	true	相互運用性
skipLibCheck	true	相互運用性

詳しい例、高度なパターン、ベストプラクティスについては、REFERENCE.md を参照してください。

参考資料

• TypeScript Handbook：https://www.typescriptlang.org/docs/handbook/intro.html
• TSConfig Reference：https://www.typescriptlang.org/tsconfig
• Strict Mode Guide：https://www.typescriptlang.org/tsconfig#strict
• Module Resolution：https://www.typescriptlang.org/docs/handbook/module-resolution.html
• Best Practices：https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html