article summary

Solve TypeScript 'Cannot find name' errors with proven fixes: declarations, tsconfig, and troubleshooting. Step-by-step guide — fix your build now.

Fixing the "Cannot find name 'X'" Error in TypeScript

Introduction

If you've used TypeScript for more than a few weeks, you've probably run into the compiler error: "Cannot find name 'X'". It shows up during tsc builds, in editors (VS Code, WebStorm), or in CI pipelines. For intermediate developers this message can be deceptively simple — sometimes it truly means a missing identifier, and other times it points to configuration, typing, or module-resolution problems. This guide dives deep: you'll learn how TypeScript resolves names, how to diagnose the root cause, and how to fix the problem in real projects, including third-party libraries, global variables, and custom declaration files.

In this tutorial you'll walk through practical debugging steps, tsconfig rules that affect name resolution, and multiple approaches to declare or import symbols safely. We'll cover writing .d.ts files, using DefinitelyTyped packages, handling global browser APIs, resolving module path issues, and preventing future occurrences via compiler flags and project structure. There are code examples, step-by-step repair instructions, and advanced techniques for complex monorepos.

By the end you will be comfortable reading TypeScript diagnostics, knowing where to add declarations, and configuring your project to avoid regressions. This is meant for developers who already know TypeScript basics (types, interfaces, modules) and want actionable strategies to resolve and prevent the "Cannot find name" family of errors.

Background & Context

TypeScript's "Cannot find name 'X'" is a name-resolution error emitted when the compiler can't find a declaration for an identifier that's used in code. This can happen for many reasons: the symbol really doesn't exist, a module import is incorrect, a declaration file (.d.ts) is missing or misconfigured, or compiler options prevent the compiler from seeing a file. Because TypeScript separates type-checking from runtime, resolving names correctly often relies on ambient declarations or correct module definitions.

Understanding how TypeScript finds types (via node resolution, typeRoots, and included files in tsconfig) is essential to fix these errors. We'll also explore how declaration files for global variables and functions are authored and how to pull typings from the community. If you maintain build configs, you'll appreciate how compiler options like rootDir, outDir, and module resolution affect name lookup. For a general overview of configuring TypeScript projects, see our guide on Introduction to tsconfig.json: Configuring Your Project.

Key Takeaways

How to read the "Cannot find name" diagnostic and map it to causes
Steps to verify imports, module resolution, and file inclusion
How and when to write ambient declarations (.d.ts) for globals
How to use community type packages (DefinitelyTyped) and troubleshoot broken typings
Which tsconfig options affect name resolution and why they matter
Best practices to keep your codebase typing-safe and maintainable

Prerequisites & Setup

This guide assumes you have a working TypeScript environment (Node.js, npm/yarn, and an editor like VS Code). Install a recent TypeScript version (>=4.x) for better diagnostics and language features:

bash

npm install --save-dev typescript
npx tsc --version

Make sure your project has a tsconfig.json at the repo root. If you need to review the basic compiler options that affect builds, check our guide on Setting Basic Compiler Options: rootDir, outDir, target, module.

You should be comfortable with ES module imports and have a basic mental model of TypeScript's module resolution (node-style vs classic). Also ensure your editor uses the workspace TypeScript version (VS Code: Use Workspace Version) so errors match the tsc CLI.

Main Tutorial Sections

1) Read the Diagnostic and Find the Context

Start by reading the exact message and surrounding code. "Cannot find name 'Foo'" can mean:

A local variable or function 'Foo' was never declared
An import is missing or misspelled
A global (browser API or injected script) hasn't been declared

Example:

function doWork() {
  console.log(User.name);
}

If you see this and there is no local User import or declaration, TypeScript can't find a declaration for it. Use the editor's 'Go to Definition' or run tsc to see where the compiler fails. If it's caused by global runtime values (like a script that injects "analytics"), you'll need an ambient declaration (see section on globals).

