型は実行時には消える — TypeScriptを後から入れる

TypeScriptを導入する。コード画面と型を示すカード、検査する虫眼鏡とチェック。

型は実行時には消えます。既存のプロジェクトに後からTypeScriptを入れて、どこまで守ってくれるのかを実際に確かめます。

前回: VitestでReactのテストを書く|要素の取得方法とテストの分け方 作業場所はVMの中(Ubuntu)です。前回まで作ってきた ~/react-demo/ の続きです。

このサイトで、これまでに踏んだ事故を3つ並べます。

1つめ。 JavaScriptの回で書きました。

user.nmae   // undefined(エラーは出ない)

打ち間違えているのに、何も起きません。 undefined が静かに返るだけです。

2つめ。 非同期処理の回で書きました。

console.log(data.items);          // undefined(エラーは出ない)
console.log(data.items.length);   // Uncaught TypeError

await を忘れた data は Promise です。 そこに items は無いので、また undefined です。エラーになるのは、その undefined をさらに触った、次の行です。

3つめ。 REST APIの回の、つまずき表にこう書きました。

req.params.id が文字列で困る — URLから来る値は必ず文字列。

この3つには、同じ形があります。

間違えた瞬間には、何も起きない。 ずっと後で、まったく関係のない場所が壊れる。

そして3つとも、「書いている最中に赤い線が引かれていれば、1秒で終わっていた」ものです。

それをやるのが TypeScript です。

ただし、この記事で一番伝えたいのは、TypeScript ができることではなく、できないことのほうです。そこを誤解したまま入れると、「型を書いたのに落ちた」で嫌いになります。

対象レベル: 初級 / 区分: 必修

目次

この記事でわかること

  • TypeScript は別の言語ではないこと。JavaScript に型注釈を足しただけで、tsc がやっているのは、その注釈を消すこと。ビルドツールの回で「トランスパイルの一種」と書いたことの、中身
  • 実行時には、1ミリも守ってくれないこと。型は動くコードに1文字も残りません。 だから APIから返ってきたJSONは、型を書いても中身が保証されない。ここが一番危ない
  • Vite は型検査をしないこと。npm run build が通っても、型が合っている証明にはならない。検査は tsc --noEmit が別に走る
  • any を1つ書くと、その先の検査が全部消えること。「分からない」を表したいときに使うのは unknown
  • 型を書きすぎると、かえって読みにくくなること。書くのは境界だけで、中は推論に任せる

この記事でやること

  1. tsc に1ファイルだけ通して、型注釈が消えた JavaScript が出てくるのを目で見る
  2. ~/react-demo/ に TypeScript を入れ、tsconfig.json を置き、npm run typecheck を作る
  3. .jsx を .tsx に、1ファイルずつ移す(3ファイルだけ。全部はやりません)
  4. props に型を付け、わざと打ち間違えて、保存する前に叱られることを確かめる
  5. any に置き換えて、検査が消えるのを見る。そのあと unknown で書き直す

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
TypeScriptJavaScript に「型の書き方」を足したもの。 JavaScript のコードは、そのままで TypeScript として通る
型注釈name: string のように、「これは文字列だ」と人が書き足す部分
型推論書かなくても、TypeScript が値から勝手に判断してくれること
tscTypeScript のコンパイラ。型を検査するのと、型注釈を消して .js を出すの、2つの仕事をする
tsconfig.jsontsc の設定ファイル。 どのファイルを、どれくらい厳しく見るか
strict厳しさをまとめて上げるスイッチ。 今から始めるなら true 一択
型エイリアス型に名前を付けたもの。 type Task = { ... }
ユニオン型「AかB」を表す型。 string | number
any「何でもいい」。 そこから先の検査が全部止まる
unknown「中身が分からない」。 確かめるまで、何も触らせてもらえない
型ガード実行時に中身を確かめて、型を絞り込む書き方
型定義ファイル(.d.ts)JavaScript で書かれたライブラリに、後から型だけを付けるファイル
@types/○○その型定義ファイルだけを配っている npm パッケージ
構造的型付け名前ではなく「形」が合っていれば同じ型とみなす、TypeScript の考え方

① TypeScript は、別の言語ではない

まず、ここを固めます。

ビルドツールの回で、TypeScript をこう紹介しました。

function greet(name: string): string {
  return `こんにちは、${name}さん`;
}

: string の部分は TypeScript の書き方です。ブラウザにそのまま渡すと構文エラーで止まります。 だから、こう書き直してから渡します。

function greet(name) {
  return `こんにちは、${name}さん`;
}

型の情報を消しただけです。

あのとき「トランスパイルの一種」として1行で流したものを、今回はそこだけを主役にします。

