【TypeScript】TS2304の原因と解決方法｜Cannot find nameを完全解説

この記事で学べること

• TS2304エラーメッセージの読み方と意味
• 変数名のタイポ・宣言前の参照・スコープ外アクセスなど基本パターン
• import / export 関連の TS2304（named import・default import・循環参照・パスエイリアス）
• 型定義ファイル（.d.ts）関連の TS2304（@types・declare global・typeRoots）
• DOM API での TS2304（document / window / HTMLElement）
• Node.js 固有の TS2304（process / __dirname / Buffer / require）
• テストフレームワークでの TS2304（Jest / Vitest の describe / it / expect）
• React / JSX での TS2304（React・useState・カスタムコンポーネント）
• グローバル変数・環境変数での TS2304（window.XXX・process.env）
• tsconfig.json の設定で解決する TS2304（lib・types・include・paths）
• 実務でよくあるTS2304パターン10選

前提知識：この記事はTypeScriptの基本的な構文を理解している方を対象としています。型の基本から学びたい方は【TypeScript】型の書き方 完全入門を先にお読みください。

error TS2304: Cannot find name ‘X’.

src/index.ts:5:1 - error TS2304: Cannot find name 'myVariable'.

5   console.log(myVariable);
                ~~~~~~~~~~

覚え方：「Cannot find name ‘あなたが使おうとした名前‘」— TypeScriptは「その名前、どこにも見つかりません」と言っています。宣言・import・型定義のどれかが不足している可能性が高いです。

注意：TS2552 は TS2304 の「親切版」です。TypeScript がタイポを検出できた場合は TS2552 になり、修正候補を提示してくれます。修正候補がない場合に TS2304 が出ます。

error TS2304: Cannot find name ‘consle’.

// 変数名のタイポ
const userName = "田中";
console.log(userNmae);  // TS2304: Cannot find name 'userNmae'

// グローバルオブジェクトのタイポ
consle.log("Hello");  // TS2304: Cannot find name 'consle'

// 関数名のタイポ
function calculateTotal(prices: number[]) {
  return prices.reduce((sum, p) => sum + p, 0);
}
const total = calulateTotal([100, 200]);  // TS2304: Cannot find name 'calulateTotal'

// 正しい変数名を使用
const userName = "田中";
console.log(userName);  // OK

// 正しいグローバルオブジェクト
console.log("Hello");  // OK

// 正しい関数名
const total = calculateTotal([100, 200]);  // OK

ポイント：VS Code などのエディタでは、タイポがあると TS2552（Did you mean ‘X’?）としてスペル候補を提示してくれることがあります。エディタの赤い波線と提案メッセージを確認しましょう。

error TS2304: Cannot find name ‘userService’.

// TypeScript のプリミティブ型は小文字
const name: String = "田中";  // 動くが非推奨（ラッパーオブジェクト型）

// クラス名と変数名の混同
class UserService {
  getUser() { return { name: "田中" }; }
}
const user = userService.getUser();  // TS2304: Cannot find name 'userService'

// プリミティブ型は小文字を使う
const name: string = "田中";  // OK

// インスタンスを作成してから使用
const userService = new UserService();
const user = userService.getUser();  // OK

error TS2304: Cannot find name ‘message’.

// 宣言前に参照している
console.log(message);  // TS2304: Cannot find name 'message'
const message = "Hello, TypeScript!";

// 関数内でも同様
function greet() {
  console.log(greeting);  // TS2304: Cannot find name 'greeting'
  const greeting = "こんにちは";
}

// 宣言を参照より前に置く
const message = "Hello, TypeScript!";
console.log(message);  // OK

// 関数内でも同様
function greet() {
  const greeting = "こんにちは";
  console.log(greeting);  // OK
}

注意：var で宣言した変数はホイスティングにより宣言前でも undefined として参照できますが、const / let ではTDZにより参照できません。モダンなTypeScriptでは var の使用は避けるべきです。

error TS2304: Cannot find name formatDate.

// import を忘れている！
// import { formatDate } from ./utils;

const today = formatDate(new Date());  // TS2304: Cannot find name formatDate

import { formatDate } from ./utils;

const today = formatDate(new Date());  // OK

ポイント：VS Code では、未インポートの識別子にカーソルを合わせて Ctrl + .（Quick Fix）を押すと、自動でimport文を追加してくれます。積極的に活用しましょう。

