TypeScriptバージョン確認の決定版！tsc -vの罠とプロジェクト別・VSCodeでの確認法まで完全網羅

「TypeScriptを使って開発を始めたけれど、なぜかコンパイルエラーが消えない…」「チュートリアルと同じコードなのに動かない」そんな経験はありませんか？

もしかするとその原因、コードの書き間違いではなくTypeScriptの「バージョン」にあるかもしれません。

TypeScriptは進化のスピードが非常に速く、プロジェクトによって使われているバージョンがバラバラなことも珍しくありません。「自分のPCに入っているバージョン」と「プロジェクトで指定されているバージョン」がズレていると、思わぬ不具合や型エラーに悩まされることになります。

しかし、いざ確認しようと思っても「tsc -vでいいんだっけ？」「package.jsonの数字と違う気がする…」と、正しい確認方法に迷ってしまう方も多いはず。

そこで本記事では、初心者から現場のエンジニアまで、二度とバージョン確認で迷わないための知識を網羅的に解説します。

この記事を読めば、環境依存のトラブルをサクッと解決し、本来の目的である「コーディング」に集中できるようになります。それでは、まずは一番基本の確認コマンドから見ていきましょう！

格安ドメイン取得サービス─ムームードメイン─

TypeScriptのバージョンを今すぐ確認する基本方法

TypeScriptのバージョンを確認する最も基本的なコマンドは tsc -v または tsc --version です。ただし、このコマンドが示すバージョンは「グローバルにインストールされたTypeScript」である点に注意が必要です。プロジェクトで実際に使われているバージョンとは異なる可能性があります。

tsc -v / npx tsc -v で分かるバージョンの違い

TypeScriptのバージョン確認には2つの主要な方法があり、それぞれ異なるバージョンを表示します。

グローバルインストール版を確認: tsc -v

tsc -v
# または
tsc --version

このコマンドは、システム全体（グローバル）にインストールされているTypeScriptのバージョンを表示します。出力例:

Version 5.3.3

重要な注意点: このバージョンは、プロジェクトで実際に使用されているTypeScriptとは別物です。グローバル版がインストールされていない場合、command not found: tsc というエラーが表示されます。

プロジェクトローカル版を確認: npx tsc -v

npx tsc -v

npx を使うことで、プロジェクトの node_modules 内にインストールされているTypeScriptのバージョンを確認できます。これが実際のビルドやコンパイルで使われるバージョンです。

出力例:

Version 5.4.5

両者の違いを実例で理解する

# グローバル版
$ tsc -v
Version 4.9.5

# プロジェクトローカル版
$ npx tsc -v
Version 5.4.5

この例では、グローバルに古い4.9.5がインストールされている一方で、プロジェクトでは最新の5.4.5を使用しています。実際のビルドではnpxで実行されるため、5.4.5が使われます。

グローバルとローカルのTypeScriptバージョンを見分ける方法

バージョンの不一致によるトラブルを避けるために、どちらのTypeScriptが実行されているかを正確に把握する必要があります。

which/where コマンドで実行パスを確認する

macOS/Linux の場合:

which tsc

出力例:

/usr/local/bin/tsc          # グローバルインストール
/Users/username/.nvm/versions/node/v18.0.0/bin/tsc  # nvmを使っている場合

Windows (PowerShell) の場合:

where.exe tsc

node_modules内のローカル版を確認する

プロジェクトのローカル版TypeScriptは、以下のパスに存在します:

# パスを確認
ls node_modules/.bin/tsc

# またはパッケージ情報を確認
cat node_modules/typescript/package.json | grep version

意図しないバージョンが呼ばれる原因

以下のようなケースで、想定外のバージョンが実行されることがあります:

1. PATHの優先順位: グローバル版のパスが先に解決される
2. エディタの設定: VSCodeなどがグローバル版を参照している
3. npm scriptsとターミナルの差異: package.json の scripts 内では自動的にローカル版が使われるが、ターミナルで直接 tsc を実行するとグローバル版が使われる

{
  "scripts": {
    "build": "tsc"  // これはローカル版を使う
  }
}

npm run build  // ローカル版 (5.4.5) を使用
tsc            // グローバル版 (4.9.5) を使用 ← 意図しない動作!

