TypeScript "TS2580: Cannot find name 'process'" - Fix Node Types

By Daniel Zoghalchali·Latchkey

tsc does not know about Node globals like process, require, __dirname, or Buffer unless the Node type definitions are installed and included. TS2580 specifically suggests installing @types/node.

What this error means

Type-checking fails with error TS2580: Cannot find name 'process'. Do you need to install type definitions for node? (or the same for require, __dirname, Buffer, global).

tsc output

src/config.ts:1:13 - error TS2580: Cannot find name 'process'. Do you need to
install type definitions for node? Try `npm i --save-dev @types/node`.

1 const url = process.env.API_URL
              ~~~~~~~

Diagnose it: which tsconfig and which compiler?

A TypeScript error that appears only in CI usually means the runner is compiling with a different config or a different compiler version than your editor. Your editor uses the workspace TypeScript and the nearest tsconfig.json; CI uses whatever the lockfile resolved and whatever config the build script names.

Terminal

# what CI will actually use
npx tsc --version
npx tsc --showConfig | head -40

# which files are in the program (a missing include is a common cause)
npx tsc --listFiles | wc -l

# type-check only, no emit, same as most CI gates
npx tsc --noEmit

Common causes

@types/node not installed

The Node global type declarations are missing, so tsc has no definition for process, Buffer, require, etc. Common in front-end projects that nonetheless touch Node globals in build scripts.

Node types installed but excluded

A compilerOptions.types allowlist that omits node, or a lib/typeRoots setting that excludes it, hides the installed declarations from this compilation.

How to fix it

Install @types/node

Terminal

npm install -D @types/node

Ensure node types are included

If you pin types, list node; otherwise tsc auto-includes installed @types.

tsconfig.json

// tsconfig.json
{
  "compilerOptions": {
    "types": ["node", "vite/client"]
  }
}

Pin the compiler so unrelated updates cannot break the gate

TypeScript adds errors in minor releases. An unpinned compiler turns a routine dependency update into a red build on code nobody touched, which is the most common false alarm in a TypeScript CI pipeline.

package.json

// package.json
{
  "devDependencies": {
    "typescript": "5.6.3"   // exact, not ^5.6.3
  }
}

How to prevent it

Add @types/node wherever build scripts or config touch Node globals.
Avoid an over-restrictive compilerOptions.types allowlist.
Type-check with tsc --noEmit in CI to catch missing globals.

Frequently asked questions

What causes TypeScript "TS2580: cannot find name 'process'"?

There are 2 common causes: @types/node not installed and node types installed but excluded. The Node global type declarations are missing, so tsc has no definition for process, Buffer, require, etc.

How do I fix TypeScript "TS2580: cannot find name 'process'"?

There are 2 fixes depending on which cause you have: install @types/node and ensure node types are included. Work through them in order, since the first is the most common.

What does TypeScript "TS2580: cannot find name 'process'" actually mean?

Type-checking fails with error TS2580: Cannot find name 'process'.

How do I stop TypeScript "TS2580: cannot find name 'process'" happening again?

Add @types/node wherever build scripts or config touch Node globals. The prevention section lists 3 changes that keep it from recurring.