error TS2304: Cannot find name result.

function fetchData(isAdmin: boolean) {
  if (isAdmin) {
    const result = "管理者データ";
  }
  console.log(result);  // TS2304: Cannot find name result
}

function fetchData(isAdmin: boolean) {
  let result = "一般データ";
  if (isAdmin) {
    result = "管理者データ";
  }
  console.log(result);  // OK
}

error TS2304: Cannot find name ”formatCurrency”.

export function formatPrice(price: number): string {
  return `¥${price.toLocaleString()}`;
}

// エクスポート名と異なる名前でインポート
import { formatCurrency } from ''./utils'';
// TS2305 or TS2304

// 正しいエクスポート名を使う
import { formatPrice } from ''./utils'';
const text = formatPrice(1000);  // OK

// 別名を付けたい場合は as を使う
import { formatPrice as formatCurrency } from ''./utils'';

// default export を named import しようとしている
import { axios } from ''axios'';  // エラー

// named export を default import しようとしている
import formatDate from ''./utils'';  // エラー

// default export は波括弧なしでインポート
import axios from ''axios'';  // OK

// named export は波括弧付きでインポート
import { formatDate } from ''./utils'';  // OK

// --- a.ts ---
import { B } from ''./b'';
export class A { getB() { return new B(); } }

// --- b.ts ---
import { A } from ''./a'';  // 循環参照！
export class B { getA() { return new A(); } }

// --- b.ts ---
import type { A } from ''./a'';  // 型のみのインポート

// tsconfig.json に paths の設定がない場合
import { UserService } from ''@/services/user'';  // モジュール解決できない

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

注意：Vite や webpack を使っている場合、ビルドツール側にも同じエイリアス設定が必要です。tsconfig.json だけでは実行時のパス解決ができません。

// moduleResolution: "node" の場合
import { foo } from ''./utils'';      // OK（拡張子なし）
import { foo } from ''./utils.ts'';   // エラー

// moduleResolution: "nodenext" の場合
import { foo } from ''./utils.js'';   // OK（.js 拡張子が必要）
import { foo } from ''./utils'';      // エラー

ポイント：moduleResolution: "nodenext" では、TypeScriptファイルでも .js 拡張子を付けてインポートします。これはTypeScriptがコンパイル後のJavaScriptファイルのパスを参照するためです。

error TS2304: Cannot find name ”$”.

// @types/jquery がインストールされていない
$(".btn").click(() => {
  // TS2304: Cannot find name ''$''
});

# npm の場合
npm install --save-dev @types/jquery

# yarn の場合
yarn add --dev @types/jquery

# pnpm の場合
pnpm add -D @types/jquery

error TS2304: Cannot find name ”APP_CONFIG”.

// グローバルに APP_CONFIG が定義されているが、TypeScript が認識できない
console.log(APP_CONFIG.apiUrl);  // TS2304: Cannot find name ''APP_CONFIG''

// src/global.d.ts
declare const APP_CONFIG: {
  apiUrl: string;
  version: string;
  debug: boolean;
};

// 型定義のないライブラリ用のモジュール宣言
declare module ''my-legacy-library'' {
  export function doSomething(input: string): void;
  export const VERSION: string;
}

// 最低限の宣言（any でエクスポート）
declare module ''untyped-lib'';

{
  "compilerOptions": {
    // typeRoots: 型定義を探すディレクトリ
    // デフォルトは ["node_modules/@types"]
    "typeRoots": [
      "./node_modules/@types",
      "./src/types"  // カスタム型定義ディレクトリ
    ],

    // types: 読み込む型パッケージを限定する
    // 指定するとそれ以外は読み込まれない！
    "types": ["node", "jest"]
  }
}

注意：types を指定すると、指定したパッケージのみが自動読み込みされます。例えば "types": ["node"] と設定すると、@types/jest がインストールされていても読み込まれません。

// グローバル変数の宣言
declare const gtag: Function;
declare const __DEV__: boolean;

// グローバル関数の宣言
declare function sendAnalytics(event: string, data: Record<string, unknown>): void;

// グローバルな Window インターフェースの拡張
declare global {
  interface Window {
    myApp: {
      version: string;
      init(): void;
    };
  }
}

// export {} が必要（ファイルをモジュールとして扱うため）
export {};