3つの言い方で、同じことを言います

言い方中身
足し算であるJavaScript のコード全部が、そのまま TypeScript として通る。 拡張子を変えるだけで、書き直しは要らない
引き算しかしないtsc が出す JavaScript は、型注釈を消しただけ。 速くもならないし、機能も増えない
実行には関わらないブラウザも Node.js も、TypeScript を知らない。 動いているのは、型が消えたあとの JavaScript

「新しい言語を覚え直す」ではありません。 いま書ける JavaScript に、注釈を足していくだけです。

だから、この記事は「全部を書き直す」記事にはなりません。 1ファイルずつ、注釈を足しながら移していきます。 移していないファイルは、.jsx のまま普通に動きます。


② 型が消えるところを、実際に見る

言葉だけだと信じられないので、tsc を1回だけ手で動かします。

TypeScript を入れる

VMの中で、~/react-demo/ に入ります。

bash
$ cd ~/react-demo
$ npm install -D typescript @types/react @types/react-dom

3つ入れました。

入れたもの役割
typescripttsc の本体。 検査と、型消しをする
@types/reactReact の型定義。 useState が何を返すか、といった情報
@types/react-domreact-dom の型定義

なぜ React 本体だけでは足りないのか。 React は JavaScript で書かれています。 JavaScript には型が書いてありません。そこで、有志が型定義ファイル(.d.ts)だけを別に作り、@types/react という名前で配っています。 これは「DefinitelyTyped」という、巨大な共同作業の一部です。ライブラリを入れて型が効かないときは、まず @types/そのライブラリ名 があるか探します。 最近のライブラリは自分で型定義を同梱していることが多く、その場合 @types/ は要りません。Vite や Vitest がそうです。

-D は開発のときだけ要る印です(npmの回)。利用者に配る dist/ には、TypeScript は1バイトも入りません。

入ったか確かめます。

bash
$ npx tsc --version
Version 5.9.2

数字は違って構いません。 5 系なら、この記事のとおりに進みます。

1ファイルだけ、通してみる

プロジェクトを汚したくないので、別の場所に作ります。

bash
$ mkdir -p ~/ts-try
$ nano ~/ts-try/greet.ts
function greet(name: string): string {
  return `こんにちは、${name}さん`;
}

console.log(greet("たろう"));

拡張子は .ts です。

tsc に通します。

bash
$ cd ~/ts-try
$ ~/react-demo/node_modules/.bin/tsc greet.ts --target ES2020

なぜ長いパスを打っているのか。 tsc は ~/react-demo/node_modules/ の中に入っています。 npmの回でやったとおり、npm install で入れたコマンドは node_modules/.bin/ に置かれます。 npx tsc でも同じものが動きますが、いまは ~/ts-try にいて node_modules がありません。 「どこに入っているのか」を1度は見ておいてください。

何も表示されずに終わります。 成功です。

bash
$ ls
greet.js  greet.ts

greet.js が増えています。 中を見ます。

bash
$ cat greet.js
function greet(name) {
    return `こんにちは、${name}さん`;
}
console.log(greet("たろう"));

: string が2つとも消えています。それだけです。

ビルドツールの回で「こう書き直します」と手で書いて見せたものが、そのまま出てきました。

間違えてみる

greet.ts の最後の行を、こう変えます。

console.log(greet(42));

もう一度、同じコマンドを打ちます。

bash
$ ~/react-demo/node_modules/.bin/tsc greet.ts --target ES2020
greet.ts:5:19 - error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

5 console.log(greet(42));
                    ~~

Found 1 error in greet.ts:5

「数値は、文字列の引数に入れられません」と言っています。

[スクリーンショット: 01_tscの型エラー.png] VMのターミナルで tsc greet.ts を実行し、error TS2345 の行と、42 の下に ~~ が付いている画面を撮ってください。

ここまでは、期待どおりです。 問題は、この次です。

bash
$ cat greet.js
function greet(name) {
    return `こんにちは、${name}さん`;
}
console.log(greet(42));

エラーが出たのに、greet.js は作り直されています。 しかも中身は greet(42) のままです。

tsc は、既定では「文句は言うが、出力は止めない」です。止めたいときは --noEmitOnError を付けます。

これが、この記事の中心にある事実です。

型は、動くコードに1文字も残りません。 tsc は「間違っていますよ」と言うだけで、間違ったまま動かすことを止めはしません。

確かめ終わったので、片づけます。

bash
$ rm -rf ~/ts-try

③ 一番危ない誤解 — 実行時には守ってくれない

②を踏まえて、最大の落とし穴に行きます。 ここを飛ばすと、型を書いたことでかえって危なくなります。