ベストプラクティス: 常に npx tsc または npm run build を使用することで、意図しないバージョンの実行を防げます。

TypeScriptがインストールされているかを確認する最短手順

TypeScriptがまだインストールされていない場合や、インストール状況を素早く確認したい場合の手順です。

最速の確認コマンド

npx tsc -v

このコマンド一つで以下を判定できます:

ケース1: ローカルにインストール済み

Version 5.4.5

ケース2: ローカル未インストール、グローバルのみ

Need to install the following packages:
  typescript
Ok to proceed? (y)

この表示が出た場合、プロジェクトローカルにはTypeScriptがインストールされていません。

ケース3: 完全に未インストール

tsc -v
# command not found: tsc (macOS/Linux)
# 'tsc' は、内部コマンドまたは外部コマンド... (Windows)

package.jsonで依存関係を確認する

プロジェクトにTypeScriptが含まれているかを確認:

cat package.json | grep typescript

または:

npm list typescript --depth=0

出力例:

project@1.0.0 /path/to/project
└── typescript@5.4.5

(empty) や -- typescript@UNMET DEPENDENCY と表示された場合は、インストールされていません。

すぐにインストールするには

開発依存関係としてインストール（推奨）:

npm install --save-dev typescript
# または
yarn add --dev typescript

特定のバージョンを指定する場合:

npm install --save-dev typescript@5.4.5

インストール後、再度 npx tsc -v でバージョンを確認し、プロジェクトに正しくインストールされたことを確認してください。

プロジェクト管理ツール（npm/yarn）でのバージョン確認と見方

プロジェクトで実際に使われているTypeScriptのバージョンを正確に把握するには、package.json だけでなく、lockファイルや依存関係ツリーを確認する必要があります。このセクションでは、npm/yarnを使った詳細なバージョン確認方法を解説します。

package.jsonとlockファイル（npm/yarn）から正確なバージョンを読み取る

package.json に記載されているバージョンは範囲指定である場合が多く、実際にインストールされているバージョンとは異なることがあります。正確なバージョンを知るには、lockファイルを確認する必要があります。

package.jsonでの記述例

