【入門編】 compilerOptions.declaration – TypeScript実践ガイド

こんにちは。TypeScriptの世界へようこそ。

新しい技術を学び始めるとき、設定ファイルの一つひとつが魔法の呪文のように見えて、どこから手をつけていいか不安になりますよね。でも大丈夫、安心してください。今日はその中でも、特にライブラリ開発の「要」となる `compilerOptions.declaration` について、一緒に紐解いていきましょう。

—

TypeScriptの「翻訳」と「説明書」

TypeScriptは、私たちが書いたプログラムを、ブラウザが理解できるJavaScriptに翻訳してくれる頼もしい相棒です。

でも、考えてみてください。あなたが作った素晴らしい機能を、他の誰かが自分のプロジェクトで使いたいと思ったとき、相手のパソコンはあなたのプログラムの「中身」をどうやって理解すればいいのでしょうか？

そこで登場するのが `.d.ts`（型定義ファイル） です。これは、あなたのプログラムがどんな道具（関数や変数）を持っていて、どうやって使えばいいのかを記した「取扱説明書」のようなものです。

なぜ `declaration` が必要か？

もしあなたが、誰かに「特製のスパイスボックス」をプレゼントするとします。中身が何かわからないまま渡されたら、相手は困ってしまいますよね。「これは何に使うの？」「入れる量はこのくらいでいいの？」と質問攻めになるでしょう。

`declaration: true` という設定は、TypeScriptに対して「プログラムを変換するついでに、自動的に立派な取扱説明書（.d.ts）も作っておいてね！」とお願いする魔法のスイッチなんです。

—

さっそく設定してみよう

`tsconfig.json` というファイルを開いてみてください。プロジェクトの根っこにあるはずです。そこに、以下のように一行書き加えるだけです。

{
“compilerOptions”: {
// コンパイルしたとき、型定義ファイル（.d.ts）も一緒に生成して！という合図です
“declaration”: true,

// コンパイル後のファイルが出力される場所を指定します
“outDir”: “./dist”
}
}

たったこれだけで、TypeScriptはコードをコンパイルするたびに、ソースコードの横にひっそりと、でも確実に、他の開発者が読みやすい「説明書」を書き出してくれるようになります。

—

実際に何が起きているのか？

例として、簡単な計算機能を作ってみたとしましょう。

src/index.ts

2つの数字を足し合わせる魔法の関数

/
export const add = (a: number, b: number): number => {
return a + b;
};

この状態でコンパイルを走らせると、`dist`フォルダの中には以下の2つが生成されます。

1. `index.js`（ブラウザが動かすための実働プログラム）
2. `index.d.ts`（他の人があなたのコードを使うときに参照する説明書）

この `index.d.ts` を覗いてみると、中身はこんな感じです。

dist/index.d.ts

2つの数字を足し合わせる魔法の関数

/
export declare const add: (a: number, b: number) => number;

見てください！余計な計算のロジックは消えて、「`add`っていう関数があるよ。数字を2つ入れると、数字が返ってくるよ」という、「使い手にとって必要な情報」だけが綺麗にまとめられています。 これが、あなたが書いたコードが世界中で使われるためのパスポートになるんです。

—

初学者がつまずきやすいポイント

ここまで読んで、「あれ、自分の環境だと `declaration` を有効にしても何も起きない気がする…」と不安になった方はいませんか？

よくあるのが、「ファイルをコンパイルするコマンドを忘れている」というケースです。ただ設定を書いただけでは、TypeScriptは動き出しません。ターミナルで `npx tsc` と打って、実際に翻訳作業をスタートさせてあげてくださいね。

また、`declaration` を有効にすると、プロジェクトのフォルダが少しだけ賑やかになります。最初から完璧に整理しようとせず、まずは「自分のプログラムに説明書がついた！」という成功体験を喜んでください。

—

最後に：型定義ファイルは「親切の証」

プログラミングの世界では、動けばいいコードを書くのはスタート地点に過ぎません。その先にある「誰かに使ってもらうこと」を考えたとき、この `declaration: true` という設定は、あなた自身のエンジニアとしての「優しさ」を表現する手段になります。

もし、将来あなたが作ったライブラリが誰かの役に立つとき、その人はきっと、あなたが自動生成した `.d.ts` を読んで「ああ、こうやって使えばいいんだ！」と笑顔になっているはずです。

TypeScriptの環境構築は、最初は少し泥臭い作業の連続かもしれません。でも、一つひとつ丁寧に紐解いていけば、必ずあなたの力になります。

もしまた分からないことがあれば、いつでも聞きに来てくださいね。あなたの挑戦を、心から応援しています。