書ける、通る、そして嘘

Node.jsのAPIの回で作ったサーバーから、タスクを取ってくるとします。

type Task = {
  id: number;
  title: string;
  done: boolean;
};

const res = await fetch("http://localhost:3000/tasks");
const tasks: Task[] = await res.json();

console.log(tasks[0].title);

このコードは、型検査を通ります。 1つも警告は出ません。

では、サーバーがこう返してきたら、どうなるでしょうか。

{"items":[{"id":"3","name":"牛乳を買う","done":0}]}
書いた型実際に来たもの
配列{ items: [...] } というオブジェクト
id: number"3" という文字列
title: stringtitle は無く、name がある
done: boolean0 という数値

tasks[0] は undefined になり、.title を読んだ瞬間に落ちます。

TypeError: Cannot read properties of undefined (reading 'title')

非同期処理の回で踏んだ data.items と、まったく同じ壊れ方です。型を書いても、1ミリも変わりませんでした。

なぜこうなるのか

res.json() の戻り値は any だからです。

any は「何でもいい」という型です。const tasks: Task[] = ... は、確かめたのではなく、「これは Task[] ということにしてくれ」と宣言しただけです。

そして②で見たとおり、型は実行時に消えます。 fetch の結果を照合するコードは、どこにも生成されません。

同じことが req.params.id でも起きます。

const id: number = req.params.id;   // ← ここは怒られる
const id = Number(req.params.id);   // ← 変換して初めて数値になる

上の行はエラーになるので気づけます。 ですが、JSON.parse を経由した瞬間に any になり、誰も見なくなります。

覚えることは1つです。

型が守ってくれるのは、「自分が書いたコードの内側」だけ。 外から来たもの(API・localStorage・URL・フォーム入力・環境変数)は、型を書いた時点では、ただの願望。

境界で、実行時に確かめる

では、どうするか。 「外から入ってくる場所」で、実際に中身を見ます。

type Task = {
  id: number;
  title: string;
  done: boolean;
};

function isTask(value: unknown): value is Task {
  if (typeof value !== "object" || value === null) return false;
  const v = value as Record<string, unknown>;
  return (
    typeof v.id === "number" &&
    typeof v.title === "string" &&
    typeof v.done === "boolean"
  );
}

const res = await fetch("http://localhost:3000/tasks");
const raw: unknown = await res.json();

if (!Array.isArray(raw) || !raw.every(isTask)) {
  throw new Error("サーバーの返事が、想定した形ではありません");
}

console.log(raw[0].title);

新しい書き方が2つ出てきました。

書いたもの意味
value: unknown「中身が分からない値」。 確かめるまで、value.id すら書かせてもらえません
value is Task型ガード。 「この関数が true を返したら、それは Task として扱ってよい」と TypeScript に教える戻り値の書き方

typeof はJavaScriptの回でやったものそのままです。新しい魔法は使っていません。 実行時に、素の JavaScript で中身を見ているだけです。

そして最後の行の raw[0].title は、もう安全です。 if を通り抜けた時点で、TypeScript は raw を Task[] として扱ってくれます。

実務では、これを手で書くことはあまりありません。 zod のようなライブラリを使うと、「型」と「実行時の確認」を1回書くだけで両方作れます。 ですが、この記事では入れません。 「ライブラリが何を代わりにやってくれるのか」を、先に自分の手で書いておかないと、なぜ要るのかが分からないからです。 上のコードが「面倒だ」と思えたなら、それがライブラリを入れる理由です。


④ 既存のプロジェクトに、後から入れる

新規プロジェクトなら npm create vite@latest で TypeScript を選ぶだけです。ですが、ここでは後から入れます。

理由は2つです。

  • 仕事で出会うのは、たいてい「すでにある JavaScript のプロジェクト」です。作り直せません
  • 一度に全部変えると、何十個ものエラーが同時に出ます。 どれが本物の間違いで、どれが設定の問題か、区別できなくなります

絶対に守る方針を、先に書きます。

全部を一度に変えない。1ファイルずつ移す。移すたびに動かす。

tsconfig.json(新規・全文)

bash
$ nano ~/react-demo/tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "allowJs": true,
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

1行ずつ、何のためにあるか書きます。