ポイント：declare global を使うファイルには、export {} を追加してモジュールとして認識させる必要があります。これがないと、ファイル全体がグローバルスクリプトとして扱われ、意図しない動作になる場合があります。

error TS2304: Cannot find name ”document”.

{
  "compilerOptions": {
    "lib": ["ES2020"]  // DOM が含まれていない！
  }
}

{
  "compilerOptions": {
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  }
}

error TS2304: Cannot find name ”HTMLInputElement”.

// lib に DOM がない場合
const input = document.querySelector("input") as HTMLInputElement;
// TS2304: Cannot find name ''HTMLInputElement''

function handleClick(e: MouseEvent) {
// TS2304: Cannot find name ''MouseEvent''
  console.log(e.clientX);
}

注意：Node.js環境の tsconfig.json では lib に "DOM" を入れるべきではありません。DOM APIが使えてしまうと、サーバーサイドで実行時エラーになります。SSRやテスト環境でDOMが必要な場合は jsdom などのライブラリを使いましょう。

error TS2304: Cannot find name ”process”.

// @types/node がインストールされていない
const port = process.env.PORT;  // TS2304: Cannot find name ''process''
const dir = __dirname;  // TS2304: Cannot find name ''__dirname''
const buf = Buffer.from("hello");  // TS2304: Cannot find name ''Buffer''

# @types/node をインストール
npm install --save-dev @types/node

error TS2304: Cannot find name ”__dirname”.

// ES Modules では __dirname は使えない
const configPath = __dirname + "/config.json";  // TS2304

import { fileURLToPath } from ''node:url'';
import { dirname, join } from ''node:path'';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const configPath = join(__dirname, "config.json");  // OK

declare global {
  var db: DatabaseConnection;
  var logger: Logger;
}

export {};

// 型定義があるので TS2304 にならない
globalThis.db.query("SELECT * FROM users");
globalThis.logger.info("Server started");

注意：declare global 内で var を使う理由は、const や let はグローバルスコープに変数を追加できないためです。これは TypeScript の仕様です。

error TS2304: Cannot find name ”describe”.

// @types/jest がインストールされていない
describe("sum", () => {  // TS2304: Cannot find name ''describe''
  it("1 + 2 = 3", () => {  // TS2304: Cannot find name ''it''
    expect(sum(1, 2)).toBe(3);  // TS2304: Cannot find name ''expect''
  });
});

# 1. @types/jest をインストール
npm install --save-dev @types/jest

# 2. tsconfig.json の types に jest を追加
# もしくは tsconfig.json で types を指定していなければ自動で読み込まれる

{
  "compilerOptions": {
    "types": ["jest", "node"]
  },
  "include": ["src/**/*", "tests/**/*"]  // テストファイルも含める
}

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

// vitest.config.ts
import { defineConfig } from ''vitest/config'';

export default defineConfig({
  test: {
    globals: true,  // describe, it, expect をグローバルに
  },
});

ポイント：Vitest では globals: true を設定しなくても、各テストファイルで import { describe, it, expect } from ''vitest'' と明示的にインポートする方法もあります。この方法なら型設定の問題を完全に回避できます。

{
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "tests/**/*.ts",      // テストディレクトリを追加
    "**/*.test.ts",       // テストファイルパターン
    "**/*.spec.ts"        // specファイルパターン
  ]
}

error TS2304: Cannot find name ”React”.

// import React がない + jsx: "react" の場合
const App = () => {
  return <div>Hello</div>;  // TS2304: Cannot find name ''React''
};

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx"  // React 17+ の新しい JSX Transform
  }
}

import React from ''react'';  // 明示的にインポート

const App = () => {
  return <div>Hello</div>;  // OK
};

// 小文字で始まるコンポーネント名
const myButton = () => <button>Click</button>;

// JSXで使うと HTML 要素として解釈される
const App = () => <myButton />;  // HTML にそんな要素はない

// 大文字で始めるのが React のルール
const MyButton = () => <button>Click</button>;

const App = () => <MyButton />;  // OK

error TS2304: Cannot find name ”useState”.

// import を忘れている
const Counter = () => {
  const [count, setCount] = useState(0);  // TS2304: Cannot find name ''useState''

  useEffect(() => {  // TS2304: Cannot find name ''useEffect''
    document.title = `Count: ${count}`;
  }, [count]);

  return <button onClick={() => setCount(count + 1)}>{count}</button>;
};

