How to fix 'target' must be specified or 'lib' must contain 'dom' in TypeScript

TypeScriptBEGINNERLOWUpdated Dec 11, 2025· 157 views

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.

Quick fix

Fixes 'target' must be specified or 'lib' must contain 'dom'

// 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"]
  }
}
  1. Check your current tsconfig.json configuration
  2. Add the "target" compiler option
  3. Add "dom" to the "lib" array (alternative solution)
  4. Verify your configuration works
typescript — error
// 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"]
  }
}
'target' must be specified or 'lib' must contain 'dom'

What this error means

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.

Typical symptoms

  • TypeScript compilation fails with error: "'target' must be specified or 'lib' must contain 'dom'"
  • Build tools (webpack, Vite, etc.) fail to compile TypeScript files
  • IDE shows red squiggly lines under DOM API usage (document, window, etc.)
  • Code that uses browser-specific APIs fails type checking

Common causes

  1. Missing "target" field in tsconfig.json compilerOptions
  2. Missing "lib" field or "lib" array doesn't include "dom"
  3. Using an outdated TypeScript version with different default settings
  4. Inheriting tsconfig.json from a parent directory with incomplete configuration
  5. Project migrated from JavaScript to TypeScript without updating compiler options

How to fix "'target' must be specified or 'lib' must contain 'dom'"

1Check your current tsconfig.json configuration

First, examine your tsconfig.json file to see what compiler options are set:

json
// 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.

2Add the "target" compiler option

Add a "target" field to your tsconfig.json. For modern web projects, use "es2020" or later:

json
{
  "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.

3Add "dom" to the "lib" array (alternative solution)

If you prefer not to set a target, you can explicitly include "dom" in the lib array:

json
{
  "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.

4Verify your configuration works

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:

bash
npx tsc --noEmit

3. Check if the error disappears
4. Verify DOM APIs are now recognized:

typescript
// This should no longer show errors
document.getElementById("app");
window.location.href = "/";
const element: HTMLElement = document.createElement("div");
5Handle special cases and edge scenarios

Node.js projects: If you're building a Node.js backend, use "node" lib instead of "dom":

json
{
  "compilerOptions": {
    "target": "es2020",
    "lib": ["es2020"],
    "module": "commonjs"
  }
}

Mixed environments: For universal/isomorphic code:

json
{
  "compilerOptions": {
    "target": "es2020",
    "lib": ["es2020", "dom"]
  }
}

Extending configurations: If using extends, ensure parent config has required options:

json
{
  "extends": "./base-tsconfig.json",
  "compilerOptions": {
    // Override or add missing options
    "target": "es2020",
    "lib": ["es2020", "dom"]
  }
}

Advanced notes

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:

bash
npx tsc --init

This creates a tsconfig.json with common options commented out, including "target" and "lib".

Frequently asked questions

What does "'target' must be specified or 'lib' must contain 'dom'" mean?
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.
How do I fix "'target' must be specified or 'lib' must contain 'dom'"?
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.
What causes "'target' must be specified or 'lib' must contain 'dom'"?
Missing "target" field in tsconfig.json compilerOptions Missing "lib" field or "lib" array doesn't include "dom" Using an outdated TypeScript version with different default settings
Is the "'target' must be specified or 'lib' must contain 'dom'" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading