How to fix Cannot find name 'global' in TypeScript

TypeScriptBEGINNERMEDIUMUpdated Dec 8, 2025· 186 views

This TypeScript error occurs when the compiler cannot find type definitions for the global object. This typically happens in Node.js projects where TypeScript lacks proper type information about global Node.js variables. Installing @types/node or configuring your tsconfig.json correctly resolves this issue.

Quick fix

Fixes TS2304

npm install --save-dev @types/node
  1. Install @types/node package
  2. Update tsconfig.json to include Node types
  3. For custom global variables, declare them in a .d.ts file
  4. Use globalThis instead of global (modern approach)
typescript — error
npm install --save-dev @types/node
Cannot find name 'global'
shell
npm install --save-dev @types/node

What this error means

The "Cannot find name global" error means TypeScript doesn't have type definitions for the Node.js global object. In Node.js, the global object is a special object that contains all global variables and functions (like console, process, Buffer). TypeScript's type checker needs these definitions to understand what properties are available on the global scope. Without the proper type definitions, TypeScript treats any reference to "global" as an unknown identifier, similar to misspelling a variable name.

Typical symptoms

  • TypeScript shows error "TS2304: Cannot find name global" in IDE or during compilation
  • Code that tries to access properties on the global object fails type checking
  • Custom global variables defined in Node.js applications are not recognized
  • The JavaScript runs fine but TypeScript compilation fails
  • Problems only occur in ts-node or TypeScript-aware environments, not when running plain JavaScript

Common causes

  1. Missing or incomplete @types/node installation in the project
  2. tsconfig.json does not include Node.js type definitions in compilerOptions
  3. Using global or Node.js-specific APIs in a project with DOM/browser-only types
  4. Custom global variables defined at runtime but not declared to TypeScript
  5. Using ts-node without proper type declaration setup

How to fix "Cannot find name 'global'"

1Install @types/node package

The most common fix is to install the official Node.js type definitions:

bash
npm install --save-dev @types/node

or with yarn:

bash
yarn add --dev @types/node

This package provides TypeScript with all the type information it needs to understand Node.js global objects and functions.

2Update tsconfig.json to include Node types

Ensure your tsconfig.json includes Node.js in the type libraries. Update your compilerOptions:

json
{
  "compilerOptions": {
    "lib": ["ES2020"],
    "types": ["node"],
    "target": "ES2020",
    "module": "commonjs"
  }
}

The key is adding "types": ["node"] or ensuring "lib" includes appropriate Node.js support. If you're running both server and browser code, you might need multiple entries:

json
{
  "compilerOptions": {
    "lib": ["ES2020", "DOM"],
    "types": ["node"]
  }
}
3For custom global variables, declare them in a .d.ts file

If you're adding your own custom global variables, create a declaration file. Create a file like src/global.d.ts:

typescript
declare global {
  var myCustomGlobal: string;
  var myConfig: { apiUrl: string; timeout: number };
}

export {};

Then use it in your code:

typescript
// This will now work without TS2304 error
myCustomGlobal = "hello";
console.log(global.myConfig.apiUrl);

Important: The export {}; at the end is required to mark the file as an external module, which allows augmenting the global scope.

4Use globalThis instead of global (modern approach)

In Node.js 12+ and modern TypeScript, prefer globalThis over global. It's more portable and works across browsers and Node.js:

typescript
// Instead of:
global.myVariable = "value";

// Use:
globalThis.myVariable = "value";

globalThis is the standardized way to access global scope and doesn't require additional type declarations. If you still get an error with globalThis, install @types/node as shown in Step 1.

Advanced notes

Node.js v16+ deprecated NodeJS.Global in favor of globalThis. If you're seeing this error in an old project, upgrading @types/node to the latest version may change how types are exported. For ts-node specifically, you can also use a triple-slash reference in your declaration file: /// <reference types="node" /> at the top of files that need global declarations. When using build tools like webpack or esbuild with Node.js code, ensure your tsconfig target is set to "node" or "commonjs" rather than "web" or "es2015 module" modes. In monorepos, each package may need its own tsconfig.json with proper type configuration. If you're extending the global object with custom properties for type safety, avoid modifying it at runtime without declaring it to TypeScript first—this prevents both type errors and runtime surprises.

Frequently asked questions

What does "TS2304" mean?
js global object. js, the global object is a special object that contains all global variables and functions (like console, process, Buffer). TypeScript's type checker needs these definitions to understand what properties are available on the global scope.
How do I fix "TS2304"?
This TypeScript error occurs when the compiler cannot find type definitions for the global object. This typically happens in Node.js projects where TypeScript lacks proper type information about global Node.js variables. Installing @types/node or configuring your tsconfig.json correctly resolves this issue.
What causes "TS2304"?
Missing or incomplete @types/node installation in the project tsconfig.json does not include Node.js type definitions in compilerOptions Using global or Node.js-specific APIs in a project with DOM/browser-only types
Is the "TS2304" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading