(aws-cdk-cli): TypeScript template includes "dom" in lib, which is unnecessary for Node.js CDK apps

[46ki75]

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.ts

Possible 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.

[pahud]

• Problem Confirmed: The default tsconfig.json generated by cdk init app --language typescript incorrectly includes "dom" in the lib array.
• Impact: This allows TypeScript to recognize browser-specific globals (like window, document) - even though they don't exist in the Node.js runtime where CDK apps execute. This can lead to developers accidentally using these globals, resulting in runtime errors that aren't caught during compilation.
• Root Cause Located: The issue stems from the static template file packages/aws-cdk/lib/init-templates/app/typescript/tsconfig.json
• Solution: Removing "dom" from the lib array in the template file seems to be the correct fix, as it aligns the TypeScript environment with the actual Node.js runtime.

Thank you for the PR. The maintainer should review your PR when it's ready.