設定意味
targetどのくらい新しい JavaScript の書き方まで、そのまま残してよいか
lib最初から存在するものとして扱う一覧。 DOM を入れないと document が知らない名前になります
module / moduleResolutionimport の解決の仕方。 bundler は「Vite のようなビルドツールが後ろにいる」前提の設定
jsx: "react-jsx"JSX を、React 17以降のやり方で変換する。 これがあるので import React を書かなくて済みます
⭐ allowJs: true.js / .jsx のファイルが混ざっていてもよい。 これが「1ファイルずつ移す」の心臓部です
⭐ strict: true厳しさをまとめて上げる。 特に 「型を書き忘れた引数」をエラーにする(noImplicitAny)
noEmit: true.js を出さない。 検査だけする。 出すのは Vite の仕事です
isolatedModules1ファイルずつ独立して変換できる書き方だけ許す。 Vite(esbuild)はそうやって変換するので、揃えます
skipLibChecknode_modules の中の型定義までは検査しない。 無いと、他人のライブラリのエラーで足が止まります
include見るのは src の中だけ

allowJs: true を、checkJs: true と間違えないでください。 allowJs は「混ざっていてよい」だけです。.jsx のファイルは、置いてあっても検査されません。 checkJs: true にすると、.jsx のファイルまで全部検査が始まります。 いま入れると、移していないファイルまで真っ赤になります。 今日は入れません。

strict: true を、最初から true にしている理由。 false から始めて後で上げるのは、ほぼ必ず失敗します。 false の間に書いたコードは true を通らないので、上げる日が来ると数百個のエラーが出て、結局そのままになります。 これから移すファイルは、最初から strict で書きます。

npm run typecheck を作る — Vite は型を見ない

ここが、TypeScript 導入で最も見落とされるところです。

Vite は、型検査をしません。

Vite が中で使っている esbuild は、②で見たのと同じ「型注釈を消す」作業だけをします。 速いのは、検査していないからです。

つまり、こうなります。

コマンド型が間違っていたら
npm run dev普通に動きます。 何も言いません
npm run build普通に成功します。 dist/ もできます
npm test(Vitest)普通に通ります。 Vitest も型は見ません
tsc --noEmitここだけが、エラーにします

package.json の scripts を、こうします。

bash
$ nano ~/react-demo/package.json
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "lint": "eslint .",
    "preview": "vite preview",
    "test": "vitest run",
    "test:watch": "vitest",
    "typecheck": "tsc --noEmit"
  },

変えたのは2箇所です。

  1. typecheck を足した
  2. build の先頭に tsc --noEmit && を足した

&& はLinuxのコマンドの回で出てきたものと同じで、「左が成功したときだけ右を実行する」です。 これで、型エラーがあるときは dist/ が作られません。 「間違ったものを配ってしまう」を、機械が止めます。

動かします。

bash
$ cd ~/react-demo
$ npm run typecheck
> react-demo@0.0.0 typecheck
> tsc --noEmit

何も出ません。 これが成功です。

「何も出ない=成功」は、Linux の道具に共通の作法です。言うことがあるときだけ言います。 ここまでで何度も見てきたはずです。

まだ .ts のファイルは1つもありませんが、設定は動いています。


⑤ 1ファイル目 — TaskSummary に props の型を付ける

移す順番には、原則があります。

葉っぱから移す。 他のファイルを読み込んでいないもの、から。

TaskSummary は、import が1つもありません。 ここから始めます。

まず、型を置く場所を作る

Task の形は、この先いくつものファイルで使います。 1箇所に置きます。

bash
$ nano ~/react-demo/src/types.ts
export type Task = {
  id: number;
  title: string;
  done: boolean;
};

JSX を書かないので、拡張子は .tsx ではなく .ts です。UserContext.js を .js にしたのと同じ理由です。

なぜこの形なのか、確かめておきます。 状態管理の回の tasksReducer.js に、こう書いてありました。

return [...tasks, { id: Date.now(), title: action.title, done: false }];

Date.now() は数値、action.title は文字列、done は真偽値。 型を書くというのは、すでにあるものを言葉にする作業です。新しく決めているわけではありません。

ファイルの名前を変える

bash
$ cd ~/react-demo
$ mv src/components/TaskSummary.jsx src/components/TaskSummary.tsx

Git で管理しているなら git mv のほうがよいです(GitHubの回)。「削除して新規作成」ではなく「移動」として記録されるので、履歴が繋がります。

git mv src/components/TaskSummary.jsx src/components/TaskSummary.tsx

src/components/TaskSummary.tsx(丸ごと置き換え)

import type { Task } from "../types";

type Props = {
  tasks: Task[];
};

function TaskSummary({ tasks }: Props) {
  const remaining = tasks.filter((t) => !t.done).length;

  return (
    <p>
      残り {remaining} 件 / 全 {tasks.length} 件
    </p>
  );
}

export default TaskSummary;

元のコードと違うのは、3箇所だけです。

