先生と生徒の会話形式で理解しよう

生徒

「TypeScriptで外部の便利なライブラリを使おうとしたら、エラーが出てしまいました。JavaScriptのライブラリはそのまま使えないんですか？」

先生

「それは『型』の情報が足りないからかもしれませんね。TypeScriptでは、JavaScriptで作られた道具を使うために『型定義ファイル』という説明書が必要なんです。」

生徒

「説明書ですか？どうやって手に入れればいいんでしょうか？」

先生

「そこで登場するのが『@types』という仕組みです。今回はその読み込み方や設定方法を詳しく解説しますね！」

1. 外部モジュールの型（@types）とは？

TypeScriptを学習していると、「ライブラリ」や「パッケージ」といった言葉を耳にするようになります。これらは、世界中の頭の良いプログラマーたちが作ってくれた「便利な道具箱」のようなものです。例えば、日付の計算を楽にする道具や、複雑な計算を自動でやってくれる道具など、たくさん存在します。

しかし、ここで一つ問題があります。世の中にある多くの道具箱は、もともと「JavaScript（ジャバスクリプト）」という言語で作られています。TypeScriptはJavaScriptに「型（データの種類というルール）」を追加した言語なので、JavaScriptで作られた道具をそのまま持ってきても、「この道具はどうやって使えばいいの？」「どんなデータを入れて、どんな結果が返ってくるの？」という詳細がわからず、エラーを出してしまいます。

そこで必要になるのが、「型定義ファイル（かたていぎふぁいる）」です。これは、JavaScriptの道具に対する「取扱説明書」のような役割を果たします。この説明書があるおかげで、TypeScriptは外部の道具を正しく理解し、私たちがコードを書くときに「使い方が間違っていますよ！」と教えてくれるようになるのです。そして、この説明書をまとめて管理している場所が、「DefinitelyTyped（デフィニトリー・タイプド）」というプロジェクトであり、そこから提供されるパッケージの名前が「@types（アット・タイプス）」から始まるものなのです。

2. パッケージ管理ツール「npm」の準備

外部の型を読み込む前に、パソコンで「道具」をダウンロードするための準備が必要です。プログラミングの世界では、「npm（エヌピーエム）」というツールを使って、世界中のプログラムを自分のパソコンに取り込みます。

「npm」は、例えるなら「スマートフォンのアプリストア」のようなものです。欲しいアプリ（プログラム）の名前を指定するだけで、自動的にダウンロードして使える状態にしてくれます。まずは、プロジェクトのフォルダ内で以下のコマンドを実行して、設定ファイルを作成しましょう。


npm init -y

これによって、「package.json（パッケージ・ジェイソン）」という名前のファイルが作られます。これは、このプロジェクトで「どんな道具（ライブラリ）を使っているか」を記録するための「持ち物リスト」です。

3. @typesを使って型をインストールする手順

では、具体的に「@types」をインストールする方法を見ていきましょう。例えば、日付を扱うのに非常に有名な「lodash（ローダッシュ）」というライブラリを使いたいとします。

まず、本体のライブラリをインストールします。


npm install lodash

この状態だけでは、TypeScriptは「lodashの中身がどうなっているか」を知りません。そこで、型定義ファイル（説明書）をインストールします。型定義ファイルの名前は、必ず「@types/ライブラリ名」というルールになっています。


npm install --save-dev @types/lodash

ここで使っている --save-dev という命令は、「これはプログラムを動かすときに使う道具ではなく、プログラムを作るとき（開発するとき）にだけ使う説明書です」という意味です。型定義ファイルは、私たちがコードを書くときのアドバイスとして必要なので、このように区別してインストールするのが一般的です。

インストールが完了すると、node_modules というフォルダの中に @types というフォルダができあがり、その中に説明書が格納されます。これで準備完了です！

4. インストールした型をコードで使ってみよう

説明書（型定義ファイル）をインストールすると、Visual Studio Code などのエディタが驚くほど賢くなります。実際にコードを書いてみましょう。以下の例は、lodashを使って配列を逆順にする処理です。


import * as _ from "lodash";

let numbers: number[] = [1, 2, 3, 4, 5];
let reversedNumbers = _.reverse(numbers);

console.log(reversedNumbers);

型定義ファイルを読み込んでいると、_. と入力した瞬間に、利用できる機能のリストがズラッと表示されます。これを「入力補完（にゅうりょくほかん）」と呼びます。また、マウスを関数の上に乗せると、「この関数は数字の配列を受け取ります」といった説明がポップアップで表示されます。これが、@typesを導入する最大のメリットです。