import { useState, useEffect } from ''react'';

const Counter = () => {
  const [count, setCount] = useState(0);  // OK
  useEffect(() => {  // OK
    document.title = `Count: ${count}`;
  }, [count]);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
};

error TS2304: Cannot find name ”gtag”.

// Google Analytics の gtag をそのまま使おうとしている
gtag("event", "click", {
  event_category: "button",
});  // TS2304: Cannot find name ''gtag''

// Google Analytics の型定義
declare function gtag(
  command: "config" | "event" | "set",
  targetId: string,
  config?: Record<string, unknown>
): void;

// Window にカスタムプロパティを追加
declare global {
  interface Window {
    dataLayer: Record<string, unknown>[];
  }
}
export {};

declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production" | "test";
    PORT?: string;
    DATABASE_URL: string;
    API_KEY: string;
  }
}

error TS2304: Cannot find name ”ImportMetaEnv”.

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_TITLE: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

ポイント：Viteの環境変数は VITE_ プレフィックスが付いたものだけがクライアントサイドに公開されます。VITE_ のない環境変数はサーバーサイドのみで利用可能です。

{
  "include": ["src/**/*.ts"],  // .tsx が含まれていない！
  "exclude": ["**/*.test.ts"]  // テストファイルが除外されている
}

{
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "tests/**/*.ts",
    "src/types/**/*.d.ts"
  ]
}

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@types/*": ["src/types/*"]
    }
  }
}

注意：paths は TypeScript コンパイラの型解決にのみ影響します。実行時のモジュール解決には影響しません。Vite なら resolve.alias、webpack なら resolve.alias で同じパスマッピングを設定する必要があります。

tsconfig.json チェックリスト

• lib に必要なライブラリ（DOM, ES2020 等）が含まれているか？
• types を指定している場合、必要な型パッケージが全て列挙されているか？
• typeRoots にカスタム型定義ディレクトリが含まれているか？
• include にソースファイルとテストファイルが含まれているか？
• exclude で必要なファイルを除外していないか？
• moduleResolution がプロジェクトの実行環境に合っているか？
• baseUrl / paths がビルドツール側の設定と一致しているか？

# Express
npm install --save-dev @types/express

# Lodash
npm install --save-dev @types/lodash

# cors
npm install --save-dev @types/cors

// jQuery
declare const $: any;
declare const jQuery: any;

// Google Analytics
declare function gtag(...args: any[]): void;

// packages/app/tsconfig.json
{
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "../shared" }
  ]
}

// NG: const enum は isolatedModules でインライン化できない
export const enum Direction { Up, Down, Left, Right }

// OK: 通常の enum を使う
export enum Direction { Up, Down, Left, Right }

// さらに良い: as const オブジェクトを使う
export const Direction = {
  Up: 0,
  Down: 1,
  Left: 2,
  Right: 3,
} as const;
type Direction = (typeof Direction)[keyof typeof Direction];

TS2304 の解決フローチャート

• 1. タイポ・スペルミスはないか？ → エディタの補完機能を活用
• 2. import 文を書き忘れていないか？ → VS Code の Quick Fix (Ctrl + .)
• 3. @types パッケージはインストールされているか？ → npm install -D @types/xxx
• 4. tsconfig.json の lib は正しいか？ → DOM / ES2020 等を確認
• 5. tsconfig.json の types は正しいか？ → 指定している場合、全ての型を列挙
• 6. tsconfig.json の include にファイルが含まれているか？ → .tsx やテストファイルも含める
• 7. declare 文やカスタム型定義ファイルが必要か？ → .d.ts を作成

TypeScript 関連記事

• 【TypeScript】型の書き方 完全入門 – 基本型から応用型まで体系的に学ぶ
• 【TypeScript】よくあるエラーと解決方法 – 主要エラーコードの一覧と解決策
• 【TypeScript】tsconfig.json 完全ガイド – 全オプションの解説と推奨設定
• 【TypeScript】TS2322の原因と解決方法 – Type is not assignable to type の完全解説
• 【TypeScript】TS2339の原因と解決方法 – Property does not exist on type の完全解説
• 【TypeScript】TS2345の原因と解決方法 – Argument is not assignable の完全解説
• 【TypeScript】TS7006の原因と解決方法 – Parameter implicitly has an any type の完全解説