足したもの意味
import type { Task }型だけを読み込む。 type と書いてあるので、変換したときに import の行ごと消えます
type Props = { tasks: Task[] }このコンポーネントが受け取る props の形。Task[] は「Task の配列」
{ tasks }: Props受け取った props が Props の形であること

中身のロジックは1文字も変えていません。

読み込んでいる側の import を直す

これを忘れると、画面が真っ白になります。

App.jsx は、いまこう書いてあります。

import TaskSummary from "./components/TaskSummary.jsx";

TaskSummary.jsx は、もう存在しません。 拡張子を消します。

import TaskSummary from "./components/TaskSummary";

なぜ「.tsx に書き換える」ではなく「消す」のか。 拡張子を書かなければ、Vite が .tsx でも .jsx でも探してくれます。 次に別のファイルを移したとき、また直しに来なくて済みます。 .tsx と書くこともできますが、TypeScript 側では既定で禁止されています(allowImportingTsExtensions を足せば通ります)。消すのが一番楽です。

動かして確かめる

bash
$ cd ~/react-demo
$ npm run typecheck
$ npm test
$ npm run dev -- --host
  • typecheck が無言で終わる
  • npm test が 2 passed(前回書いたテストは、1文字も変えていません)
  • ブラウザで開いて、「残り 0 件 / 全 0 件」がいつもどおり出る

3つとも通れば、1ファイル目は完了です。

テストが素通りしたことに、注目してください。 .jsx を .tsx にしても、動くものは何も変わっていません。 前回書いたテストは、.tsx になったことすら知りません。 前回「実装の詳細をテストするな」と書いた意味が、ここで効いています。 className でテストしていたら、いま直しに行くことになっていました。

わざと打ち間違える

②の greet(42) と同じことを、今度は本物のコードでやります。

TaskSummary.tsx の !t.done を、!t.dome に変えてください。

  const remaining = tasks.filter((t) => !t.dome).length;
bash
$ npm run typecheck
src/components/TaskSummary.tsx:8:44 - error TS2551: Property 'dome' does not exist on type 'Task'. Did you mean 'done'?

8   const remaining = tasks.filter((t) => !t.dome).length;
                                             ~~~~

  src/types.ts:4:3
    4   done: boolean;
        ~~~~
    'done' is declared here.

Found 1 error in src/components/TaskSummary.tsx:8

Did you mean 'done'? まで言っています。 そして types.ts の4行目まで案内しています。

これが、記事の冒頭に置いた1つめの事故への答えです。

user.nmae   // undefined(エラーは出ない)

JavaScript のままだと、t.dome は undefined になります。 !undefined は true なので、「全部が未完了」として数えられます。 画面には「残り 3 件 / 全 3 件」と、それらしい数字が出ます。 完了にしても数が減らない、という形で、ずっと後になって気づきます。

[スクリーンショット: 02_型エラーで叱られる.png] npm run typecheck で Property 'dome' does not exist on type 'Task' が出ている画面を撮ってください。Did you mean 'done'? の部分が入るように。

VS Code から繋いでいるなら(VS Code Remote SSH の回)、保存する前から dome に赤い波線が引かれているはずです。

[スクリーンショット: 03_エディタの赤い波線.png] VS Code で TaskSummary.tsx を開き、dome の下に赤い波線が出ているところを撮ってください。

ターミナルで走らせるより、こちらのほうが本題です。 npm run typecheck は「後で気づく」仕組みですが、エディタの赤い線は「打っている最中に気づく」仕組みです。同じ tsc が、裏で動いています。

確かめ終わったので、dome を done に戻してください。


⑥ 2・3ファイル目 — 関数の props に型を付ける

次は TaskMeta と TaskItem です。 ここで、props が値だけでないことが分かります。

TaskMeta を移す

bash
$ cd ~/react-demo
$ mv src/components/TaskMeta.jsx src/components/TaskMeta.tsx

src/components/TaskMeta.tsx(丸ごと置き換え)

import { memo, useContext } from "react";
import { UserContext } from "../contexts/UserContext";
import type { Task } from "../types";

type Props = {
  task: Task;
};

function TaskMeta({ task }: Props) {
  const { user } = useContext(UserContext);

  return (
    <span className="meta">
      担当: {user} / 登録 {new Date(task.id).toLocaleTimeString()}
    </span>
  );
}

export default memo(TaskMeta);

UserContext の import からも、拡張子を消しました。

UserContext.js は、まだ JavaScript のままです。 それでも型は効きます。

export const UserContext = createContext({
  user: "名無し",
  setUser: () => {},
});

TypeScript は、この既定値を見て user が文字列だと推論します。 allowJs: true にしてあるので、JavaScript のファイルからも、書いてある値の形を読み取ってくれます。 移していないファイルが、足を引っ張らないということです。

