A Cannot find name error usually means TypeScript has not loaded the declaration file that describes a global for the current project. This guide shows how to identify the runtime you are targeting, choose the right lib and types settings, inspect the declarations TypeScript actually loaded, and keep browser, Node.js, worker, and test environments separate instead of hiding genuine errors.
Overview
TypeScript does not infer every global from the JavaScript runtime that will eventually execute your code. Names such as window, document, process, Buffer, Worker, describe, and expect become available when the compiler includes the declarations that define them.
Those declarations come from two main places:
- Library declarations: built-in TypeScript files selected through
compilerOptions.lib, such asDOM,WebWorker, and an ECMAScript version. - Package declarations: installed type packages such as
@types/nodeor a test runner's types, selected automatically or throughcompilerOptions.types.
The error is therefore not always fixed by installing another package. Adding DOM declarations to a server project can make window compile even though it will fail at runtime. Similarly, adding Node declarations to browser code can make server-only APIs appear valid. The correct fix is to make the project configuration describe its actual execution environment.
First check the spelling, then ask three questions: Where does this file run? Which declaration source defines the missing name? Is this the correct project configuration for the file? If the answer differs between application code and tests, use separate configurations rather than one broad global environment.
Template structure
Common globals and their declaration sources
| Global | Typical environment | Declaration source | Typical configuration |
|---|---|---|---|
window, document, HTMLElement | Browser application | TypeScript DOM library | lib: ['ES2022', 'DOM', 'DOM.Iterable'] |
Worker, DedicatedWorkerGlobalScope | Web Worker | Web Worker library | lib: ['ES2022', 'WebWorker'] |
process, Buffer, NodeJS | Node.js | @types/node | types: ['node'] |
describe, it, expect | Test files | Test runner declarations | Runner-specific types or test config |
fetch, URL, Promise | Browser, Node.js, or another runtime | ECMAScript, DOM, or runtime package declarations | Match the runtime and compiler version |
Diagnostic commands
Inspect the configuration TypeScript resolves instead of guessing which tsconfig.json an editor or build is using:
npx tsc -p tsconfig.json --showConfig
npx tsc -p tsconfig.json --listFilesOnly
npx tsc -p tsconfig.json --traceResolution
--showConfig displays the effective compiler options after inheritance and overrides. --listFilesOnly helps confirm whether files such as the DOM library or Node declaration packages are included. --traceResolution is more verbose, but it can reveal why a package or configuration file was not resolved.
Also verify the project selected by your editor. A file opened outside the intended project may be treated as an inferred project, while a monorepo may contain several configurations with different environments.
Safe configuration patterns
A browser application can use a configuration similar to this:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"strict": true
},
"include": ["src/**/*.ts", "src/**/*.tsx"]
}
A Node.js application should normally include Node declarations and avoid DOM declarations unless the server intentionally uses a DOM-compatible library:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"types": ["node"],
"strict": true
},
"include": ["src/**/*.ts"]
}
The exact module settings depend on the project and its package configuration. The important point is that @types/node must be installed as a development dependency and included in the configuration used to compile the server files.
For tests, extend the application configuration only when the test environment adds declarations without changing the application runtime:
{
"extends": "./tsconfig.json",
"compilerOptions": {
"types": ["node", "vitest/globals"]
},
"include": ["src/**/*.ts", "tests/**/*.ts"]
}
Use the declaration package and configuration recommended by the test runner in your project. Some runners prefer explicit imports such as import { describe, expect, it } from 'vitest' rather than global test names. Explicit imports reduce ambient scope and make a test file easier to move between projects.
How to customize
Choose lib for platform APIs
The lib option controls built-in API declarations. An ECMAScript library describes language features such as Map, Promise, and newer array methods. DOM describes browser APIs such as document and HTMLElement. WebWorker describes worker-specific APIs and should be selected for worker entry points rather than automatically added to every file.
Do not treat lib as a polyfill or runtime switch. It changes type checking only. If the target runtime lacks an API, you still need a compatible runtime, platform support, or polyfill.
Choose types for package-provided globals
When compilerOptions.types is omitted, TypeScript can discover visible declaration packages under node_modules/@types. When types is specified, it becomes an allowlist for global type packages. A common source of surprises is adding one package to this array and unintentionally excluding another package that previously supplied globals.
For example, a test configuration with types: ['node'] may remove the test runner's global declarations. Add the runner's package when you deliberately use global test APIs, or use explicit imports instead.
Use declarations only for genuinely global APIs
For a custom runtime global, an ambient declaration can be appropriate:
declare const BUILD_VERSION: string;
Keep such declarations in a clearly named file included by the relevant project. Do not declare window, process, or describe yourself merely to silence an error; that masks a missing or incorrect environment configuration. If an environment variable is accessed through a framework-specific object, use that framework's supported type augmentation pattern and keep runtime validation separate from compile-time declarations. The guide on type-safe environment variables is useful for this distinction.
Examples
Cannot find name 'window'
This usually occurs when browser code is compiled with a server-oriented configuration, or when the DOM library was removed from an explicit lib array. Add the DOM library to the browser project, not to a shared server configuration. If the file is shared between browser and server code, prefer a platform-neutral API or narrow the code behind an environment-specific boundary:
export function getViewportWidth(): number | undefined {
return typeof window === 'undefined' ? undefined : window.innerWidth;
}
The runtime check prevents execution in Node.js, but the project still needs declarations for the browser branch to type-check.
Cannot find name 'process' or Cannot find name 'Buffer'
Install the Node.js declaration package used by the project and include it in the Node configuration. Do not fix this by adding a hand-written declare const process unless you are describing a deliberately custom runtime. If the code is actually bundled for a browser, replace the Node API with the bundler's supported environment mechanism rather than making Node globals visible everywhere.
Cannot find name 'Worker'
Check which side of the worker boundary the file represents. A browser page may construct a worker and therefore need DOM declarations, while the worker entry point may need Web Worker declarations. A single broad configuration can create conflicts or make both sets of APIs appear available. Separate entry-point projects or carefully scoped declaration files make accidental cross-environment usage easier to catch.
Cannot find name 'describe' or expect
Confirm that the test files are included by the test configuration and that the selected runner's declarations are installed and enabled. Check whether the runner expects globals or imports. Also compare the command run locally with the command used in CI; CI may invoke a different project file, package manager workspace, or test transform. For broader test setup patterns, see TypeScript testing setup.
When the error appears after a migration
JavaScript-to-TypeScript migrations often expose files that previously relied on an implicit browser, Node, or test environment. Treat each error as a boundary decision: identify where the file runs, then include the smallest correct declaration set. A staged migration plan can help keep application, build, and test checks distinct; see the JavaScript to TypeScript migration plan for a related workflow.
When to update
Revisit this setup whenever the execution environment or compiler inputs change. Useful triggers include moving code between browser and server, adding a Web Worker, introducing a test runner, changing bundlers, upgrading TypeScript, upgrading @types/node, changing the module system, or splitting a monorepo into project references.
Use this short checklist when a missing-global error appears:
- Read the filename and identify the runtime that actually executes it.
- Check the active project with
tsc --showConfig. - Inspect loaded declaration files with
--listFilesOnly. - Choose the matching
libfor platform APIs andtypesfor package globals. - Check
include, project references, and test-specific configuration. - Run the compiler and the real runtime or test command; a successful type check does not prove that an API exists at runtime.
Finally, avoid making the error disappear by loosening strictness, adding every available type package, or declaring an unknown global as any. Those changes can hide a misplaced import or an invalid cross-environment dependency. Keep a small, explicit configuration for each runtime, and update it when the project boundary changes. That practice turns Cannot find name from a frustrating message into a useful signal about what your code is allowed to assume.