TypeScriptのインストール: npmでの導入とバージョン確認

TypeScriptは typescript という名前のnpmパッケージです。プロジェクトにインストールして、動くかを確認しましょう。

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

このパッケージは、TypeScriptのコンパイラーである tsc コマンドを提供します。インストールにはNode.jsとnpm（Node.jsに同梱）が必要です。Node.jsはnodejs.orgかシステムのパッケージマネージャーから入手し、node --version で確認してください。

TypeScriptを試すだけなら、何もインストールする必要はありません。このブロックはブラウザーの中でコンパイルして実行されます。

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

プロジェクトにTypeScriptをインストールする

推奨されるのは、プロジェクトの開発用依存としてローカルにインストールする方法です。

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript（短縮形は npm i -D typescript）は、コンパイラーを node_modules に入れ、package.json に記録します。

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

開発用依存なのは、コードのビルドにだけ必要で、実行には必要ないからです。プロジェクトをクローンして npm install を実行した人は、誰でも同じバージョンのコンパイラーを使えます。

ローカルのコンパイラーを実行するには、node_modules/.bin からコマンドを探す npx を前に付けます。

npx tsc --version

package.json の scripts の中では、npx なしで tsc と書けます。npmがスクリプトの PATH に node_modules/.bin を加えるからです。

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

これで npm run build でコンパイルし、npm run typecheck でファイルを書き出さずに型だけをチェックできます。

TypeScriptのバージョンを確認する

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

npx tsc --version と tsc --version が違うバージョンを表示する場合、プロジェクトには独自のコンパイラーがあり、グローバルのものはそれより古いか新しいということです。プロジェクトのビルドで意味を持つのは、プロジェクトのバージョンです。

TypeScriptをグローバルにインストールする

グローバルにインストールすると、npx なしでどのターミナルでも tsc コマンドが使えます。

npm install -g typescript
tsc --version

macOSやLinuxでNode.jsをシステム全体にインストールしている場合、EACCES の権限エラーで失敗することがあります。nvmやfnmのようなバージョンマネージャーでNode.jsをインストールすれば避けられます。sudo npm install -g はおすすめしません。

グローバルのコマンドはちょっとした実験に使いましょう。実際のプロジェクトでは、ローカルにもインストールしておきます。そうすれば package.json がバージョンを記録し、グローバルのコンパイラーを更新してもプロジェクトのビルドは変わりません。

pnpm、Yarn、Bunでインストールする

どのJavaScriptのパッケージマネージャーでも、同じパッケージをインストールします。

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

コンパイラーは pnpm tsc、yarn tsc、bunx tsc で実行します。

tsc --init で tsconfig.json を作る

tsconfig.json ファイルは、フォルダーがTypeScriptのプロジェクトであることを示し、コンパイラーのオプションを保持します。次のコマンドで生成します。

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

生成されるファイル（TypeScript 7）は strict といくつかの追加チェックをオンにし、"module": "nodenext" と "target": "esnext" を使い、rootDir と outDir の行はコメントアウトされています。コンパイラーが src から読み、dist に書き出すように、その2行のコメントを外します。

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

これは短くしたもので、実際のファイルにはもっと多くのオプションがそれぞれコメント付きで入っています。各オプションの意味はtsconfigのページで解説しています。同じフォルダーで npx tsc --init をもう一度実行すると error TS5054: A 'tsconfig.json' file is already defined で失敗するので、設定が上書きされることはありません。

最初のファイルをコンパイルする

src/index.ts を作ります。

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

そしてコンパイルして実行します。

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

引数なしの npx tsc は tsconfig.json を読み、対象のすべてのファイルを型チェックし、出力を dist に書き出します。生成された設定では、ファイルごとに index.js と、index.d.ts（型宣言）と .map ファイル（ソースマップ）ができます。

出力について知っておきたいことが2つあります。

• 標準では、型エラーがあっても出力は止まりません。 tsc はエラーを報告し、0以外の終了コードで終わりますが、JavaScriptは書き出します。エラーがある間は何も書き出さないようにするには、"noEmitOnError": true を設定します。
• tsconfig.json があるときは、ファイル名を渡さないでください。 npx tsc src/index.ts は error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline.（ファイルを指定すると tsconfig.json は読み込まれない）で失敗します。そのまま npx tsc を実行するか、本当に1ファイルを標準設定でコンパイルしたい場合は --ignoreConfig を加えます。

ウォッチモード

--watch（短縮形 -w）はコンパイラーを動かし続け、ファイルが変わるたびに再コンパイルします。

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

エディターの横のターミナルで開いたままにしておきましょう。止めるには Ctrl+C を押します。

特定のバージョンのTypeScriptをインストールする

@ のあとにバージョンを付けます。

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

TypeScript 6は、コンパイラーがJavaScriptで書かれた最後のバージョンです。コンパイラーのJavaScript APIを呼び出すツールの中にはまだそれを必要とするものがあり、その点とアップグレードの方法はTypeScript 7のページで解説しています。

エディターの設定

VS CodeにはTypeScriptのサポートが組み込まれています。.ts ファイルを開けば、何もインストールしなくてもエラーの波線、補完、ホバーでの型表示、名前の変更が使えます。エディターでもTypeScript 7の速さを得たいなら、TypeScriptチームが公開している専用の拡張機能で、VS CodeをネイティブのTypeScript 7言語サーバーに切り替えられます。WebStormなどのJetBrainsのIDEは最初からTypeScriptに対応しており、Neovim、Vim、Emacs、Zed、Sublime TextはLSPのサポートを通してTypeScriptの言語サーバーを使います。

よくあるインストールのエラー

This is not the tsc command you are looking for。 TypeScriptがインストールされていないフォルダーで npx tsc を実行したため、npx がたまたま tsc という名前の非推奨パッケージを取ってきました。npm install --save-dev typescript で本物をインストールしてください。

tsc: command not found、またはWindowsでの 'tsc' is not recognized as an internal or external command。 TypeScriptがグローバルにインストールされていないか、グローバルのnpmフォルダーが PATH に入っていません。ローカルにインストールしたプロジェクトで npx tsc を使うか、グローバルにインストールして新しいターミナルを開いてください。

error TS2591: Cannot find name 'process'（または require。__dirname では TS2304）。Node.js自身のAPIの型は別のパッケージにあります。npm install --save-dev @types/node でインストールし、compilerOptions に "types": ["node"] を加えます。TypeScript 7は、インストールされたすべての @types パッケージを自動では読み込まなくなりました。

error TS5011: The common source directory of 'tsconfig.json' is './src'。 ファイルが src にあり、outDir を設定したのに rootDir を設定していません。"rootDir": "./src" を加えます。

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'。 npm init -y は package.json に "type": "commonjs" を書き込むので、tsc --init の設定（verbatimModuleSyntax 付きの "module": "nodenext"）はすべての .ts ファイルをCommonJSとして扱い、そこでは import と export が使えません。"type": "module" に変え、相対インポートは .js の拡張子付きで書きます: import { add } from "./math.js"。