TaskItem.jsx の import を直します。

import TaskMeta from "./TaskMeta";

TaskItem を移す

bash
$ mv src/components/TaskItem.jsx src/components/TaskItem.tsx

src/components/TaskItem.tsx(丸ごと置き換え)

import TaskMeta from "./TaskMeta";
import type { Task } from "../types";

type Props = {
  task: Task;
  onToggle: (id: number) => void;
  onRemove: (id: number) => void;
};

function TaskItem({ task, onToggle, onRemove }: Props) {
  return (
    <li>
      <span
        onClick={() => onToggle(task.id)}
        className={task.done ? "done" : ""}
      >
        {task.title}
      </span>
      <button onClick={() => onRemove(task.id)}>削除</button>
      <TaskMeta task={task} />
    </li>
  );
}

export default TaskItem;

TaskList.jsx の import も直します。

import TaskItem from "./TaskItem";

関数の型の読み方

新しいのは、この2行だけです。

  onToggle: (id: number) => void;
  onRemove: (id: number) => void;
部分意味
(id: number)数値を1つ受け取る
=>その関数は
void何も返さない

コンポーネントの回で書いた「子は出来事を報告するだけ」が、そのまま型になっています。

void は「戻り値を使わない」という宣言です。返してもよいが、こちらは見ない、という意味です。

そして、これで防げるものが増えました。

<button onClick={() => onRemove(task)}>削除</button>

task.id と書くべきところを task と書いた場合です。

error TS2345: Argument of type 'Task' is not assignable to parameter of type 'number'.

JavaScript のままだと、これは何も起きません。 tasks.filter((t) => t.id !== オブジェクト) が全件 true になり、「削除ボタンを押しても消えない」という形で現れます。エラーは1つも出ません。

これが、冒頭に並べた3つの事故と、同じ形です。

動かす

bash
$ npm run typecheck
$ npm test
$ npm run dev -- --host

ブラウザで、タスクを追加して、押して、削除してください。 前回までとまったく同じに動きます。

ここで止めます

App.jsx TaskList.jsx TaskForm.jsx Header.jsx Board.jsx tasksReducer.js は、.jsx / .js のまま残します。

理由は「今日はここまで」ではなく、これが正しい進め方だからです。

移したまだ
葉っぱ。他を読み込んでいないApp.jsx。全部を束ねている
props の形がはっきりしているtasksReducer.js。ユニオン型という別の話が要る

App.jsx を最初に移すと、そこから芋づるで全ファイルのエラーが出ます。 葉っぱから根に向かって移すと、1回のエラーは1ファイルぶんで済みます。 残りは、次に触る用事ができたときに、そのついでに移せばよいです。「移すためだけの日」を作る必要はありません。


⑦ any を書くと、全部が無意味になる

移していると、必ず「よく分からないから、とりあえず通したい」場面が来ます。 そこで any に手が伸びます。

やってみる

TaskSummary.tsx の型を、一時的にこうします。

type Props = {
  tasks: any;
};

そして、また dome に打ち間違えます。

  const remaining = tasks.filter((t) => !t.dome).length;
bash
$ npm run typecheck

何も出ません。 通ります。

さらに、こう書いても通ります。

  const remaining = tasks.存在しないメソッド().なんでも.length;

any は「型が分からない」ではありません。 「ここから先は検査するな」という命令です。 そして any は伝染します。 any から取り出した値も any です。1つ書くと、そこから流れていく先が全部、検査されなくなります。

確かめ終わったので、tasks: Task[] に戻してください。

any と unknown

「本当に中身が分からない」ときに使うのは unknown のほうです。

anyunknown
何を表すか検査をやめる中身が分からない
そのまま .title を読めるか読める(そして落ちる)⭐ 読めない。エラーになる
他の型の変数に入れられるか入れられる入れられない
使うために—typeof などで確かめて、絞り込む
let a: any = JSON.parse('{"x":1}');
a.title.toUpperCase();       // ✅ 通る。実行すると落ちる

let u: unknown = JSON.parse('{"x":1}');
u.title.toUpperCase();       // ❌ error TS18046: 'u' is of type 'unknown'.

unknown は、③で書いた型ガードとセットです。

if (typeof u === "string") {
  u.toUpperCase();           // ✅ ここでは string として扱える
}

unknown の良さは、「不便であること」です。 any は「危険な場所」を見えなくします。unknown は「ここは確かめないと使えない」と、その場に印を残します。 JSON.parse も res.json() も、返すのは any です。受け取った瞬間に const raw: unknown = ... と書き直すだけで、確認を忘れられなくなります。

