JS with Types Start

TypeScript error

TS2580: Node.js globals without the Node.js types

  • Error TS2580
  • Tested with TypeScript 5.9

TS2580, "Cannot find name 'process'. Do you need to install type definitions for node?", is reported when code uses a Node.js global and no declaration for it is loaded. TypeScript's own libraries describe the language and the browser, not Node.js; Node's globals come from the @types/node package, which is what the message's suggested command installs.

The checker picks this message when the config has no types list. With a types list that leaves node out, the same problem is TS2591, whose message adds "and then add 'node' to the types field".

At a glance

CodeTS2580
MessageCannot find name '{0}'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.
TypeScript's categoryerror
Listed underModules and imports
Depends on types
In .js files Reported when the file is checked: checkJs in jsconfig.json, or // @ts-check at the top of the file

The message is TypeScript's own text from its diagnostic messages file (Apache-2.0); {0} is filled in by tsc for each error.

What it looks like

server.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: server.js(2,21): error TS2580: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`. 6.0.3 : differs, see why TypeScript 6.0.3, run 21 October 2026: differs from 5.9.3. server.js(2,21): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig. 7.0.2 : differs, see why TypeScript 7.0.2, run 21 October 2026: differs from 5.9.3. server.js(2,21): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig. checked 21 October 2026 
const port = Number(process.env.PORT ?? 3000);error TS2580: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.

export { port };
Node.js globals with no Node.js types installed.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "typeRoots": ["./node_modules/@types"]
  },
  "include": ["*.js"]
}

What causes it

  • @types/node is not installed in the project.
  • The config has no types list (so every installed @types package would load if it were there).

How to fix it

Install @types/node

Run npm install --save-dev @types/node, ideally the major version matching the Node.js you run. The fixed example has it available and names it in types, which is what the quick-start setups on this site do.

server.js TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
const port = Number(process.env.PORT ?? 3000);

export { port };
With @types/node installed (and named in types).
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": ["node"]
  },
  "include": ["*.js"]
}

About the example

This site's build has @types/node installed, so the failing example points typeRoots at its own empty node_modules/@types folder to stand for a project without it. In your project you would simply not have the package.

Under TypeScript 6.0 and 7.0

Every example on this page also runs under TypeScript 6.0.3 and 7.0.2 when this site is built. One of them reports something different from 5.9.3, the version the page describes; the ✗ on its badge links to its entry below.

types defaults to an empty list, so the hint names the types field

TypeScript 6.0 and 7.0 · defaults that changed in 6.0

The pattern: A global from a package that is not installed (process, describe, it) in a config that does not set types.

Why: Only the 6.0 default types: [] causes this. The name is still missing in every version, but 6.0 and 7.0 report it with the code and message for a project that lists its types (TS2591 instead of TS2580, TS2593 instead of TS2582), which add "and then add 'node' to the types field in your tsconfig". Source: TypeScript 6.0 release notes: types now defaults to an empty list.

Node.js globals with no Node.js types installed server.js

TypeScript 5.9.3
server.js(2,21): error TS2580: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node`.
TypeScript 6.0.3differs from 5.9.3
server.js(2,21): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.
TypeScript 7.0.2differs from 5.9.3
server.js(2,21): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

What works in every version: Install the types and name them: "types": ["node"], plus your test runner's.

The example With @types/node installed (and named in types) on this page shows it, with the same result under every version.

Gotchas

  • require itself is not reported in a .js file, because the checker reads require(...) calls as imports; the module name is then reported if it cannot be found (TS2307 for "fs" without the Node.js types).
  • __dirname and __filename are reported as plain TS2304 without the hint. In ES modules they do not exist at all; Node.js offers import.meta.dirname and import.meta.filename instead (from version 20.11, per its documentation).

  • TypeScript error

    TS2591: Node.js globals with node missing from types

    TS2591 means a Node.js global is used and the config's types list does not include node. Add "node" to types (and install @types/node if needed).

  • TypeScript error

    TS2584: console is missing because lib leaves out the DOM

    TS2584 means console or document is unknown: lib lists only ECMAScript libraries and no Node.js types are loaded. Add @types/node or the dom library.

  • jsconfig.json option

    types and typeRoots

    types lists the @types packages whose globals the checker loads, like node for process. Without it, TypeScript 5.9 loads every @types package; 6.0 loads none.

  • Quick start

    Node.js with ES modules

    Type-check a Node.js project written as ES modules: the jsconfig.json, @types/node, the npm scripts and the import rules that nodenext enforces.

  • Quick start

    Node.js with CommonJS

    Type-check a CommonJS Node.js project: require and module.exports with JSDoc, @types/node, and module nodenext reading "type": "commonjs".

Sources

Last reviewed 20 October 2026.