allowjs-mixing

allowJs を使用して TypeScript と JavaScript を混在させる

概要

大規模な JavaScript コードベースを TypeScript に移行する際、すべてを一度に置き換える必要はありません。コンパイラーオプション allowJs を使うと、同じプロジェクト内で .ts ファイルと .js ファイルを混在させ、段階的に TypeScript を導入できます。これにより、コードベースを動作する状態に保ちながら、ファイルを 1 つずつ変換していく段階的な移行が可能になります。

このアプローチは、一気に書き換えることが現実的ではない大規模な移行に不可欠です。

このスキルを使う場面

• JavaScript プロジェクトを TypeScript に移行するとき
• JS コードベースに TypeScript を段階的に導入するとき
• TypeScript と JavaScript が混在するチームで作業するとき
• 既存の大規模プロジェクトを変換するとき
• チームがまだ TypeScript を学んでいるとき

絶対に守るルール

段階的な移行を可能にするため、allowJs を使用します。依存関係グラフの末端にあるモジュールから始め、モジュール単位でファイルを変換していきます。

検出

移行時の課題に注意してください。

// Can't migrate because:
- 1000+ JavaScript files
- Team still learning TypeScript
- Can't stop feature development
- Risk of breaking changes

allowJs を有効にする

// tsconfig.json
{
  "compilerOptions": {
    "allowJs": true,        // Allow JavaScript files
    "checkJs": false,       // Don't type check JS (optional)
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"]
}

移行戦略

Phase 1: Enable allowJs
  - Add tsconfig.json with allowJs: true
  - Rename one file to .ts as proof of concept
  - Ensure build still works

Phase 2: Convert leaf modules
  - Start with files that have no dependencies
  - Utilities, helpers, constants
  - Low risk, easy wins

Phase 3: Work up dependency graph
  - Convert files that only depend on converted files
  - Gradually move toward entry points

Phase 4: Convert entry points last
  - Main files, app entry points
  - Most complex, most dependencies

ファイルを変換する

// utils.js (before)
export function formatDate(date) {
  return date.toISOString().split('T')[0];
}

export const PI = 3.14159;

// utils.ts (after)
export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

export const PI = 3.14159;

JS と TS 間のインポート

// app.ts - TypeScript importing JavaScript
import { formatDate } from './utils.js';  // .js extension
// TypeScript trusts the JS (with checkJs: false)

// With types for JS module
declare module './utils.js' {
  export function formatDate(date: Date): string;
  export const PI: number;
}

// legacy.js - JavaScript importing TypeScript
import { User } from './types.ts';  // Works with allowJs
// JS doesn't get type checking, but can import TS

JavaScript に型を追加する

// @ts-check - Enable type checking for this file

/**
 * @param {string} name
 * @param {number} age
 * @returns {string}
 */
function greet(name, age) {
  return `Hello ${name}, you are ${age}`;
}

/** @type {string[]} */
const names = ['Alice', 'Bob'];

/** @typedef {{ x: number, y: number }} Point */

移行チェックリスト

// 1. Set up tsconfig.json with allowJs
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,  // Enable later for stricter checking
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  }
}

// 2. Start with simple files
// - No dependencies
// - Pure functions
// - Well-tested

// 3. Add types gradually
// - Start with any if needed
// - Refine over time

// 4. Enable strict mode checks incrementally
// - noImplicitAny
// - strictNullChecks
// - strictFunctionTypes

プレッシャーに負けないための手順

移行時には、次の点に従ってください。

1. 最初に allowJs を有効にする：まずインフラを整えます
2. 小さく始める：ファイルを 1 つ変換し、ビルドが動作することを確認します
3. 末端のモジュールを優先する：依存関係が少ないほど簡単です
4. 最初は any を使う：型は後から改善できます
5. 進捗を記録する：小さな成果を祝いましょう

危険信号

アンチパターン	問題	解決策
一気に書き換える	リスクが高すぎ、時間がかかります	allowJs を使って段階的に進めます
エントリーポイントから変換する	依存関係が多すぎます	末端から始めます
tsconfig.json がない	コンパイルを制御できません	適切に設定します
途中で放棄する	労力が無駄になります	進捗を記録し、成果を祝いましょう

よくある正当化

「すべてを一度に変換する必要があります」

実際には：allowJs を使った段階的な移行は、大規模なコードベースにおいて、より安全で実用的です。

「JS と TS が混在すると分かりにくくなります」

実際には：これは一時的な状態であり、管理可能です。明確な移行計画があれば、整理された状態を保てます。

「このまま JS を使い続ければよいのです」

実際には：TypeScript のメリットは、時間とともに積み重なります。小さく始め、徐々に拡大しましょう。

クイックリファレンス

手順	作業	期間
1	allowJs を指定して tsconfig を追加する	1 日目
2	ユーティリティファイルを 1～2 個変換する	1 週目
3	末端のモジュールを変換する	2～4 週目
4	依存関係グラフを上に向かって進める	1～3 か月目
5	エントリーポイントを変換する	3～6 か月目
6	allowJs を削除する（任意）	完了時

要点

TypeScript を段階的に導入するには allowJs を使います。末端のモジュールから始め、ファイルを徐々に変換していきます。これにより、開発を止めることなく、大規模な移行を管理しやすくなります。

参考資料

• Dan Vanderkam 著『Effective TypeScript』第 2 版
• 項目 81：allowJs を使用して TypeScript と JavaScript を混在させる