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.
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"]
}
}// 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'
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".