{
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

この ^5.4.0 という記述は「5.4.0以上、6.0.0未満」を意味します。つまり、実際には5.4.5や5.4.9がインストールされている可能性があります。

package-lock.json（npm）で実際のバージョンを確認する

確認コマンド:

cat package-lock.json | grep -A 3 '"typescript"'

または、JSONを直接開いて確認:

{
  "packages": {
    "node_modules/typescript": {
      "version": "5.4.5",
      "resolved": "<https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz>",
      "integrity": "sha512-...",
      "dev": true
    }
  }
}

この "version": "5.4.5" が実際にインストールされている正確なバージョンです。

yarn.lock（Yarn）で実際のバージョンを確認する

確認コマンド:

cat yarn.lock | grep -A 3 'typescript@'

yarn.lockの記述例:

typescript@^5.4.0:
  version "5.4.5"
  resolved "<https://registry.yarnpkg.com/typescript/-/typescript-5.4.5.tgz#>..."
  integrity sha512-...

ここでも version "5.4.5" が実際のバージョンです。

なぜlockファイルを見るべきか

lockファイルを確認すべき理由は以下の3点です:

1. 再現性の保証: 他の開発者やCI環境で全く同じバージョンがインストールされることを保証
2. バージョン範囲の解決結果: ^5.4.0 のような範囲指定が、どのバージョンに解決されたかを記録
3. 依存関係の依存関係: 他のパッケージが内部的に使っているTypeScriptのバージョンも記録

重要: lockファイルは必ずGitにコミットしてください。これにより、チーム全体で同じバージョンが保証されます。

「npm list typescript」で依存関係を含めたバージョン詳細を表示する

package.json の記述と実際にインストールされているバージョンの違いを確認するには、npm list コマンドが便利です。

基本的な使い方

npm list typescript

出力例:

project@1.0.0 /Users/username/project
└── typescript@5.4.5

この出力から、プロジェクトに5.4.5がインストールされていることが分かります。

深い依存関係まで表示する

npm list typescript --depth=10

出力例:

project@1.0.0 /Users/username/project
├── typescript@5.4.5
├─┬ @typescript-eslint/parser@6.0.0
│ └── typescript@5.4.5 deduped
└─┬ ts-node@10.9.0
  └── typescript@5.4.5 deduped

この出力から以下が分かります:

• プロジェクト直接の依存: typescript@5.4.5
• @typescript-eslint/parser も同じバージョンを参照（deduped = 重複排除済み）
• ts-node も同じバージョンを参照

package.jsonとの違いを理解する

package.jsonの記述:

{
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

実際にインストールされているバージョン（npm list）:

└── typescript@5.4.5

この違いが生じる理由:

1. 範囲指定の解決: ^5.4.0 は5.4.x系の最新版（この場合5.4.5）をインストールする
2. インストール時期の違い: 同じ ^5.4.0 でも、インストールした時期によって5.4.2、5.4.5など異なるバージョンになる
3. lockファイルの固定: 一度インストールされると、lockファイルが特定バージョンを固定する

Yarnでの確認方法

Home page | Yarn

Yarn, the modern JavaScript package manager

yarnpkg.com

yarn list --pattern typescript

または:

yarn why typescript

yarn why は依存関係の理由まで表示してくれます:

=> Found "typescript@5.4.5"
info Reasons this module exists
   - "workspace-root" depends on it
   - Hoisted from "@typescript-eslint#parser#typescript"

チルダ（~）やキャレット（^）などセマンティックバージョニングの正しい意味

TypeScriptのバージョン管理で最も混乱しやすいのが、セマンティックバージョニング（SemVer）の記号です。これらを正しく理解することで、意図しないバージョンアップによるトラブルを防げます。

セマンティックバージョニングの基本構造

TypeScriptのバージョンは メジャー.マイナー.パッチ の形式です:

5.4.5
│ │ │
│ │ └─ パッチ（バグ修正）
│ └─── マイナー（新機能追加、後方互換性あり）
└───── メジャー（破壊的変更）

キャレット（^）: マイナーバージョンまで許可

{
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

許可される範囲: >=5.4.0 <6.0.0

使用場面: 最も一般的な指定方法。新機能やバグ修正を受け入れつつ、破壊的変更は避けたい場合。

チルダ（~）: パッチバージョンのみ許可

{
  "devDependencies": {
    "typescript": "~5.4.0"
  }
}

許可される範囲: >=5.4.0 <5.5.0

使用場面: より保守的な運用。バグ修正のみを受け入れ、新機能による予期しない動作変更を避けたい場合。

完全固定: 記号なし

{
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

許可される範囲: 5.4.5 のみ

使用場面: 本番環境で完全な再現性が必要な場合。ただし、セキュリティパッチも自動適用されないため、定期的な手動更新が必要。

比較表: 各記号の違い

記述	5.4.0 → 5.4.5	5.4.0 → 5.5.0	5.4.0 → 6.0.0	用途
^5.4.0	✅	✅	❌	一般的な開発（推奨）
~5.4.0	✅	❌	❌	保守的な運用
5.4.0	❌	❌	❌	完全固定（本番環境）
* または latest	✅	✅	✅	非推奨（予測不可能）

エンジニアがミスしやすいポイント

ポイント1: ^ と ~ を逆に理解している

// ❌ 間違った理解
{
  "typescript": "~5.4.0"  // 「これで最新版が使えるはず」→ 5.4.x までしか使えない
}

// ✅ 正しい理解
{
  "typescript": "^5.4.0"  // マイナーバージョンまでアップデート可能
}

ポイント2: lockファイルがあれば記号は関係ないと思い込む

lockファイルがあっても、npm update や yarn upgrade を実行すると範囲内で最新版に更新されます:

# package.json: "typescript": "^5.4.0"
# 現在のバージョン: 5.4.2

npm update typescript
# → 5.4.5 にアップデート（^の範囲内）

ポイント3: 依存パッケージのバージョン範囲を見落とす

他のパッケージが特定のTypeScriptバージョンを要求している場合、競合が発生することがあります:

{
  "devDependencies": {
    "typescript": "^5.4.0",
    "some-tool": "^2.0.0"  // 内部で "typescript": "^5.3.0" を要求
  }
}

この場合、両方を満たす5.4.xがインストールされますが、意図したバージョンと異なる可能性があります。

推奨される運用方法

開発中のプロジェクト:

{
  "devDependencies": {
    "typescript": "^5.4.0"  // 新機能とバグ修正を受け入れる
  }
}

本番環境・重要プロジェクト:

{
  "devDependencies": {
    "typescript": "5.4.5"  // 完全固定で予期しない変更を防ぐ
  }
}

そして必ず、package-lock.jsonまたはyarn.lockをバージョン管理システムにコミットすることで、チーム全体で同じバージョンを保証できます。

専門的な知識不要！誰でも簡単に使える『XWRITE(エックスライト)』

TypeScriptバージョン差によるエラーの切り分け方

TypeScriptのバージョン差異は、型エラーやビルド失敗の原因として見落とされがちです。このセクションでは、エラーがバージョンに起因するかを判断し、適切に対処する方法を解説します。

型エラー・ビルドエラーが「バージョン差」かどうか判断するポイント

すべてのTypeScriptエラーがバージョン差によるものではありませんが、以下のような症状が出た場合はバージョンを疑うべきです。

バージョン差が原因である可能性が高い症状

症状1: 新しい構文が認識されない

// satisfies演算子はTypeScript 4.9以降で使用可能
const config = {
  url: "<https://example.com>",
  method: "GET"
} satisfies Config;

エラーメッセージ（TypeScript 4.8以前）:

error TS1005: ',' expected.

このエラーが出た場合、使用しているTypeScriptが4.9未満である可能性が高いです。

確認方法:

npx tsc -v
# Version 4.8.4 ← 4.9未満なのでsatisfiesが使えない

症状2: 型定義ファイルの互換性エラー

import { useState } from 'react';

エラーメッセージ:

node_modules/@types/react/index.d.ts:3000:14 - error TS2304: Cannot find name 'ReadonlyArray'.

このエラーは、@types/react が要求するTypeScriptバージョンより古いバージョンを使っている場合に発生します。

package.jsonで確認:

{
  "devDependencies": {
    "@types/react": "^18.2.0"  // TypeScript 4.7以降が必要
  }
}

症状3: 突然動作していたコードがエラーになる

チームメンバーがpushしたコードが、自分の環境ではエラーになるケース:

// TypeScript 5.0以降で追加されたconst type parameters
function createArray<const T>(items: T[]): T[] {
  return items;
}

エラーメッセージ（TypeScript 4.9以前）:

error TS1005: '>' expected.

これは、コードを書いた人がTypeScript 5.0以降を使っているのに、あなたの環境が古いバージョンのままである状態です。

バージョン差でないことが確実な症状

以下のようなエラーは、バージョンではなくコードの問題です:

const user: User = {
  name: "Alice"
  // ageプロパティが不足
};

エラーメッセージ:

error TS2741: Property 'age' is missing in type '{ name: string; }' but required in type 'User'.

このような「プロパティ不足」「型の不一致」などは、どのバージョンでも発生する通常の型エラーです。

バージョン差を判断する決定的な方法

手順1: 公式リリースノートで構文・機能を確認

エラーが出ている構文や機能が、いつ導入されたかを確認:

• TypeScript公式リリースノート: https://www.typescriptlang.org/docs/handbook/release-notes/overview.html

手順2: 他の環境で動作確認

# TypeScript PlaygroundでTypeScriptバージョンを切り替えて試す
# <https://www.typescriptlang.org/play>

TypeScript Playgroundでは、バージョンを4.0～最新まで切り替えられるため、どのバージョンからその構文が使えるかを即座に確認できます。

手順3: バージョンを一時的に上げて検証

# 現在のバージョンを確認
npx tsc -v

# 最新版を試す（node_modules内のみ、グローバルには影響しない）
npm install --save-dev typescript@latest

# ビルドを実行
npx tsc

# 問題が解決すれば、バージョン差が原因

グローバルとローカルのバージョンがズレている時の典型的な症状

開発環境で最も頻発するトラブルの一つが、グローバルとローカルのTypeScriptバージョンの不一致です。

症状1: エディタとターミナルでエラー表示が異なる

VSCodeでは問題なし:

const data = { id: 1 } satisfies Data;
// エディタ上でエラー表示なし

ターミナルでビルドするとエラー:

$ tsc
error TS1005: ',' expected.

原因: VSCodeがプロジェクトローカルのTypeScript 5.0を使用している一方、ターミナルで実行した tsc コマンドがグローバルのTypeScript 4.8を参照している。

確認方法:

# VSCodeが使っているバージョン
# VSCodeのステータスバー右下に表示される「TypeScript 5.0.4」をクリック
# または、コマンドパレット（Cmd+Shift+P）で "TypeScript: Select TypeScript Version" を実行

# ターミナルが使っているバージョン
which tsc
# /usr/local/bin/tsc ← グローバル版

npx tsc -v
# Version 5.0.4 ← プロジェクトローカル版

解決方法:

# グローバル版を使わず、必ずnpxを使う
npx tsc

# またはpackage.jsonのscriptsに記述
# scripts内では自動的にローカル版が優先される

{
  "scripts": {
    "build": "tsc"
  }
}

npm run build  # 必ずローカル版が使われる

症状2: パスの優先順位による意図しないバージョンの実行

PATHの設定例（macOS/Linux）:

echo $PATH
# /usr/local/bin:/Users/username/.nvm/versions/node/v18.0.0/bin:...

グローバルにインストールされたTypeScriptが /usr/local/bin/tsc にある場合、ターミナルで tsc を実行すると必ずこちらが優先されます。

検証コマンド:

# 実際にどのtscが実行されるか確認
type tsc
# tsc is /usr/local/bin/tsc

# プロジェクトローカルのtscのパス
ls -la node_modules/.bin/tsc
# node_modules/.bin/tsc -> ../typescript/bin/tsc

解決策: グローバル版をアンインストール

# npmでグローバルインストールしている場合
npm uninstall -g typescript

# yarnでグローバルインストールしている場合
yarn global remove typescript

グローバル版を削除しても、プロジェクトごとにローカルインストールされていれば npx tsc で問題なく動作します。

症状3: CI環境とローカル環境でビルド結果が異なる

ローカルでは成功:

$ npm run build
✓ Build successful

CI（GitHub Actions等）では失敗:

# .github/workflows/ci.yml
- name: Build
  run: npm run build
  # Error: Type error in src/app.ts

原因分析:

# ローカル環境
$ npx tsc -v
Version 5.4.5

# CIのログを確認
Run npm run build
  TypeScript version: 5.3.2  ← ローカルと異なる

原因: package.jsonに "typescript": "^5.3.0" と記述されており、ローカルでは5.4.5がインストールされているが、CIでは5.3.2がインストールされた。lockファイルがコミットされていない、または無視されている可能性がある。

解決方法:

# package-lock.jsonまたはyarn.lockが存在することを確認
ls -la package-lock.json

# .gitignoreでlockファイルが除外されていないか確認
cat .gitignore | grep lock

# lockファイルをコミット
git add package-lock.json
git commit -m "Fix: Add package-lock.json to ensure consistent TypeScript version"

CI / Docker / リモート環境で使われているTypeScriptの確認方法

ローカル以外の環境でのバージョン確認は、ログや環境変数から間接的に確認する必要があります。

GitHub Actionsでの確認方法

方法1: ビルドログから確認

GitHub Actionsのワークフロー実行ログに、TypeScriptのバージョンが表示されることがあります:

# .github/workflows/ci.yml
name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      # バージョンを明示的に出力
      - name: Check TypeScript version
        run: npx tsc -v

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

ログ出力:

Run npx tsc -v
Version 5.4.5

方法2: package-lock.jsonから確認

CIで npm ci を使用している場合、package-lock.jsonに記録されたバージョンが必ずインストールされます:

# ローカルで確認
cat package-lock.json | grep -A 2 '"node_modules/typescript"'

Dockerコンテナでの確認方法

Dockerfileでバージョンを固定:

FROM node:18-alpine

WORKDIR /app

# package.jsonとlockファイルをコピー
COPY package*.json ./

# npm ciで確実にlockファイルのバージョンをインストール
RUN npm ci

# ソースコードをコピー
COPY . .

# ビルド時にバージョンを出力
RUN npx tsc -v && npm run build

CMD ["node", "dist/index.js"]

ビルドログで確認:

docker build -t myapp .
# ...
# Version 5.4.5
# Build successful

実行中のコンテナ内で確認:

# コンテナに入る
docker exec -it myapp-container sh

# バージョン確認
npx tsc -v
# Version 5.4.5

リモート環境（本番サーバー等）での確認

SSH接続して確認:

ssh user@production-server

cd /var/www/myapp

# プロジェクトのTypeScriptバージョン
npx tsc -v

# または、package-lock.jsonから
cat package-lock.json | grep '"typescript"' -A 3

環境変数やビルドスクリプトでの確認

環境ごとのバージョンを記録:

{
  "scripts": {
    "build": "echo \\"Building with TypeScript $(npx tsc -v)\\" && tsc",
    "build:prod": "npm ci && npm run build"
  }
}

実行時:

npm run build
# Building with TypeScript Version 5.4.5

トラブルシューティング: CI環境でのバージョン固定

問題: CIで毎回異なるバージョンがインストールされる

解決策1: npm ciを使う（npmの場合）

# ❌ 間違い
- run: npm install

# ✅ 正しい
- run: npm ci

npm ci は package-lock.json を厳密に遵守し、常に同じバージョンをインストールします。

解決策2: Yarnのfrozen-lockfileオプション（Yarnの場合）

# ✅ lockファイルを厳密に遵守
- run: yarn install --frozen-lockfile

解決策3: package.jsonでバージョンを完全固定

{
  "devDependencies": {
    "typescript": "5.4.5"  // ^や~を使わず完全固定
  }
}

これにより、どの環境でも必ず5.4.5がインストールされます。ただし、セキュリティパッチも自動適用されないため、定期的な手動更新が必要です。

新世代レンタルサーバー『シンレンタルサーバー』

チーム・CI環境でTypeScriptバージョンを揃える運用方法

チーム開発において「ローカルでは動くのにCIで失敗する」「メンバーによってビルド結果が異なる」といった問題は、TypeScriptバージョンの不統一が原因であることが多いです。このセクションでは、組織全体でバージョンを確実に揃えるための実践的な運用方法を解説します。

グローバルとローカルのバージョン差異をなくすベストプラクティス

プロジェクトごとにローカルインストールを徹底することが、バージョン差異による問題を防ぐ最も確実な方法です。

原則: グローバルインストールを使わない

推奨されない運用:

# ❌ グローバルにTypeScriptをインストール
npm install -g typescript

# ❌ グローバル版をそのまま使用
tsc src/index.ts

この運用では以下の問題が発生します:

• プロジェクトAではTypeScript 5.4が必要だが、グローバルは4.9のまま
• 開発者Aのグローバルは5.3、開発者Bは5.4という不整合
• CIにはグローバルインストールされていないためビルド失敗

推奨される運用:

# ✅ プロジェクトごとにローカルインストール
npm install --save-dev typescript

# ✅ npxまたはnpm scriptsで実行
npx tsc src/index.ts

# またはpackage.jsonに記述

{
  "scripts": {
    "build": "tsc",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

npm run build  # 必ずローカル版が使われる

グローバルインストールが残っている場合の対処

確認方法:

# グローバルにインストールされているTypeScriptを確認
npm list -g typescript

# 出力例
/usr/local/lib
└── typescript@4.9.5

アンインストール:

# npmの場合
npm uninstall -g typescript

# yarnの場合
yarn global remove typescript

# 確認
npm list -g typescript
# (empty)

重要: グローバル版をアンインストールしても、各プロジェクトのnode_modules内にローカルインストールされていれば、npx tsc や npm run build で問題なく動作します。

VSCodeでプロジェクトローカル版を使用する設定

VSCodeがグローバル版ではなくプロジェクトローカル版のTypeScriptを使うように設定します。

手順1: ワークスペース設定を開く

.vscode/settings.json を作成:

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

手順2: VSCodeでTypeScriptバージョンを選択

1. TypeScriptファイルを開く
2. ステータスバー右下の「TypeScript 5.x.x」をクリック
3. 「ワークスペースバージョンの使用」を選択

これにより、VSCodeがプロジェクトの node_modules/typescript を使用するようになります。

確認方法:

ステータスバーに表示されるバージョンが、プロジェクトの package.json と一致していることを確認:

# プロジェクトのバージョン
cat package.json | grep typescript
# "typescript": "5.4.5"

# VSCodeのステータスバー
# TypeScript 5.4.5 ← 一致していればOK

package.jsonでのバージョン固定方法

開発環境とCI環境で同じバージョンを保証するため、バージョンを明示的に固定します。

完全固定（推奨）:

{
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

この記述により、どの環境でも必ず5.4.5がインストールされます。

範囲指定の場合:

{
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

この場合、package-lock.json または yarn.lock を必ずコミットすることで、全員が同じバージョン（例: 5.4.5）を使用できます。

lockファイルの徹底管理

package-lock.json（npm）または yarn.lock の役割:

• 依存関係の具体的なバージョンを記録
• チームメンバー全員が同じバージョンをインストールすることを保証
• CI環境でも同じバージョンが使われることを保証

必ずGitにコミット:

# .gitignoreにlockファイルが含まれていないか確認
cat .gitignore | grep lock

# もし含まれている場合は削除
# package-lock.json ← この行を削除

# lockファイルをコミット
git add package-lock.json
git commit -m "Add package-lock.json for consistent dependency versions"

lockファイルを無視してはいけない理由:

// package.json
{
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

この設定で、開発者Aが2024年3月にインストールすると5.4.2が、開発者Bが2024年5月にインストールすると5.4.5が入る可能性があります。lockファイルがあれば、全員が同じバージョンを使用できます。

複数人・複数プロジェクトでTypeScriptバージョンを統一する考え方

組織全体で複数のプロジェクトを管理している場合、Node.jsやTypeScriptのバージョン管理ツールを活用することで、環境構築を標準化できます。

Node.jsバージョン管理ツールの活用

TypeScriptはNode.jsに依存するため、Node.jsバージョンも統一することが重要です。

Volta（推奨）

Voltaは、プロジェクトごとにNode.jsとパッケージマネージャーのバージョンを自動切り替えできるツールです。

インストール:

# macOS/Linux
curl <https://get.volta.sh> | bash

# Windows
# <https://docs.volta.sh/guide/getting-started> からインストーラーをダウンロード

プロジェクトへの設定:

# プロジェクトディレクトリで実行
volta pin node@18.19.0
volta pin npm@10.2.0

これにより、package.jsonに以下が追加されます:

{
  "volta": {
    "node": "18.19.0",
    "npm": "10.2.0"
  }
}

利点:

• プロジェクトに入ると自動的に指定バージョンに切り替わる
• チームメンバーが同じVoltaをインストールしていれば、誰でも同じ環境になる
• グローバルインストールの概念がなくなり、バージョン衝突が起きない

TypeScriptと組み合わせた運用:

cd my-project
volta pin node@18.19.0

npm install --save-dev typescript@5.4.5

これで、プロジェクトに入った瞬間にNode.js 18.19.0が使われ、そのプロジェクトのTypeScript 5.4.5が確実に動作します。

asdf

asdfは、複数の言語・ツールのバージョンを統一管理できるツールです。

インストール:

# macOS（Homebrew）
brew install asdf

# プラグインの追加
asdf plugin add nodejs
asdf plugin add yarn

プロジェクトへの設定:

cd my-project

# .tool-versionsファイルを作成
echo "nodejs 18.19.0" >> .tool-versions
echo "yarn 1.22.19" >> .tool-versions

.tool-versionsの例:

nodejs 18.19.0
yarn 1.22.19

このファイルをGitにコミットすることで、チーム全員が同じNode.jsとYarnのバージョンを使用できます。

TypeScriptとの併用:

# asdfでNode.jsバージョンを切り替え
asdf install

# プロジェクトローカルにTypeScriptをインストール
npm install --save-dev typescript@5.4.5

nvm（参考）

nvmは広く使われていますが、自動切り替え機能が限定的です。

.nvmrcファイル:

18.19.0

使用方法:

# プロジェクトディレクトリで毎回実行が必要
nvm use

Voltaやasdfと比べて自動化が弱いため、チーム運用ではVoltaまたはasdfを推奨します。

package.jsonのenginesフィールドで要件を明記

Node.jsやnpmのバージョン要件をpackage.jsonに記載することで、不適切なバージョンでのインストールを防げます。

{
  "name": "my-project",
  "version": "1.0.0",
  "engines": {
    "node": ">=18.0.0 <19.0.0",
    "npm": ">=9.0.0"
  },
  "devDependencies": {
    "typescript": "5.4.5"
  }
}

.npmrcで厳格モードを有効化:

プロジェクトルートに .npmrc を作成:

engine-strict=true

これにより、指定バージョン外のNode.jsでは npm install が失敗します:

npm install
# npm ERR! engine Unsupported engine
# npm ERR! engine Not compatible with your version of node/npm

CI環境での統一方法

GitHub Actionsの例:

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      # Node.jsバージョンを固定
      - uses: actions/setup-node@v3
        with:
          node-version: '18.19.0'
          cache: 'npm'

      # lockファイルを厳密に遵守
      - name: Install dependencies
        run: npm ci

      # TypeScriptバージョンを確認
      - name: Check TypeScript version
        run: npx tsc -v

      # ビルド実行
      - name: Build
        run: npm run build

      # 型チェック
      - name: Type check
        run: npm run type-check

GitLab CIの例:

image: node:18.19.0-alpine

stages:
  - build
  - test

before_script:
  - npm ci
  - npx tsc -v

build:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

test:
  stage: test
  script:
    - npm run type-check

複数プロジェクト間でのバージョン統一戦略

組織で複数のプロジェクトを管理している場合、以下の戦略が有効です。

戦略1: 四半期ごとの統一アップデート

// 全プロジェクトで同じバージョンに統一
{
  "devDependencies": {
    "typescript": "5.4.5"  // 2024 Q2の標準バージョン
  }
}

戦略2: メジャーバージョンのみ統一

// マイナー・パッチは各プロジェクトの裁量
{
  "devDependencies": {
    "typescript": "^5.4.0"  // 5.x系で統一
  }
}

戦略3: 共有設定パッケージの活用

組織共通の設定を npm パッケージとして管理:

# 社内npmレジストリまたはGitリポジトリで管理
npm install --save-dev @company/typescript-config

// @company/typescript-config/package.json
{
  "peerDependencies": {
    "typescript": "5.4.5"
  }
}

各プロジェクトでこのパッケージを使うことで、TypeScriptバージョンが自動的に統一されます。

ドキュメントとオンボーディング

新メンバーがスムーズに環境構築できるよう、READMEに明記します。

README.mdの例:

## 開発環境のセットアップ

### 必要なツール

- Node.js 18.19.0（Voltaを推奨）
- npm 10.2.0以上

### 初回セットアップ

1. Voltaのインストール

```bash
curl https://get.volta.sh | bash
```
1. リポジトリのクローンとセットアップ

```bash
git clone <https://github.com/company/project.git>
cd project
npm install
```
2. TypeScriptバージョンの確認

```bash
npx tsc -v
# Version 5.4.5 と表示されればOK
```

### ビルド
npm run build

### トラブルシューティング
- エディタで型エラーが出る場合
    - VSCodeのステータスバー右下で「ワークスペースバージョンの使用」を選択

このようなドキュメントにより、チーム全員が同じ環境で開発できます。

よくある質問（FAQ）

コストパフォーマンスに優れた高性能なレンタルサーバー

【Hostinger】

まとめ

今回の記事では、TypeScriptのバージョン確認方法から、開発現場で混乱を招きやすいグローバル・ローカルの使い分けまでを詳しく解説しました。

「たかがバージョン確認」と思われがちですが、ここを疎かにすると、チームメンバー間での型エラーの食い違いや、本番環境（CI/CD）だけでビルドが落ちるといった、エンジニアにとって最も避けたい「無駄な工数」を発生させる原因になります。

記事の内容を振り返り、特に明日からの開発で意識していただきたい「重要ポイント」をまとめました。

TypeScriptは進化が非常に早く、新しいバージョンで追加される便利な機能を活用するためにも、正しく環境を把握しておくことは重要です。

もし今、原因不明のビルドエラーに悩んでいるのなら、まずは今回ご紹介したコマンドを使って「自分の期待しているバージョンが本当に動いているか」を真っ先に疑ってみてください。それだけで、数時間のデバッグ作業が数分で解決することも珍しくありません。

この記事が、あなたの開発環境をよりクリーンで、ストレスのないものにする一助となれば幸いです。

【不要なパソコンを送るだけ】パソコン無料処分サービス『送壊ゼロ』