When debugging, don't assume the runtime object exists — check the runtime first and only add types/declarations if you confirm the value is provided by the environment or a script.

For patterns about declaring globals and functions, our guide on Declaration Files for Global Variables and Functions provides practical examples.

2) Missing or Incorrect Declaration Files for External Libraries

If a symbol is from a third-party package (for example, calling MyLib.doThing()), TypeScript needs typings. Many packages ship their own types; others require @types packages. When you see "Cannot find name" for a library symbol, check:

Is @types/ installed? (npm i -D @types/packagename)
Does the package expose types in package.json ("types" field)?
Is the package a UMD global that requires

Troubleshooting missing or incorrect declaration files is common — read our dedicated instructions in Troubleshooting Missing or Incorrect Declaration Files in TypeScript. Also, to find and install community typings, learn about Using DefinitelyTyped for External Library Declarations.

Example fix:

bash

npm i --save-dev @types/lodash

Then import types normally:

import _ from 'lodash';
_.map(...);

If no types exist, consider authoring a minimal declaration file (see section on writing .d.ts).

3) Global vs Module Scope and /// Usage

TypeScript treats files with imports/exports as modules with isolated scope. Top-level declarations in one module are not visible to another unless exported/imported or declared as ambient globals. If you rely on global script-injected names, you must provide ambient declarations in a .d.ts file, or include a directive for legacy setups.

Example: if an external script provides a global Analytics object (no import), add a .d.ts:

declare global {
  interface Window { Analytics: any }
}
export {} // ensure file is a module

Or for triple-slash references in legacy multi-file projects, learn when and how to use them in Understanding /// Directives in TypeScript.

4) Writing a Declaration File (.d.ts) — Basics

When you must add types yourself, create a .d.ts file in your project (for example, types/globals.d.ts). Keep it minimal and precise. Example for a global helper:

// types/globals.d.ts
declare const __BUILD_DATE__: string;

declare interface MyGlobalWidget {
  init(opts?: { root: HTMLElement }): void;
}

declare const Widget: MyGlobalWidget;

Place this file where TypeScript will find it (include it via tsconfig "files"/"include" or ensure it's under the project root). For an in-depth introduction to declaration files and patterns for typing existing JS, see Introduction to Declaration Files (.d.ts): Typing Existing JS.

5) Quick Fixes: declare, any, and Stub Types

When you need a fast unblock during development, declare the symbol or use a stub type. This is a stop-gap; prefer precise types later.

declare const Foo: any; // fast but unsafe
// or
declare const Foo: { doThing(): void };

If a missing symbol is due to implicit any rules, understand how flags like noImplicitAny affect the compiler. We cover strategies to avoid untyped variables in Using noImplicitAny to Avoid Untyped Variables.

Use these stubs only temporarily and track TODOs for proper typings.

6) Module Resolution and Import Path Errors

Often the "Cannot find name" comes from a failed import that the TypeScript resolver can't follow. Typical problems:

Wrong relative path: import { X } from '../lib/x' vs '../lib/x/index'
Case-sensitive file systems (macOS vs Linux)
Missing index.ts or incorrect package "exports"

Use tsc --traceResolution to see how TypeScript attempts to resolve an import. Example:

bash

npx tsc --traceResolution src/app.ts

Fix paths, check package.json "types"/"main" fields, and confirm files are included by tsconfig (see the next section about tsconfig inclusion).

7) tsconfig: Included Files, typeRoots, and project boundaries

The tsconfig controls which files and type declarations TypeScript sees. If a .d.ts file isn't picked up, confirm:

tsconfig.json includes the path (using "include" or not excluding it)
typeRoots and types settings don't exclude your custom declarations
In monorepos, ensure composite projects reference and expose types properly

If you need a refresher on how to configure tsconfig for scalable projects, refer to Introduction to tsconfig.json: Configuring Your Project and the focused options in Setting Basic Compiler Options: rootDir, outDir, target, module.