どうしても any を書くときは、理由を1行書いてください。

// TODO: サーバー側の型が決まったら差し替える
const config: any = loadLegacyConfig();

「後で直す」と書いていない any は、永久に残ります。


⑧ 型を書きすぎない

ここまで読むと、逆に振れます。 全部に型を書きたくなります。 やめてください。

書かなくていいもの

// ❌ くどい
const remaining: number = tasks.filter((t) => !t.done).length;
const title: string = "やること";
const isEmpty: boolean = tasks.length === 0;

// ✅ これでいい
const remaining = tasks.filter((t) => !t.done).length;
const title = "やること";
const isEmpty = tasks.length === 0;

.length は数値だと、TypeScript は知っています。 書いても情報は1つも増えません。

それどころか、害があります。

書いた型は、直さなければならないものです。 remaining の計算方法を変えて文字列を返すようにしたとき、: number は「直す場所」として増えます。 書いていなければ、勝手に付いてきます。

書くべきもの

基準は1つです。

境界には書く。中には書かない。

書く書かない
props の型(type Props)関数の中の変数
関数の引数return の型(推論に任せる)
外から来るデータの形(API・設定)コンポーネントの戻り値(JSX.Element と書かない)
空で始まる状態(下記)useState("") のように初期値で分かるもの

例外:空で始まると、推論が効かない

これは必ず踏むので、先に書きます。

const [tasks, setTasks] = useState([]);

この tasks の型は、never[](何も入れられない配列)になります。 [] を見ても、中身が何なのか判断しようがないからです。

error TS2345: Argument of type 'Task' is not assignable to parameter of type 'never'.

こういうときだけ、自分で教えます。

const [tasks, setTasks] = useState<Task[]>([]);

<Task[]> は「この useState は Task の配列を持つ」という指定です。

<> の書き方をジェネリクスと呼びます。 いまは「型を引数として渡す書き方」とだけ覚えておけば十分です。 自分でジェネリクスを作る必要は、しばらく来ません。 使うだけです。

React.FC を使わない

古い記事では、よくこう書いてあります。

const TaskSummary: React.FC<Props> = ({ tasks }) => { ... };

いまは、これは勧められていません。

  • children を勝手に受け取れることになっていた時期があり、混乱のもとだった
  • ふつうの関数として書けば、{ tasks }: Props だけで足りる

この記事の書き方(function TaskSummary({ tasks }: Props))が、いまの標準です。


つまずいたところ

画面が真っ白になり、Failed to resolve import が出る

[plugin:vite:import-analysis] Failed to resolve import "./components/TaskSummary.jsx" from "src/App.jsx".

→ 拡張子を変えたのに、読み込んでいる側の import を直していません。 .jsx を消して "./components/TaskSummary" にしてください。 これが今回、一番よくやります。 ファイル名を変えたら、必ずそのファイルを import している場所を探す、を癖にします。

bash
$ cd ~/react-demo
$ grep -rn "TaskSummary" src

npm run build が通ったので、型は合っていると思った

→ 合っていません。 Vite は型を見ません。 build の前に tsc --noEmit を入れたのは、まさにこれを防ぐためです。 npm run dev も npm test も、同じく型を見ません。 型を確かめているのは tsc だけです。

Could not find a declaration file for module 'react'.

→ @types/react が入っていません。 npm install -D @types/react @types/react-dom をやり直してください。 react 自体は入っているのに出るので、最初は意味が分かりませんでした。「モジュールが無い」ではなく「型定義が無い」と言っています。

.jsx のファイルまで真っ赤になると身構えていた

→ なりませんでした。 allowJs: true は「置いてあってよい」だけで、検査はしません。 検査させたいなら checkJs: true ですが、いま入れると移していないファイルまで全部エラーになります。 移し終わってから入れるものです。

VS Code のエラーと、npm run typecheck の結果が食い違う

→ VS Code が、自分に同梱されている TypeScript を使っています。 プロジェクトに入れた 5.9.2 とは別物です。 .ts / .tsx のファイルを開いた状態で Ctrl + Shift + P → TypeScript: Select TypeScript Version → Use Workspace Version を選んでください。 正は、いつも npm run typecheck(=プロジェクトの tsc)のほうです。エディタは「速く教えてくれる係」でしかありません。

type と interface のどちらを使うか、で止まった

→ 止まる価値がありませんでした。 ほとんどの場面で、どちらでも同じように書けます。 この記事は type に統一しています。理由は「オブジェクト以外(ユニオン型など)にも同じ書き方が使えるから」だけです。 チームで決まっているなら、それに従ってください。 1人なら、揃っていればどちらでも構いません。


