Updating TypeScript version support in AWS SDK for JavaScript v3

We’re updating TypeScript version support in the AWS SDK for JavaScript v3. Starting January 4, 2027, the SDK will require TypeScript versions published within the last 2.5 years. Read on to learn what’s changing, why this change is necessary, and what actions you may need to take.

We built the AWS SDK for JavaScript with TypeScript-first development in mind, designed to deliver smaller artifacts while taking advantage of modern TypeScript features. This support policy update also aligns the SDK with the broader TypeScript ecosystem.

What’s changing and why

This change applies only if you use TypeScript with the AWS SDK for JavaScript v3.

The TypeScript ecosystem has broadly converged on supporting only recent compiler versions:

• DefinitelyTyped, the central repository for community-maintained TypeScript type definitions (hosting types for 8,000+ npm packages including @types/node and @types/react), only tests packages against TypeScript versions less than 2 years old. For more information, see Support Window on GitHub.
• typescript-eslint, the most widely used TypeScript linting framework, mirrors the DefinitelyTyped support window and only supports TypeScript versions less than 2 years old.

Real-world applications depend on many packages beyond the SDK. Once the broader ecosystem drops an older version, you’re likely to encounter incompatible typings regardless.

We are aligning with this ecosystem norm. The SDK will follow the DefinitelyTyped support window plus a 6-month grace period, giving you up to a 2.5-year window to upgrade your TypeScript version. For more information, see AWS SDKs and Tools maintenance policy.

The following table shows the end-of-support timeline for each TypeScript version:

* Speculative, based on the DefinitelyTyped support window. 

What you can expect

A clear minimum supported TypeScript version

We will document a minimum TypeScript version in the GitHub repository’s README and will keep it updated as part of the normal maintenance process. We define “supported” as:

• We build and test the SDK against TypeScript versions within the support window.
• We may not address issues specific to out-of-window TypeScript versions.

Smaller package artifacts and simpler publishing

This change reduces build and release complexity, published package size, and AWS Lambda artifact size.

What you need to do

You don’t need to take immediate action. If your project uses a TypeScript version within the support window, no changes are needed. For projects on an older TypeScript version, your existing setup will continue to work as long as you don’t update the SDK version. However, we recommend that you upgrade your TypeScript version to continue receiving the latest SDK updates.

You have two options for staying compatible with the SDK:

Option 1: Upgrade TypeScript to a supported version (recommended)

• Upgrade TypeScript in your dev dependencies.
• Run your project’s type check to validate your code against the new TypeScript version.
• Address any new diagnostics.

Tip: Newer compilers often catch issues that older versions missed, so new diagnostics might reveal real bugs in your code.

Option 2: Pin the AWS SDK for JavaScript v3 packages

Pin @aws-sdk/* dependencies to the last version that supported your TypeScript version. This prevents short-term disruption, but you won’t receive newer SDK updates, security patches, or new features.

FAQ

Is this a runtime breaking change?

No. This change affects type-level compatibility (your build) and the SDK’s ability to ship types efficiently. This can cause build failures with older (unsupported) TypeScript compilers.

Why not keep downleveling indefinitely?

Downleveling hasn’t been required since TypeScript 4.7, which was published in May 2022. Down-leveling makes every release heavier:

• Downlevel types account for 18% of the published package size in the SDK.
• Downleveling is an additional step in the SDK’s release process.

Conclusion

We recommend upgrading to a supported TypeScript version ahead of this change to keep receiving updates, security patches, and new features. For the current minimum supported version, see AWS SDK for JavaScript v3 README on GitHub.

We’d love to hear from you. Open a discussion or issue on our GitHub.