Example tsconfig snippet to include a custom types folder:

json

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types"]
  },
  "include": ["src", "types"]
}

8) Using Community Types (DefinitelyTyped) Correctly

Before writing your own declarations, check if types exist on DefinitelyTyped. Install via npm:

bash

npm i --save-dev @types/somepackage

If the package has partial types, you may still need to augment them. Learn how to find and contribute to community typings in Using DefinitelyTyped for External Library Declarations.

When a @types package is out-of-date, consider creating a local augmentation in a types/ folder or submitting a PR to DefinitelyTyped.

9) Writing Simple Module Declarations for JS Modules

If you import a plain JS module with no types, create a module declaration file:

// types/my-js-lib.d.ts
declare module 'my-js-lib' {
  export function doThing(arg: string): Promise<number>;
}

Place it in typeRoots or include it in tsconfig. For step-by-step patterns to type a JS module, see Writing a Simple Declaration File for a JS Module.

10) Debugging Tips and Editor Integration

Restart your language server or editor when changing tsconfig or adding .d.ts files
Use tsc --noEmit to get the full set of compiler diagnostics
Use --traceResolution to trace module lookup
Check global npm @types conflicts (sometimes multiple versions create ambiguous paths)

If you use monorepos, ensure each package's tsconfig references other packages or exposes types. When behavior differs between IDE and tsc, prefer the CLI output — editors sometimes use their bundled TypeScript version and an outdated cache.

Advanced Techniques

When simple fixes aren't enough, use advanced strategies:

Declaration merging and module augmentation: augment an existing library's types using declare module 'lib' { ... } with careful merging rules.
Create a centralized types package in monorepos: publish or reference a shared "types" package to avoid duplication and ensure consistent ambient declarations across packages.
Use paths + baseUrl in tsconfig for friendly import aliases, but combine them with tooling support (tsconfig-paths, bundler alias) to maintain runtime resolution.
Build-time validation: add tsc --noEmit to CI to catch missing declarations early, and use stricter flags in CI than local dev to prevent regressions.

For stricter development workflows, combine these with recommended strictness flags — see our guide on Understanding strict Mode and Recommended Strictness Flags for suggestions on enabling checks safely.

Best Practices & Common Pitfalls

Dos:

Prefer explicit imports/exports over ambient globals for maintainability.
Keep declaration files small, focused, and documented.
Use community typings when available; contribute back when you fix them.
Keep tsconfig consistent across team members and enforce via CI.

Don'ts:

Don't scatter declare any across the codebase — it hides bugs and reduces type safety.
Avoid relying on triple-slash references for modern module-based code; they are primarily for legacy setups.
Don't ignore tsc --traceResolution outputs — they often show the real cause of unresolved names.

Troubleshooting checklist:

Confirm runtime existence of the symbol.
Verify import paths and file casing.
Ensure tsconfig includes your declarations.
Search for @types packages and check package.json "types".
Restart your editor/language server.

Many issues stem from misconfigured project boundaries: if a package in a monorepo doesn't expose its types properly or tsconfig excludes the types folder, the symptom will be "Cannot find name" even though the symbol exists at runtime.

Real-World Applications

Browser global APIs: Add precise ambient declarations for window-injected analytics, feature flags, or vendor globals. This prevents runtime surprises and keeps autocomplete in your IDE.
Migrating JS libraries: When migrating a JS module to TypeScript, write module declarations to incrementally adopt types — see Introduction to Declaration Files (.d.ts): Typing Existing JS.
Multi-package repositories: Centralize shared typings and enforce types via a shared tsconfig base. If packages publish, ensure their package.json contains the "types" path so consumers don't see missing names.
Rapid prototyping: Use temporary declare stubs to move quickly, then refine with interface/type definitions and publish improved types upstream.

Conclusion & Next Steps