後片づけ

~/ts-try は②で消しました。 残っていたら消してください。

bash
$ rm -rf ~/ts-try

TypeScript を丸ごと外して、前回の状態に戻したいときは、こうします。

bash
$ cd ~/react-demo
$ mv src/components/TaskSummary.tsx src/components/TaskSummary.jsx
$ mv src/components/TaskMeta.tsx src/components/TaskMeta.jsx
$ mv src/components/TaskItem.tsx src/components/TaskItem.jsx
$ rm src/types.ts tsconfig.json
$ npm uninstall -D typescript @types/react @types/react-dom

そのうえで、3ファイルから型注釈を消し、App.jsx TaskItem.jsx TaskList.jsx の import に .jsx を書き戻し、package.json の scripts を、この全文に戻します。

  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "preview": "vite preview",
    "test": "vitest run",
    "test:watch": "vitest"
  },

Git で管理しているなら、こちらのほうが確実です(GitHubの回)。 今回の作業を始める前にコミットしておけば、git checkout . で全部戻せます。 手で戻すと、必ずどこか1行残ります。

残す場合の、最終的な構成はこうです。

bash
$ ls -R ~/react-demo/src
/home/user/react-demo/src:
App.css  App.jsx  App.test.jsx  assets  components  contexts  index.css  main.jsx  setupTests.js  tasksReducer.js  types.ts

/home/user/react-demo/src/components:
Board.jsx  Header.jsx  TaskForm.jsx  TaskItem.tsx  TaskList.jsx  TaskMeta.tsx  TaskSummary.tsx

/home/user/react-demo/src/contexts:
UserContext.js

.jsx と .tsx が混ざっています。 これは途中の状態ではなく、正常な状態です。現場のプロジェクトは、たいていこうなっています。

~/react-demo/ は、この先でも使うので残してください。


まとめ

  • TypeScript は別の言語ではない。 JavaScript のコードは、そのままで TypeScript として通る。 足すのは注釈だけ
  • tsc の仕事は2つ。 型を検査することと、型注釈を消して JavaScript を出すこと。それ以外は何もしない
  • 型は実行時に1文字も残らない。 tsc はエラーを出しても、既定では .js を作り続ける(止めるなら --noEmitOnError)
  • APIから来たJSONは、型を書いても中身が保証されない。 res.json() の戻りは anyで、const tasks: Task[] = ... は確認ではなく宣言
  • 守ってくれるのは「自分が書いたコードの内側」だけ。 API・URL・localStorage・フォーム・環境変数は、境界で実行時に確かめる
  • 境界の確認は、型ガード(value is Task)で書ける。 中身は typeof を並べるだけ。面倒に感じたら、それが zod を入れる理由
  • Vite は型検査をしない。 npm run dev も npm run build も npm test も通る。 検査は tsc --noEmit だけ
  • 後から入れるときは、1ファイルずつ。 allowJs: true がそれを許す。 checkJs はまだ入れない
  • strict: true は最初から入れる。 後から上げる日は来ない
  • 移すのは葉っぱから。 App.jsx から始めると、芋づるで全部エラーになる
  • 拡張子を変えたら、読み込んでいる側の import から拡張子を消す。 画面が真っ白になる原因の第1位
  • props の型は type Props に書き、({ tasks }: Props) で受ける。 React.FC はもう使わない
  • 関数の props は (id: number) => void と書く。 onRemove(task) の書き間違いが、その場で止まる
  • any は「分からない」ではなく「検査するな」。 1つ書くと、そこから先が全部無検査になり、伝染する
  • 「分からない」を表すのは unknown。 確かめるまで何も触らせない、その不便さが価値
  • 型を書きすぎない。 境界には書き、中は推論に任せる。 書いた型は、直す場所として増える
  • 例外は useState([])。 空だと never[] になるので、useState<Task[]>([]) と教える

冒頭に並べた3つの事故のうち、2つは、今日で機械が見つけてくれるようになりました。 t.dome も onRemove(task) も、打った瞬間に赤い線が引かれます。

残る1つ——「APIから返ってきたものが、想定と違う」——は、型では解けません。 あれは、サーバーと画面の約束が食い違っている、という別の問題です。型を書いたことで、その約束をどこかに書き留める必要がある、とはっきりしました。

参考リンク


次に読む

この記事は 【第4段階】フロントエンド の 6 / 15 本目です。

記事
← 前の記事className でテストしない — Vitestで書くReactのテスト
→ 次の記事インデントは人が指摘しない — ESLintとPrettier

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›TypeScript / Type Checkers
  • TypeScript
  • 型注釈とトランスパイル
  • 境界での型の守り方

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次