5. 自動で型を読み込む仕組み「Type Roots」

「なぜ import を書くだけで型が適用されるの？」と不思議に思うかもしれません。それは、TypeScriptが自動的に node_modules/@types フォルダの中を探しに行ってくれる設定になっているからです。

この設定は、tsconfig.json というTypeScript全体の設定ファイルで管理されています。基本的には触らなくても自動で読み込まれますが、もし特別な場所に型定義ファイルを置きたい場合は、以下のように設定を変更することもあります。


{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./custom-types"]
  }
}

typeRoots（タイプ・ルーツ）という項目は、「型定義ファイルを探しに行く場所のリスト」です。初心者の方は「デフォルトでは node_modules/@types を見ているんだな」と覚えておくだけで十分です。

6. 型定義ファイルが最初から入っているライブラリもある？

最近の新しいライブラリの中には、わざわざ @types/xxx を個別にインストールしなくてもいいものも増えています。これは、ライブラリの作者が「最初から説明書（型定義ファイル）を同梱してくれている」からです。これを「Built-in Types（ビルドイン・タイプス）」と呼びます。

例えば、有名な「axios（アクシオス）」という通信用のライブラリなどは、本体をインストールするだけで型情報も一緒についてきます。個別にインストールが必要かどうかを判断するには、以下の方法があります。

npm install したときに、自動で型が効くか試してみる。
エディタでエラー（赤波線）が出て、「Could not find a declaration file...」と表示されたら @types を探す。
npmの公式サイトで、ライブラリ名の横に「DT」という青いアイコンがあるか確認する。

「DT」アイコンは DefinitelyTyped の略で、これが付いていれば個別に @types をインストールする必要があるというサインです。

7. 名前空間（namespace）とモジュールの違い

外部の型を読み込む際に、古いプログラムや特定のライブラリでは「名前空間（名前空間）」という言葉が出てくることがあります。これは、プログラムの「苗字」のようなものです。

昔のJavaScriptでは、同じ名前の関数や変数が混ざってしまう「名前の衝突」という問題がよく起きていました。例えば、Aさんが作った calculate 関数と、Bさんが作った calculate 関数が同じ場所にあると、コンピュータが混乱してしまいます。これを防ぐために「Aさんのグループの中の calculate」「Bさんのグループの中の calculate」と分ける仕組みが名前空間です。

現代のTypeScriptでは、今回紹介した import を使う「モジュール」という仕組みが主流ですが、古い型定義ファイルの中には名前空間を使っているものもあります。「どちらもプログラムが混ざらないように整理整頓するための仕組みなんだな」と理解しておけば、初心者としては完璧です。

8. 型が見つからない時の対処法

もし、どうしても @types が見つからないマイナーなライブラリを使いたいときはどうすればいいでしょうか？そのままではTypeScriptが怒ってしまい、プログラムを動かせません。そんな時の「緊急避難」として、「型定義の自作」という方法があります。

プロジェクトのルート（一番上の階層）に declarations.d.ts というファイルを作り、中身を以下のように書きます（例：my-libraryというライブラリの場合）。


declare module "my-library";

これは、「my-libraryという名前の道具を使います。細かいルール（型）はわからないけど、とにかく存在することだけは認めてください！」とTypeScriptにお願いする魔法の言葉です。これを使うとエラーは消えますが、入力補完などの便利な機能は使えなくなります。あくまで最終手段として覚えておきましょう。

9. 型定義ファイルを最新に保つ重要性

外部ライブラリは日々バージョンアップされています。本体のライブラリだけ新しくして、型定義ファイル（説明書）が古いまま放置していると、「本体には新しい機能があるのに、説明書には載っていないからエラーになる」というズレが発生します。

プログラムを開発しているときは、定期的に npm update などのコマンドを使って、本体と型定義ファイルの両方を最新の状態に保つように心がけましょう。これにより、最新の機能を安全に（型に守られながら）使うことができるようになります。

TypeScriptの大きな魅力は、この世界中に広がる「型定義の共有財産」にあります。自分で一からルールを作らなくても、先人たちが用意してくれた @types を活用することで、初心者でもミスが少なく、プロのような高度なプログラムを組み立てていくことが可能になるのです。まずは、使いたいライブラリを見つけたら「@typesがあるかな？」と探す癖をつけてみてくださいね。