"Cannot find name 'X'" is a common but solvable TypeScript error. This guide gave you a systematic approach: read diagnostics, verify imports and runtime, add declarations or install typings, and configure tsconfig correctly. Next, standardize your project's tsconfig, add CI checks with tsc --noEmit, and consider contributing missing types to the community.

To deepen your knowledge, explore writing advanced mapped and conditional types when you replace any stubs with richer typings — our other guides on mapped types and conditional types are excellent follow-ups.

Enhanced FAQ

Q1: What is the fastest way to fix "Cannot find name 'X'" during development? A1: The fastest approach is to add a temporary declare const X: any; in a .d.ts file included by tsconfig. This unblocks compilation, but record a follow-up task to replace any with a real type. Use declare only when you confirmed the symbol exists at runtime.

Q2: I imported a module but still get "Cannot find name" for a type it should export — why? A2: Several causes: the module might not export the type (named vs default export mismatch), the package's types might be missing or incorrect, or TypeScript may resolve a different package copy (duplicate node_modules). Check package.json "types" field and use npx tsc --traceResolution to inspect resolution paths. Installing @types or adding a local module declaration file can fix it.

Q3: How do I declare a global constant injected at build time (e.g., BUILD_DATE)? A3: Create a types/globals.d.ts and declare it as:

declare const __BUILD_DATE__: string;
export {} // make the file a module to avoid polluting global scope unintentionally

Include the types folder in tsconfig. This tells TypeScript the name exists at compile time.

Q4: Are triple-slash references still recommended? A4: Triple-slash references are primarily for legacy codebases that rely on ordering of script files. For modern module-based TypeScript projects, prefer imports/exports and .d.ts ambient or module declarations. If you must use references, see Understanding /// Directives in TypeScript for correct patterns.

Q5: Why does the error appear only in the editor but not with tsc? A5: The editor may use a different TypeScript version or an outdated language server cache. Ensure the editor is configured to use the workspace TypeScript version and restart the TypeScript server. Use the CLI npx tsc --noEmit to confirm the true compiler output.

Q6: Should I always install @types packages for libraries? A6: If a package doesn't ship its own types, installing @types/ is the standard solution. For packages that intentionally provide globals (UMD bundles), you may need ambient declarations instead. Learn how to use community types effectively in Using DefinitelyTyped for External Library Declarations.

Q7: How do I structure .d.ts files for a large project? A7: Keep .d.ts files focused and colocated when possible (e.g., a types/ folder or package-local declarations). For monorepos, maintain a shared types package and reference it via path aliases or package dependencies. Make sure tsconfig includes them with "typeRoots" or "include" to avoid accidental exclusion — read about configuring tsconfig in Introduction to tsconfig.json: Configuring Your Project.

Q8: I fixed the .d.ts but the error persists. What now? A8: Commonly you need to restart the editor/TS server, clear the build cache, or ensure tsconfig "include" picks up the new file. Also check for multiple tsconfig files (project references) and ensure the right tsconfig is used. If you added module declarations ensure they don't conflict with existing types.

Q9: Can strict mode flags cause missing-name errors? A9: Strict mode typically surfaces more type errors, but missing-name errors are about absent declarations. However, strict flags like noImplicitAny can prompt you to add types where you previously relied on inferred or implicit globals. For guidance on choosing strict flags, see Understanding strict Mode and Recommended Strictness Flags.

Q10: Where should I learn to write better .d.ts files and augmentations? A10: Start with simple ambient declarations and module declarations. Then progress to advanced topics like declaration merging, module augmentation, and generics in declaration files. Our practical guide to Writing a Simple Declaration File for a JS Module and the general introduction at Introduction to Declaration Files (.d.ts): Typing Existing JS are great next steps.

If you want, I can walk through a specific code example from your project and propose exact changes (tsconfig edits, declaration stubs, or improved imports). Share the snippet and your tsconfig and I'll provide tailored fixes.

Fixing the "Cannot find name 'X'" Error in TypeScript

Quick Overview