TypeScript Browser Errors — Type Errors, Module Resolution, and DOM Type Issues
About TypeScript Browser Errors
Fix TypeScript errors in browser applications including DOM type assertions, module resolution failures, and lib configuration for browser APIs. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.
Here are the key things to understand: TypeScript requires type definitions for browser APIs — configured via lib option in tsconfig.json. DOM elements returned by querySelector are typed as Element | null — type narrowing is required. Module resolution (node, bundler, nodenext) affects how imports are resolved. Missing type definitions for third-party libraries cause 'Could not find a declaration file' errors. Strict mode (strict: true) enables all strict type checking options and catches more errors. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.
The most common reasons this occurs include: tsconfig.json missing 'dom' in lib array — browser APIs like document and window are unrecognized. querySelector returning Element | null not narrowed before use. Third-party library missing @types/ package for TypeScript type definitions. Module resolution strategy not matching the bundler (Webpack, Vite, esbuild) configuration. Identifying the root cause is the first step toward finding the right solution.
To resolve this, follow these recommended steps: Add DOM types: set 'lib': ['ES2020', 'DOM', 'DOM.Iterable'] in tsconfig.json. Narrow DOM types: use type guards — if (el instanceof HTMLInputElement) { el.value = 'text'; }. Install type definitions: 'npm install -D @types/library-name' for untyped libraries. Set module resolution: 'moduleResolution': 'bundler' for Vite/modern bundlers, 'node' for Webpack 4. Use non-null assertion (el!) sparingly — prefer proper null checking with if statements. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.
This article is part of our Browser Errors collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.
Quick Answer
Why does TypeScript not recognize document or window?
The 'dom' lib is not included in tsconfig.json. Add '"lib": ["ES2020", "DOM", "DOM.Iterable"]' to compilerOptions. Without it, TypeScript only knows Node.js types.
Overview
Fix TypeScript errors in browser applications including DOM type assertions, module resolution failures, and lib configuration for browser APIs.
Key Details
- TypeScript requires type definitions for browser APIs — configured via lib option in tsconfig.json
- DOM elements returned by querySelector are typed as Element | null — type narrowing is required
- Module resolution (node, bundler, nodenext) affects how imports are resolved
- Missing type definitions for third-party libraries cause 'Could not find a declaration file' errors
- Strict mode (strict: true) enables all strict type checking options and catches more errors
Common Causes
- tsconfig.json missing 'dom' in lib array — browser APIs like document and window are unrecognized
- querySelector returning Element | null not narrowed before use
- Third-party library missing @types/ package for TypeScript type definitions
- Module resolution strategy not matching the bundler (Webpack, Vite, esbuild) configuration
Steps
- 1Add DOM types: set 'lib': ['ES2020', 'DOM', 'DOM.Iterable'] in tsconfig.json
- 2Narrow DOM types: use type guards — if (el instanceof HTMLInputElement) { el.value = 'text'; }
- 3Install type definitions: 'npm install -D @types/library-name' for untyped libraries
- 4Set module resolution: 'moduleResolution': 'bundler' for Vite/modern bundlers, 'node' for Webpack 4
- 5Use non-null assertion (el!) sparingly — prefer proper null checking with if statements