Fix: TypeScript error TS2304: Cannot find name 'x'

The Error

You compile TypeScript and get:

error TS2304: Cannot find name 'document'.

Or variations:

error TS2304: Cannot find name 'console'.

error TS2304: Cannot find name 'process'.

error TS2304: Cannot find name 'describe'.

error TS2304: Cannot find name 'React'.

error TS2304: Cannot find name 'Buffer'.

TypeScript does not recognize the identifier you used. It is not imported, not declared in any type definition file, or not included in your tsconfig.json configuration.

Why This Happens

TypeScript needs type declarations for every name you use. Built-in browser APIs (document, window, fetch) come from the dom library. Node.js APIs (process, Buffer, __dirname) come from @types/node. Testing APIs (describe, it, expect) come from @types/jest or @types/mocha.

If the required type declarations are not included, TypeScript reports Cannot find name.

Common causes:

• Missing lib in tsconfig.json. The dom or es2020 libraries are not included.
• Missing @types packages. @types/node, @types/react, @types/jest, etc. are not installed.
• Wrong tsconfig.json scope. The file is not included in the TypeScript project.
• Missing import statement. A type or value from a module is used without importing it.
• Node.js types missing. Using Node.js APIs without @types/node.

Fix 1: Add DOM Types for Browser APIs

If document, window, fetch, console, alert, localStorage, or HTMLElement are not found:

Check your tsconfig.json:

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

The DOM library provides types for all browser APIs. Without it, TypeScript does not know about document, window, fetch, etc.

If no lib is specified: TypeScript uses a default set based on the target. If target is ES2020, it includes ES2020 and DOM by default. But if you explicitly set lib to just ["ES2020"], DOM is excluded.

Pro Tip: When you specify lib, you must include everything you need. Setting "lib": ["ES2020"] removes the default DOM types. Always include "DOM" and "DOM.Iterable" for browser projects.

Fix 2: Install @types/node for Node.js APIs

If process, Buffer, __dirname, __filename, require, or module are not found:

npm install --save-dev @types/node

Then ensure TypeScript includes them. In tsconfig.json:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Or if you do not have a types field, TypeScript automatically includes all @types packages in node_modules/@types.

Warning: If you set "types": ["node"], TypeScript only includes @types/node and ignores other @types packages. To include everything, remove the types field entirely or list all required types:

{
  "compilerOptions": {
    "types": ["node", "jest", "react"]
  }
}

Fix 3: Install Test Framework Types

If describe, it, expect, test, beforeEach, afterAll, or jest are not found:

For Jest:

npm install --save-dev @types/jest

For Mocha + Chai:

npm install --save-dev @types/mocha @types/chai

For Vitest:

Vitest includes its own types. Add to tsconfig.json:

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

Or import in each test file:

import { describe, it, expect } from "vitest";

Fix 4: Fix React/JSX Types

If React is not found in JSX files:

npm install --save-dev @types/react @types/react-dom

For React 17+ with the new JSX transform:

In tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

With react-jsx, you do not need import React from 'react' in every file. The JSX factory is included automatically.

For older React (< 17):

{
  "compilerOptions": {
    "jsx": "react"
  }
}

And add the import in every JSX file:

import React from "react";

For more React and TypeScript issues, see Fix: React Invalid hook call.

Fix 5: Check File Inclusion in tsconfig.json

TypeScript only processes files that are included in the project. If your file is outside the include paths, types are not resolved:

{
  "compilerOptions": { ... },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

If your file is in tests/ but only src/ is included:

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

Check which files TypeScript sees:

npx tsc --listFiles

If your file is not in the list, it is not part of the project.

Fix 6: Declare Global Types

If you use global variables (e.g., injected by the environment), declare them:

Create a .d.ts file (e.g., src/global.d.ts):

declare const __DEV__: boolean;
declare const API_URL: string;

interface Window {
  gtag: (...args: any[]) => void;
  dataLayer: any[];
}

TypeScript picks up .d.ts files automatically if they are in the include path.

For environment variables with Vite:

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

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

For environment variables with Next.js:

Create env.d.ts:

declare namespace NodeJS {
  interface ProcessEnv {
    DATABASE_URL: string;
    NEXT_PUBLIC_API_URL: string;
  }
}

For environment variable issues in general, see Fix: environment variable is undefined.

Fix 7: Fix Module-Related Name Errors

If a name from a module is not found:

Missing import:

// Error: Cannot find name 'useState'
function App() {
  const [count, setCount] = useState(0);
}

// Fix: Import it
import { useState } from "react";

Default vs named import confusion:

// Module exports: export default function parse() {}
import { parse } from "./parser";  // Wrong — named import
// Error: Module has no exported member 'parse'

import parse from "./parser";  // Correct — default import

For module resolution errors, see Fix: TypeScript cannot find module.

Common Mistake: Using require() in TypeScript without @types/node. TypeScript does not know about require unless Node.js types are installed. Use import instead of require in TypeScript:

// Instead of:
const fs = require("fs");

// Use:
import fs from "fs";
import * as fs from "fs";

Fix 8: Fix Enum and Const Issues

If a name from an enum or const is not found:

// In types.ts
export enum Status {
  Active = "active",
  Inactive = "inactive",
}

// In app.ts — missing import:
const status: Status = Status.Active;
// Error: Cannot find name 'Status'

// Fix:
import { Status } from "./types";

Const enums across modules:

// const enums are inlined at compile time
export const enum Color {
  Red = 0,
  Green = 1,
  Blue = 2,
}

If you use isolatedModules: true (required by Vite, esbuild, SWC), const enums from other files do not work. Use regular enums or as const objects instead:

export const Color = {
  Red: 0,
  Green: 1,
  Blue: 2,
} as const;

type Color = (typeof Color)[keyof typeof Color];

Still Not Working?

If the error persists:

Check for TypeScript version compatibility. Some types require a minimum TypeScript version. Update TypeScript:

npm install --save-dev typescript@latest

Check for conflicting tsconfig files. If you have multiple tsconfig.json files (e.g., tsconfig.app.json, tsconfig.node.json), make sure the right one is used for your file.

Check for skipLibCheck. Setting "skipLibCheck": true skips type checking of .d.ts files. This can mask issues but also prevent valid errors in your own .d.ts files.

Check for triple-slash references. Some older type definitions require explicit references:

/// <reference types="node" />
/// <reference lib="dom" />

Run tsc directly to see all errors:

npx tsc --noEmit

This shows all TypeScript errors without generating output files.

For TypeScript type assignment errors, see Fix: TypeScript type is not assignable. For possibly undefined errors, see Fix: TypeScript Object is possibly undefined.