anyを1つ書くと、そこから先の型検査が消えます。ReactでどこにどうTypeScriptの型を書くのかを決めます。
これは【深掘り】の記事です。本線の順路ではありません。 本線のTypeScriptを後から入れる回で「型は実行時には消える」ところまでやった人が、「では React では、どこにどう型を書けばいいのか」で止まったときに読む記事です。飛ばしても本線は進みます。
この記事のコマンドは、VMの中(Ubuntu Server)で打ちます。 Windows の PowerShell ではありません。 VM に Node.js が入っている必要があります。 入れ方は本線のnpmの回にあります。
node -vで v20 以上が出れば大丈夫です。 画面の確認は、ホストの Windows のブラウザで行います。 これまでの深掘りで作った~/reactlab/には触りません。 この記事では、まっさらな~/tslab/を新しく作り、ポート 5188番で動かします。最後に消します。
やらかした日のことを書きます。
作っていたのは、ユーザーの一覧を出すだけの画面でした。APIから配列が返ってきて、名前を並べる。それだけです。手元では完璧に動いていました。
公開して、30分後に画面が真っ白になりました。
Uncaught TypeError: Cannot read properties of undefined (reading 'name')
ブラウザのコンソールにはこれだけ。私が書いたコードは、一文字も間違っていませんでした。
{users.map((u) => (
<li key={u.id}>{u.profile.name}</li>
))}
間違っていたのは、データのほうです。 退会したユーザーには profile が入っていませんでした。u.profile が undefined になり、その .name を読もうとして落ちた。
私は API のレスポンスの形を、頭の中でだけ覚えていました。 そしてその記憶は間違っていました。
ここが肝心です。私は「型を書くのが面倒だから書かなかった」のではありません。 「自分は形を分かっている」と思い込んでいたから、書く必要を感じなかったのです。 型を書く本当の理由は、自分の記憶が当てにならないことを、機械に指摘してもらうためです。
だから、この記事は「型の書き方」の記事ではありません。
「型に、間違いを見つけてもらう」記事です。 正しいコードを写経するのではなく、わざと間違えて、ビルドが止まるところを見ます。 止まらないパターン(any)も見ます。そのほうが、何のために書いているのかが体に残ります。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
- TypeScript は、実行時には1バイトも残らないこと。型検査と、ブラウザで動く形への変換(トランスパイル)はまったく別の仕事で、
tscが通ったからといって動く保証はどこにも無い - 本当の価値はエディタの赤い波線ではなく、
npm run buildが止まることだということ。赤線は無視できるが、ビルドの失敗は無視できない anyを1箇所書くと、そこから先の検査が全部消えること。anyは「まだ決めていない」ではなく「以後、何も見なくていい」という指示である- 外から来たデータ(
fetchの結果)に型を書いても、何も守られていないこと。型は実行時に消えるので、実行時に検証する道具が別に要る React.FCはいまは使わないこと、useState<User | null>(null)と書いた瞬間に、使うたびの絞り込みが義務になること- どこで型を書くのをやめるかの判断基準。1人開発で型が本当に効くのは、書くときではなくリファクタのとき
この記事でやること
~/tslab/に、まず型の無い React を作り、user.profile.nameで実際に画面を落とすnpm create vite@latestで React + TypeScript を作り直し、tscが何をして何をしないかを確かめる- props・
useState・useRef・イベントに型を付け、必須の prop を渡し忘れてnpm run buildを止める - 1箇所だけ
anyにして、その先のエラーが全部消えるところを見る unknownとzodに置き換え、壊れたデータが画面に着く前に止まることを確かめるstrictの扱いと「ここでやめる」線を決めて、~/tslab/を消す
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 型検査(type check) | 書いたコードの中で、値の形が食い違っていないかを、動かす前に調べること。やるのは tsc |
| トランスパイル | TypeScript を、ブラウザが読める JavaScript に書き換えること。型を消すだけで、検査はしない |
tsc | TypeScript の公式コマンド。検査もできるし変換もできるが、--noEmit を付けると検査だけする |
| 型注釈 | const n: number = 1 の : number の部分。人が手で書く型 |
| 型推論 | 書かなくても TypeScript が勝手に決めてくれる型。const n = 1 なら n は number |
| ジェネリクス | useState<string>('') の <string> のような、型を引数のように渡す書き方 |
| 絞り込み(narrowing) | if (u !== null) のような分岐で、その中だけ型が狭くなること |
any | 「型検査をここでやめる」という指定。何にでも代入でき、何をしてもエラーにならない |
unknown | 「何が入っているか分からない」という型。調べて絞り込むまで、何もさせてもらえない |
strict | tsconfig.json の設定。厳しい検査をまとめて有効にするスイッチ |
| スキーマ検証 | 実行時に、来たデータの形が想定どおりか確かめること。zod などのライブラリがやる |
① 型が無いと、何が起きるか(まず落とす)
道具を入れる前に、痛い目を再現します。 ここを飛ばすと、このあとの作業が「なんとなく丁寧なこと」に見えてしまいます。
まずプレーンな(型の無い)React を作ります。
--の意味は「ここから先はnpmではなくcreate viteに渡す」です。これを忘れると--templateが npm に食われます。
src/App.jsx を、まるごとこう書き換えます。
const users = [
{ id: 1, profile: { name: '田中' } },
{ id: 2, profile: { name: '佐藤' } },
{ id: 3 },
];
export default function App() {
return (
<ul>
{users.map((u) => (
<li key={u.id}>{u.profile.name}</li>
))}
</ul>
);
}
3人目に profile がありません。 退会したユーザーが混ざった、と思ってください。
起動します。
--host 0.0.0.0を付けないと、VMの外(Windows のブラウザ)から見えません。理由はLinuxのネットワークの回にあります。
Windows のブラウザで http://<VMのIPアドレス>:5188/ を開きます。VM の IP は ip a で確かめます。
画面は真っ白です。 F12 でコンソールを開くと、こう出ています。
Uncaught TypeError: Cannot read properties of undefined (reading 'name')
[スクリーンショット: 01_型なしで真っ白.png] — 白い画面と、コンソールのエラーが両方写るように撮ります。
ここで見てほしいのは3つです。
| 事実 | なぜ痛いか |
|---|---|
| 保存した時点では、何も言われなかった | 問題があることを、書いている最中には知りようがない |
| 落ちたのは3件目 | 1件目と2件目は正しく描けている。だから「動いた」と勘違いする |
| 落ちると、リストごと消える | 1件のデータの欠けが、画面全体を持っていく |
u.profile.name は間違ったコードではありません。 データが想定どおりなら正しい。「想定どおりか」を誰も見張っていないことが問題です。
止めます。
② Vite で React + TypeScript を作る
同じものを、TypeScript で作り直します。
--template react が react-ts に変わっただけです。何ができたか見ます。
index.html package.json public src tsconfig.app.json tsconfig.json tsconfig.node.json vite.config.ts
tsconfig.json が増え、src の中身が .tsx になっています。
App.css App.tsx assets index.css main.tsx vite-env.d.ts
| 拡張子 | 何を書くか |
|---|---|
.ts | JSX を書かない TypeScript。関数や型の定義 |
.tsx | JSX を書く TypeScript。コンポーネント |
.ts に JSX を書くとエラーになります。 「型を1個追加しただけなのに落ちた」と悩んだら、まず拡張子を見てください。
ここが一番の誤解:tsc はブラウザに何も出さない
package.json を見ます。
scripts のところに、これが入っているはずです。
{
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
"preview": "vite preview"
}
}
build が2つのコマンドに分かれています。 ここが今日いちばん大事なところです。
| コマンド | 仕事 | 出力 |
|---|---|---|
tsc -b | 型を検査する | 何も出さない(このプロジェクトの設定では) |
vite build | ブラウザ用のファイルを作る | dist/ |
そして npm run dev のとき、tsc は動いていません。
開発サーバーは、型に間違いがあっても普通に起動します。 Vite は .tsx から型を剥がすだけで、正しいかどうかは見ていないからです。
確かめます。 src/App.tsx の中に、明らかにおかしい行を1行だけ足します。
const wrong: number = 'これは文字列です';
console.log(wrong);
起動します。画面も出ます。 エラーは1つも出ません。
別のターミナル(VS Code の別タブでも可)で、検査だけしてみます。このテンプレートのルートの tsconfig.json は、tsconfig.app.json などを参照するだけで自分ではファイルを持たないので、-p tsconfig.app.json で src 用の設定を指定します(付けないと何も検査せずに無言で終わります)。
src/App.tsx:5:7 - error TS2322: Type 'string' is not assignable to type 'number'.
5 const wrong: number = 'これは文字列です';
~~~~~
Found 1 error in src/App.tsx:5
--noEmitは「ファイルを出さずに、検査だけしろ」 という意味です。
同じコードで、npm run dev は通り、tsc は落ちました。
| 誤解 | 実際 |
|---|---|
| 「TypeScript にしたら、間違ったコードは動かなくなる」 | ❌ 動きます。 dev サーバーは型を見ていない |
「tsc が通れば、ブラウザで動く」 | ❌ 動く保証はありません。 型が合っていても中身が間違っていることはある |
| 「型検査と変換は同じ作業」 | ❌ 別の仕事。片方だけ実行できる |
「型検査(tsc)」と「変換(Vite / esbuild)」は、まったく別の仕事です。 Vite は速さのために、変換だけをやって検査を捨てています。 だから検査は自分で走らせる必要があります。
さっき足した2行は消しておきます。
③ props に型を付ける(React.FC は使わない)
コンポーネントを1つ作ります。src/UserCard.tsx を新規作成します。
type User = {
id: number;
name: string;
email: string;
age?: number;
};
type Props = {
user: User;
highlighted: boolean;
onSelect: (id: number) => void;
};
export function UserCard({ user, highlighted, onSelect }: Props) {
return (
<li
style={{ background: highlighted ? '#ffe' : 'transparent' }}
onClick={() => onSelect(user.id)}
>
<strong>{user.name}</strong> — {user.email}
{user.age !== undefined && <span>({user.age}歳)</span>}
</li>
);
}
読み方を分解します。
| 書いたもの | 意味 |
|---|---|
type User = { ... } | User という名前の形を定義した。値ではない |
age?: number | ? は「あってもなくてもよい」。無いときの型は undefined |
onSelect: (id: number) => void | 「number を1つ受け取り、何も返さない関数」という型 |
({ user, highlighted, onSelect }: Props) | 引数全体が Props という形だと宣言している |
user.age !== undefined && の部分に注目してください。 これを書かずに {user.age}歳 とすると、age が無い相手でも「歳」だけ出ます。? を付けた瞬間、「無いとき」を考える義務が生まれます。 これは面倒ではなく、①で落ちたのと同じ問題を、書いている時点で突きつけられているということです。
React.FC を使わない理由
古い記事には、こう書いてあります。
const UserCard: React.FC<Props> = ({ user }) => { ... };
いまは、これは勧められていません。 私も最初はこう書いていて、2回困りました。
| 困ったこと | 何が起きるか |
|---|---|
children が勝手に生えていた(古いバージョン) | 受け取るつもりのないコンポーネントに <A><B/></A> と書けてしまい、渡した側は何も言われないのに、中身はどこにも出ない |
| ジェネリクスが書けない | function List<T>(props: Props<T>) のような型を引数に取るコンポーネントが、React.FC の形では素直に書けない |
| 返せるものが縛られる | 書き方によっては戻り値の型を自分で調整しづらい |
素の関数宣言なら、どれも起きません。
// これでいい
export function UserCard({ user, highlighted, onSelect }: Props) { ... }
「昔の書き方が今も動く」ことと「いま選ぶべき」ことは別です。React 自体の書き方の変化はpropsとstateの深掘りでも触れました。
src/App.tsx から使います。
import { UserCard } from './UserCard';
const users = [
{ id: 1, name: '田中', email: 'tanaka@example.com', age: 30 },
{ id: 2, name: '佐藤', email: 'sato@example.com' },
];
export default function App() {
return (
<ul>
{users.map((u) => (
<UserCard
key={u.id}
user={u}
highlighted={u.id === 1}
onSelect={(id) => console.log('selected', id)}
/>
))}
</ul>
);
}
ブラウザで開いて、2人分出ることを確かめます。onSelect はコンソールに出るだけです。
[スクリーンショット: 02_型付きで表示成功.png] — 一覧が出ている画面と、クリック時のコンソール出力を撮ります。
④ わざと間違える — ビルドを止める
ここが、この記事の本題です。 型は「書いたら偉い」のではなく、間違いを止めてくれて初めて意味があります。 止まるところを見ます。
src/App.tsx を、3通り壊します。1つずつ試して、そのつど戻してください。
壊し方1:必須の prop を渡し忘れる
<UserCard key={u.id} user={u} onSelect={(id) => console.log(id)} />
highlighted を消しました。検査します。
src/App.tsx:12:9 - error TS2739: Type '{ key: number; user: { id: number; name: string; email: string; }; onSelect: (id: number) => void; }' is missing the following properties from type 'Props': highlighted
Found 1 error in src/App.tsx:12
is missing the following properties: highlighted。 何が足りないかを、名指しで言っています。
壊し方2:型の違う値を渡す
<UserCard key={u.id} user={u} highlighted="yes" onSelect={(id) => console.log(id)} />
src/App.tsx:12:35 - error TS2322: Type 'string' is not assignable to type 'boolean'.
"yes" は真っぽく見えますが、boolean ではありません。 JavaScript なら通り、しかも "" を渡した日だけ挙動が変わります。この手のバグは、再現条件が分かるまでに何時間もかかります。
壊し方3:タイポ
<UserCard key={u.id} user={u} highlighted={true} onSelct={(id) => console.log(id)} />
onSelect を onSelct と打ち間違えました。
src/App.tsx:12:52 - error TS2322: Object literal may only specify known properties, and 'onSelct' does not exist in type 'Props'. Did you mean to write 'onSelect'?
Did you mean to write 'onSelect'? まで出ます。
JavaScript だと、これは何のエラーも出ません。 onSelect が undefined のまま渡り、クリックしても何も起きないだけです。「なぜかクリックが効かない」を30分探すことになります。私はやりました。
本当の価値は、エディタの赤線ではない
VS Code で開いていれば、上の3つはどれも赤い波線が出ます。でも赤線は、無視できます。
無視できないのは、ビルドが失敗することです。 壊し方1の状態で試します。
> tsc -b && vite build
src/App.tsx:12:9 - error TS2739: Type '{ ... }' is missing the following properties from type 'Props': highlighted
Found 1 error.
echo $? で終了コードを見ると、0 ではありません。
exit=2
終了コードが 0 以外なら、CI はそこで止まります。人が見落としても、機械は見落としません。
これが型の一番の価値です。 赤線は「見てもいい情報」ですが、npm run build の失敗は「通さない壁」です。 壁になっていないなら、型は無いのとほぼ同じだと思ってください。人は疲れているとき、赤線を見ません。
vite build に一度も到達していないことも確認してください。tsc -b で止まっているので、dist/ は作られていません。壊れたコードが dist/ に入らない、という順番になっています。
3つとも元に戻して、npx tsc -p tsconfig.app.json --noEmit が無言で終わることを確かめます。
型OK
⑤ useState / useReducer / useRef の型
フックの型は、ほとんどの場合、書かなくていいです。
const [count, setCount] = useState(0);
これで count は number に決まります(型推論)。setCount('x') はエラーになります。書かなくていいものを書くのは、ただの重さです。
書かないといけないのは、最初の値だけでは決まらないとき
const [user, setUser] = useState<User | null>(null);
null だけを見せられても、TypeScript には「あとで User が入る」ことが分かりません。 だから <User | null> と教えます。
そしてこの瞬間に、義務が生まれます。
return <p>{user.name}</p>;
error TS18047: 'user' is possibly 'null'.
使うたびに、null かどうかを分ける必要があります。
if (user === null) return <p>読み込み中</p>;
return <p>{user.name}</p>;
面倒に感じたら、思い出してください。 ①で真っ白になったのは、まさにこの分岐が無かったからです。面倒なのではなく、必要な分岐を今まで書いていなかっただけです。
userが null のときに何を出すかは、画面設計の話です。 読み込み中・エラー・空・データあり、の4つを分ける必要があります。型は「分けろ」とは言いますが、「何を出すか」は決めてくれません。
useReducer
useReducer は、アクションの型を書くと一気に強くなります。
type State = { count: number; step: number };
type Action =
| { type: 'inc' }
| { type: 'dec' }
| { type: 'setStep'; step: number };
function reducer(state: State, action: Action): State {
switch (action.type) {
case 'inc':
return { ...state, count: state.count + state.step };
case 'dec':
return { ...state, count: state.count - state.step };
case 'setStep':
return { ...state, step: action.step };
}
}
Action は「3つのうちどれか」という型です。 | で並べたこの形を判別可能なユニオンと呼びます。
ここが気持ちいいところです。 case 'setStep': の中でだけ action.step が使えます。case 'inc': の中で action.step と書くと、
error TS2339: Property 'step' does not exist on type '{ type: "inc"; }'.
action.type を見た分岐だけで、中身の形が自動的に絞られます。
そして dispatch({ type: 'increment' }) のような存在しないアクション名は、その場で止まります。文字列のタイポで無言で何も起きない、という useReducer の一番多い事故が消えます。
useStateとuseReducerのどちらを選ぶかは、型とは別の話です。状態が3つ以上あって、しかも互いに関係しているならuseReducerが目安です。
useRef と .current が null になる理由
import { useRef, useEffect } from 'react';
export function SearchBox() {
const inputRef = useRef<HTMLInputElement>(null);
useEffect(() => {
inputRef.current?.focus();
}, []);
return <input ref={inputRef} type="search" />;
}
inputRef.current の型は HTMLInputElement | null です。 なぜ null が混ざるのか。
JSX を書いた時点では、DOM はまだ存在しないからです。React が実際に DOM を作って ref に入れるのは、描画が終わったあとです。「まだ入っていない一瞬」が必ずあるので、型がそれを反映しています。
だから ?.(オプショナルチェーン)が要ります。inputRef.current.focus() と書くと止まります。
error TS18047: 'inputRef.current' is possibly 'null'.
<HTMLInputElement> の部分は、要素の種類ごとに変わります。 <input> なら HTMLInputElement、<div> なら HTMLDivElement、<button> なら HTMLButtonElement。
これは暗記するものではありません。 調べ方は次の節に書きます。
useRefそのものの使いどころ(値の保管 vs DOM 参照)はuseRefの深掘りにあります。
⑥ イベントとフォーム — 暗記せずに調べる
フォームの onChange に型を書こうとして、最初に固まる場所です。
import { useState } from 'react';
export function NameForm() {
const [name, setName] = useState('');
function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
setName(e.target.value);
}
function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
e.preventDefault();
console.log('submit', name);
}
return (
<form onSubmit={handleSubmit}>
<input value={name} onChange={handleChange} />
<button type="submit">送信</button>
</form>
);
}
React.ChangeEvent<HTMLInputElement> を、どうやって知るのか。 答えは「知らなくていい」です。
調べ方1:先にインラインで書いて、型を教えてもらう
関数を切り出す前に、その場に書きます。
<input value={name} onChange={(e) => setName(e.target.value)} />
この e には、型を書く必要がありません。 onChange が何を渡すかを React 側が知っているので、TypeScript が自動で決めてくれます(文脈による型付け)。
そのうえで、VS Code で e にマウスを乗せます。
(parameter) e: React.ChangeEvent<HTMLInputElement>
答えが出ます。 これをコピーして、切り出した関数に貼るだけです。
順番が逆なのが大事です。 「型を思い出してから書く」のではなく、「書いてから、型を読む」。
調べ方2:定義そのものを開く
VS Code で ChangeEvent の上にカーソルを置き、F12(定義へ移動)を押すと、node_modules/@types/react/index.d.ts が開きます。
README.md canary.d.ts index.d.ts jsx-runtime.d.ts package.json ...
index.d.ts が、React の型がすべて書いてあるファイルです。 中を検索できます。
interface ChangeEvent<T = Element> extends SyntheticEvent<T> {
@types/react は React 本体ではありません。 React は JavaScript で書かれているので、「React の関数がどんな形か」を後から書き足した別パッケージです。package.json の devDependencies に入っています。
よく使うものだけ、参考までに並べます。覚えなくていいです。
| 場面 | 型 |
|---|---|
<input> の入力 | React.ChangeEvent<HTMLInputElement> |
<textarea> の入力 | React.ChangeEvent<HTMLTextAreaElement> |
<select> の選択 | React.ChangeEvent<HTMLSelectElement> |
| フォームの送信 | React.FormEvent<HTMLFormElement> |
| ボタンのクリック | React.MouseEvent<HTMLButtonElement> |
| キー入力 | React.KeyboardEvent<HTMLInputElement> |
| 子要素を受け取る props | React.ReactNode |
<HTMLInputElement> の部分を間違えると、e.target.value が使えなくなります。 HTMLElement には value が無いからです。エラーの文面が「value が存在しない」なら、まずここを疑います。
フォームの再描画(1文字打つごとに全部描き直される問題)は、型とは別の話です。型を付けても再描画の回数は1回も変わりません。
⑦ any を書くと、その先の検査が全部消える
ここが一番伝えたいところです。
型を書いていると、必ず「どう書けばいいか分からない」場所に当たります。そこで手が止まる。そして any と書きます。私も書きました。
何が起きるかを、実際に見ます。
src/Danger.tsx を作ります。
type User = {
id: number;
name: string;
email: string;
};
export function Danger() {
const user: User = { id: 1, name: '田中', email: 'a@example.com' };
console.log(user.nmae);
console.log(user.name.toUpperCase());
console.log(user.id.trim());
return <div>{user.name}</div>;
}
3行とも間違っています。 nmae はタイポ、user.id は number なので .trim() は無い。
src/Danger.tsx:10:20 - error TS2551: Property 'nmae' does not exist on type 'User'. Did you mean 'name'?
src/Danger.tsx:12:23 - error TS2339: Property 'trim' does not exist on type 'number'.
Found 2 errors in the same file, starting at src/Danger.tsx:10
2つ捕まりました。 期待どおりです。
ここで、1文字だけ変えます。 User を any に。
const user: any = { id: 1, name: '田中', email: 'a@example.com' };
型OK
エラーが、ゼロになりました。
コードは一切直していません。 user.nmae はいまも undefined を返し、user.id.trim() はいまも実行時に落ちます。検査だけが消えました。
しかも、消えるのは1行ではありません。
const user: any = { ... };
const name = user.name; // name も any
const first = name.charAt(0); // first も any
const n: number = first; // ⚠️ 通ってしまう
any は伝染します。 any から取り出したものは any です。1箇所書くと、そこから流れ出した値の全部で検査が止まります。
| 書き方 | 意味 |
|---|---|
any | 「以後、この値については何も見なくていい」という指示 |
unknown | 「何が入っているか分からない。調べるまで何もさせない」 |
「まだ型が決まっていない」つもりで any を書くと、「もう見なくていい」と伝わります。 ここが取り違えやすい。
代わりに使うもの:unknown と絞り込み
function show(value: unknown) {
// console.log(value.length); // ← エラー: 'value' is of type 'unknown'
if (typeof value === 'string') {
console.log(value.length); // ここでは string だと分かっている
}
}
unknown は、確かめるまで何もさせません。 そして typeof で確かめると、そのブロックの中だけ型が狭くなります。
unknown は「面倒な any」ではありません。 面倒なのは、確かめる作業を今までサボっていたからです。
そして本題:外から来たデータは、型を書いても守られない
ここが、この記事の一番の急所です。
type User = { id: number; name: string; email: string };
async function load(): Promise<User[]> {
const res = await fetch('/api/users');
return res.json();
}
tsc は無言で通ります。 そして何も守られていません。
res.json() の戻り値は Promise<any> です。any なので、User[] として受け取る宣言がそのまま通ります。
私はここを「型を書いたから安全」だと思い込んでいました。 書いたのは「こう来るはずだ」という願望であって、サーバーがそのとおり返す保証はどこにもありません。
型は実行時に消えます。 ビルドされた dist/ の中に User という文字は1つも残っていません。だから、実行時に見張るものが別に要ります。
zod で、実行時に検証する
src/schema.ts を作ります。
import { z } from 'zod';
export const UserSchema = z.object({
id: z.number(),
name: z.string(),
email: z.email(),
age: z.number().optional(),
});
export const UserListSchema = z.array(UserSchema);
export type User = z.infer<typeof UserSchema>;
最後の行が肝です。 z.infer は、スキーマから型を作り出します。 つまり型を2回書きません。 スキーマ1つで、検査用の型と、実行時の検証の両方が手に入ります。
使います。
import { UserListSchema, type User } from './schema';
export async function loadUsers(): Promise<User[]> {
const res = await fetch('/api/users');
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const raw: unknown = await res.json();
const parsed = UserListSchema.safeParse(raw);
if (!parsed.success) {
console.error('APIの形が想定と違います', parsed.error.issues);
throw new Error('サーバーの応答が想定と違います');
}
return parsed.data;
}
読み方。
| 行 | 意味 |
|---|---|
const raw: unknown | 来たものを「分からないもの」として受ける。ここが出発点 |
safeParse(raw) | 例外を投げず、成否をオブジェクトで返す。parse は投げる |
parsed.success の分岐 | ここを通ったあとだけ parsed.data が User[] になる |
throw new Error(...) | 壊れたデータを、画面に渡さない |
①のケースを、これで止められるか試します。 3件目に name が無いデータを、わざと通してみます。
const broken = [
{ id: 1, name: '田中', email: 'a@example.com' },
{ id: 3, email: 'c@example.com' },
];
console.log(UserListSchema.safeParse(broken).success);
false
画面に届く前に false になりました。 どこがどう違うかも出ます。
console.log(UserListSchema.safeParse(broken).error?.issues);
[
{
expected: 'string',
code: 'invalid_type',
path: [ 1, 'name' ],
message: 'Invalid input: expected string, received undefined'
}
]
path: [ 1, 'name' ]。 「2件目の name が無い」と、場所つきで言っています。
[スクリーンショット: 03_zodが壊れたデータを止める.png] — safeParse の結果と path が写るように撮ります。
境界(外部から来る場所)だけ検証すれば十分です。 全部の関数で検証すると、遅いだけです。検証するのは、fetch の結果・localStorage から読んだ値・URLのクエリ文字列・フォームの入力の4つが中心です。
データ取得のコードが膨らむ問題そのものはデータ取得の深掘りにあります。検証はそこに1箇所だけ置くのが楽です。
⑧ どこまでやるか — strict と、やめる線
strict: true から始める
tsconfig.app.json を見ます。
"strict": true,
Vite のテンプレートは、最初から true になっています。触らないでください。
strict は、複数の設定をまとめて入れるスイッチです。 中でも効くのはこれです。
| 設定 | やること |
|---|---|
strictNullChecks | null と undefined を、他の型と混ぜられなくする。⑤の「使うたびの絞り込み」はこれのおかげ |
noImplicitAny | 型が書かれておらず推論もできない場所を、暗黙の any にせずエラーにする |
strictFunctionTypes | 関数の引数の型を厳しく見る |
strictNullChecks を切ると、この記事でやったことの大半が無意味になります。 ①の undefined is not a function は、まさに null 系のエラーだからです。
そして、順番が大事です。
| やり方 | 結果 |
|---|---|
最初から strict: true | ✅ 書くたびに1〜2個直す。1回あたり数分 |
緩く始めて、あとから strict: true | ある日 tsc が800行のエラーを吐く。そして戻す |
私は後者をやって、戻しました。 そして二度と厳しくしませんでした。「あとで厳しくする」は、実際にはほぼ起きません。
型パズルに時間を溶かさない
型は、書けば書くほど良いものではありません。 私が時間を溶かした場所を並べます。
| 溶かした場所 | いまどうするか |
|---|---|
| 汎用のコンポーネントに完璧なジェネリクスを付けようとした | 使う型を具体的に2つ書く。3つ目が出てから共通化を考える |
as const と条件型で、文字列の組み合わせを型で表そうとした | 無理なら普通の string にして、実行時に zod で見る |
ライブラリの型が合わず、.d.ts を自分で書き始めた | as で1行だけ黙らせ、コメントで理由を書く。ライブラリの型は自分の問題ではない |
判断基準を1つに決めました。
その型を書くのに15分かかったら、やめる。 代わりに
unknownで受けて、実行時に検証する。
理由は、型は実行時に何もしないからです。 完璧な型より、壊れたデータをその場で止める1行の検証のほうが、事故を防ぎます。
1人開発でも効くのは、リファクタのとき
正直に書きます。新しくコードを書いている間、型はそれほどありがたくありません。 自分が書いたばかりなので、形は覚えているからです。
効くのは、変えるときです。
// email を、必須から任意に変えたい
type User = {
id: number;
name: string;
email?: string;
};
? を1文字足して、検査します。
src/UserCard.tsx:20:29 - error TS18048: 'user.email' is possibly 'undefined'.
src/UserList.tsx:14:41 - error TS18048: 'user.email' is possibly 'undefined'.
src/schema.ts:22:10 - error TS2739: ...
Found 3 errors in 3 files.
「直す必要がある場所」の一覧が、3秒で出ます。
JavaScript でこれをやるには、grep で email を全部探して、目で追うしかありません。 そして必ず1つ見落とします。見落としたものは、本番で見つかります。
型を書くのは、未来の自分に「直すべき場所の一覧」を出せるようにするためです。 1人でも、3ヶ月後の自分は他人です。
最後に、全部通ることを確かめます。
> tsc -b && vite build
vite v5.x.x building for production...
✓ 34 modules transformed.
dist/index.html 0.46 kB
dist/assets/index-xxxxxxxx.css 1.39 kB
dist/assets/index-xxxxxxxx.js 145.21 kB
✓ built in 1.02s
ビルド成功
dist/ の中を見てください。
0
型は、1バイトも残っていません。 ここまでやったことは全部、ビルドが終わるまでの間だけ存在する見張りです。
つまずいたところ
1. npm run dev が通るので、型が合っていると思い込んだ ②のとおり、dev サーバーは型を見ていません。私は3日間、型エラーを1つも見ないまま書き進め、最初の npm run build で40個出しました。 いまは npx tsc -p tsconfig.app.json --noEmit --watch を別のタブで常に走らせています。
2. .ts に JSX を書いて、意味不明なエラーが出た
error TS1005: '>' expected.
構文エラーに見えますが、構文は正しいです。 .ts は JSX を解釈しません。.tsx にリネームしたら消えました。「型を足しただけで壊れた」と思ったら拡張子を見ます。
3. React.FC を使っていて、children を渡せてしまった 渡した側は何も言われず、受け取り側は何も表示しない。「渡したのに出ない」を1時間探しました。 素の関数宣言に変えたら、渡した瞬間にエラーになりました。③のとおりです。
4. useRef<HTMLInputElement>(null) の .current を、毎回 ! で黙らせていた
inputRef.current!.focus();
! は「null じゃないと断言する」記号で、any と同じく検査を切ります。 一度これが原因で落ちました。?. に統一したら、落ちなくなりました。 断言ではなく分岐を書くのが正解です。
5. fetch の結果に型を書いて、安心していた ⑦のとおり、res.json() は any なので、何を書いても通ります。 サーバー側が email を null で返すようになった日に、画面が落ちました。 型は何も言いませんでした。zod を入れてから、同じ変更がその日のうちにコンソールに出るようになりました。
6. any を「TODO」のつもりで置いて、忘れた grep -rn ": any" src/ で数えたら、11箇所ありました。そのうち4箇所は、実際にバグを隠していました。 いまは ESLint で any に警告を出しています(ESLintの回)。
7. ジェネリクスの汎用テーブルコンポーネントに、2日溶かした 型が正しく通った瞬間は気持ちよかったのですが、そのテーブルを使ったのは2箇所だけでした。⑧の「15分ルール」はこれで決めました。
8. strict を切ってから、戻せなくなった strictNullChecks: false にした状態で1ヶ月書き、戻したら800行のエラーが出ました。結局そのプロジェクトでは最後まで切ったままでした。 ⑧のとおり、最初から true です。
後片づけ
開発サーバーを止めます。
--watch を走らせていたタブがあれば、そちらも止めます。
ポートが残っていないか確かめます。
何も出なければ大丈夫です。 出たら、そのプロセスを止めます。
この記事で作ったものを、まるごと消します。
rm -rf は戻せません。 打つ前に、~/tslab 以外を指していないか必ず読み返してください。ここまでの深掘りで作った ~/reactlab/ や、本線の ~/react-demo/ には触っていません。残っていることを ls ~ で確認します。
rmにゴミ箱はありません。 消えたら戻りません。
ファイアウォールで 5188番を開けていた場合は、閉じます。
まとめ — 理解できたこと
- 型検査(
tsc)と、ブラウザ用への変換は別の仕事である。Vite は速さのために変換だけをやり、検査を捨てている。だからnpm run devは型が間違っていても普通に起動する npx tsc -p tsconfig.app.json --noEmitが「検査だけ」のコマンド。開発中はこれを--watchで別タブに常駐させるのが実際に効いた- 本当の価値は、エディタの赤い波線ではなく
npm run buildが止まること。赤線は疲れていると見ない。壁になっていない型は、無いのとほぼ同じ buildがtsc -b && vite buildの2段なのは意味がある。型エラーがあるとvite buildに到達せず、壊れたコードはdist/に入らない- props の型は
type Props = {...}と素の関数宣言で書く。React.FCは使わない。childrenが意図せず入り、ジェネリクスが素直に書けないため - フックの型は、ほとんど書かなくていい。
useState(0)は推論で決まる。書くのはuseState<User | null>(null)のように、最初の値だけでは決まらないとき nullを型に混ぜた瞬間、使うたびの絞り込みが義務になる。これは面倒なのではなく、今まで必要な分岐を書いていなかったということuseRefの.currentが null になりうるのは、JSX を書いた時点で DOM がまだ無いから。!で断言せず?.で分岐する- イベントの型は暗記しない。先にインラインで書いて
eにホバーし、出てきた型をコピーする。定義そのものは@types/reactのindex.d.tsにある anyは「まだ決めていない」ではなく「以後、何も見なくていい」という指示。1箇所書くとそこから流れ出した値の検査が全部消え、タイポも型違いも黙って通る- 代わりに
unknownで受けて、typeofなどで絞り込む。確かめるまで何もさせないのがunknown res.json()はanyなので、fetchの結果にどんな型を書いても何も守られない。型は実行時に消えるので、zodのような実行時の検証が別に要る- 検証するのは境界だけでいい。
fetchの結果・localStorage・URLのクエリ・フォーム入力の4つ。z.inferを使えば型を二重に書かずに済む strict: trueは最初から入れておく。あとから厳しくするのは、ほぼ実現しない(800行のエラーを見た人は戻す)- 型パズルは15分でやめる。完璧な型より、壊れたデータをその場で止める1行の検証のほうが事故を防ぐ
- 1人開発で型が本当に効くのはリファクタのとき。
?を1文字足すだけで「直すべき場所の一覧」が3秒で出る。3ヶ月後の自分は他人
参考リンク
- roadmap.sh — React — TypeScript の項目がどの位置に置かれているか
- roadmap.sh — TypeScript — 型そのものを深く追うときの地図
- TypeScript 公式 — The TypeScript Handbook — 型の一次情報
- TypeScript 公式 — Everyday Types —
anyとunknownの違いはここに - TypeScript 公式 — Narrowing — ⑤と⑦でやった絞り込みの仕様
- TypeScript 公式 — tsconfig の strict — ⑧でまとめた設定の一覧
- React 公式 — Using TypeScript — props とフックの型の、React 側の一次情報
- React 公式 — useRef —
.currentが null になりうる理由 - Vite 公式 — Getting Started —
npm create vite@latestのテンプレート一覧 - MDN — HTMLInputElement — ⑤で使った要素の型の実体
- Zod 公式ドキュメント —
safeParseとz.inferの使い方
次に読む
この記事は 【深掘り】React の 19 / 24 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | Reactのテスト — 実装を直すたびに落ちる |
| → 次の記事 | Reactのルーティング — リロードで最初の画面に戻る |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- props と state に型を付ける
- any を1つ書くと型検査が消える
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント