⚠️ NOTICE: Deprecation and removal of legacy exports from AWS CDK CLI package #310
Description
If you're seeing yellow warning messages when using the AWS CDK CLI package, this notice explains why and what you need to do.
Why are you seeing these warnings?
You are importing internal APIs from the aws-cdk package that were never officially supported. These imports typically look like:
import { SdkProvider } from 'aws-cdk/lib/api/aws-auth';
import { CloudExecutable } from 'aws-cdk/lib/api/cxapp/cloud-executable';
// ... or similar deep importsThese APIs were always considered internal implementation details and were never part of the public API contract.
What should you do?
Migrate to the official CDK Toolkit Library: @aws-cdk/toolkit-lib
The CDK Toolkit Library provides a stable, supported programmatic interface for CDK operations like:
- Synthesis
- Deployment
- Diff operations
- Bootstrap operations
- And more
While the Toolkit Library does not provide an identical API for all deprecated legacy exports, we believe it covers all major use cases for the CDK. If you have a use case that is not yet covered by the Toolkit Library, please let us know in this issue. We can assess the situation and discuss options. Please do note that many legacy exports are trivial helpers or don't work as they might seem.
Migration example:
Before (unsupported):
import { deployStack } from 'aws-cdk/lib/api/deployments';After (supported):
import { Toolkit } from '@aws-cdk/toolkit-lib';
const cdk = new Toolkit();
await cdk.deploy(cloudAssemblySource, options);When will legacy exports be removed?
Legacy exports will be completely removed in a release after March 1st, 2026.
After this date, any code relying on these internal imports will not be able to update to newer version of the AWS CDK CLI package. We strongly recommend migrating to the official CDK Toolkit Library as soon as possible.
Need help with migration?
- 📖 CDK Toolkit Library Documentation
- 💬 Ask questions in the CDK Community Slack
- 🐛 Report migration issues in this repository
Timeline
- Now: Yellow warning messages appear when using legacy exports
- March 1st, 2026: Legacy exports will be completely removed
Please plan your migration accordingly to avoid any disruption to your applications.
Why were these exports available in the first place if they should not be used?
In older versions of Node.js it was possible to import any files from any package. While these imports were possible, it was also best practice to only import from explicitly supported paths. Later versions of Node.js introduced official support for this practice by giving package authors the option to explicitly declare their exports.
In early 2025, the AWS CDK CLI package started specifying its exports and because the package is a CLI there are essentially none. To maintain compatibility with APIs known to be used by other packages and to not break all these packages immediately, a few API where explicitly added as "legacy exports". The CDK team is now formally deprecating and removing these exports.