(aws-cdk-cli): TypeScript template includes "dom" in lib, which is unnecessary for Node.js CDK apps #294
Description
Describe the bug
The TypeScript template (cdk init app --language typescript) generates a tsconfig.json file that includes "dom" in the lib field.
This is unnecessary and potentially misleading, as CDK apps run in Node.js and do not have access to browser-specific globals such as window or document.
Including "dom" can lead to accidental usage of APIs that do not exist in the runtime, resulting in runtime errors despite no TypeScript errors.
Regression Issue
- Select this option if this issue appears to be a regression.
Last Known Working CDK Version
No response
Expected Behavior
The tsconfig.json should only include "es2020" or a similar ECMAScript target appropriate for Node.js.
Example:
"lib": ["es2020"]
Current Behavior
The generated tsconfig.json currently contains:
"lib": ["es2020", "dom"]
This enables types for browser-only APIs, which may cause confusion or runtime errors in Node.js.
Reproduction Steps
Note: npm is used in the reproduction steps for broader compatibility, but the CDK repo itself uses yarn for development.
mkdir test-cdk && cd test-cdk
npx aws-cdk init app --language typescript
echo 'console.log(window.location.href);' >> test.ts
npx ts-node ./test.tsPossible Solution
Remove "dom" from the lib field in tsconfig.json inside the app/typescript init template:
packages/aws-cdk/lib/init-templates/app/typescript/tsconfig.json
Change:
"lib": ["es2020", "dom"]
To:
"lib": ["es2020"]
This ensures that browser-only APIs like window, document, or localStorage will no longer be mistakenly recognized by TypeScript Language Server (LSP) in IDEs like VS Code.
Without "dom" in the lib, references to such APIs will cause type errors, helping users avoid accidental usage of non-Node.js globals at development time.
Additional Information/Context
This change would help prevent accidental usage of browser-only APIs in CDK projects, especially by infrastructure-focused users who may not be familiar with browser vs. Node.js runtime differences.
In practice, this issue can cause real confusion — especially for infrastructure engineers who are not deeply familiar with the distinction between browser and Node.js runtimes.
For example, in my team, one developer unintentionally used window.Buffer instead of the correct Buffer global in Node.js. Since "dom" was present in the lib, no TypeScript error occurred, and it was unclear to him why the application failed at runtime. Removing "dom" would have made this mistake immediately obvious in the editor.
CDK CLI Version
2.1006.0 (build a3b9762)
Framework Version
No response
Node.js Version
v22.14.0
OS
Ubuntu 24.04 (WSL2 on Windows 11 Home)
Language
TypeScript
Language Version
5.6.3
Other information
With the current tsconfig.json, browser-only globals like window can be used without any TypeScript errors, even though they are not available in the Node.js runtime:
After removing "dom" from the lib field, the IDE (e.g., VS Code) correctly highlights these references as errors, helping developers catch the issue before runtime:
Of course, attempting to use these browser-specific globals at runtime will result in a ReferenceError regardless of the tsconfig.json settings.
