This TypeScript error occurs when your tsconfig.json file is missing either the "target" compiler option or the "dom" library in the "lib" array. TypeScript needs to know which JavaScript version to target and which built-in APIs are available. The error typically appears when trying to compile code that uses browser DOM APIs without proper configuration.
TypeScript's compiler requires either a "target" setting (like "es2020", "esnext") or an explicit "lib" array that includes "dom" to understand browser-specific APIs. When neither is provided, TypeScript cannot determine which JavaScript features and built-in types are available, causing compilation to fail. This is especially common in frontend projects where DOM APIs like document, window, or HTMLElement are used.
First, examine your tsconfig.json file to see what compiler options are set:
// Look for these fields in your tsconfig.json
{
"compilerOptions": {
// Check if "target" exists
"target": "es2020",
// Check if "lib" exists and includes "dom"
"lib": ["es2020", "dom"]
}
}If either "target" or "lib" is missing, you'll need to add them.
Add a "target" field to your tsconfig.json. For modern web projects, use "es2020" or later:
{
"compilerOptions": {
"target": "es2020",
// ... other options
}
}Common target values:
- "es2020" or "es2022": Modern JavaScript features
- "esnext": Latest ECMAScript features
- "es5": Maximum browser compatibility (older browsers)
The "target" setting tells TypeScript which JavaScript version to emit.
If you prefer not to set a target, you can explicitly include "dom" in the lib array:
{
"compilerOptions": {
"lib": ["es2020", "dom"],
// ... other options
}
}Common lib combinations:
- ["es2020", "dom"]: Modern ES features + browser APIs
- ["esnext", "dom", "dom.iterable"]: Latest features + DOM iteration
- ["es5", "dom"]: Older browser support
The "dom" library includes TypeScript definitions for browser APIs.
After updating tsconfig.json, test your configuration:
1. Restart your TypeScript server (in VS Code: Command Palette → "TypeScript: Restart TS Server")
2. Run the TypeScript compiler:
npx tsc --noEmit3. Check if the error disappears
4. Verify DOM APIs are now recognized:
// This should no longer show errors
document.getElementById("app");
window.location.href = "/";
const element: HTMLElement = document.createElement("div");Node.js projects: If you're building a Node.js backend, use "node" lib instead of "dom":
{
"compilerOptions": {
"target": "es2020",
"lib": ["es2020"],
"module": "commonjs"
}
}Mixed environments: For universal/isomorphic code:
{
"compilerOptions": {
"target": "es2020",
"lib": ["es2020", "dom"]
}
}Extending configurations: If using extends, ensure parent config has required options:
{
"extends": "./base-tsconfig.json",
"compilerOptions": {
// Override or add missing options
"target": "es2020",
"lib": ["es2020", "dom"]
}
}Understanding the relationship between target and lib:
TypeScript uses the "target" setting to determine default library files. When you set "target": "es2020", TypeScript automatically includes the ES2020 library. However, for DOM APIs (browser-specific), you need to explicitly include "dom" in the lib array or use a target that implies DOM (which most don't).
Historical context: In older TypeScript versions (pre-2.0), the default lib included DOM types when no target was specified. This changed to be more explicit, requiring developers to consciously choose their environment.
Performance considerations: Including unnecessary libs (like "dom" in a Node.js project) increases compilation time and may hide legitimate errors. Always match your lib configuration to your actual runtime environment.
Migration strategy: When migrating from JavaScript to TypeScript, start with a minimal tsconfig.json and add options as needed. The TypeScript compiler can help generate a starting configuration:
npx tsc --initThis creates a tsconfig.json with common options commented out, including "target" and "lib".
Type parameter 'X' is not used in the function signature
How to fix "Type parameter not used in function signature" in TypeScript
Type parameter 'X' is defined but never used
How to fix "Type parameter is defined but never used" in TypeScript
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript