fix: disable the cdk legacy export warning

[skyrpex]

The CDK is deprecating (and soon removing) internal imports that were never officially supported (see aws/aws-cdk-cli#310).

This fix stops the warning from printing in the terminal when using aws-cdk-local while leaving the existing patching and environment configuration intact. Adds the necessary changes to make the usage of the aws-cdk future-proof.

Notable changes:

• Removes the esbuild heuristic in favor of comparing package versions with semver. The esbuild heuristic won't work in future aws-cdk versions.
• Adds an alternative way of spawning the AWS CLI as a fallback. The current require('aws-cdk/bin/cdk') won't work in future aws-cdk versions.

[joe4dev]

Thank you for tackling these important changes 🔥

It's quite hard to understand all the different patching mechanisms, and we have limited test coverage. I think we need a fix to prevent cdklocal from breaking today 🩹
My main unknown is whether patching and environment variable updates interfere. I added some open questions. Such patching is inherently risky given the limited test coverage, but we should proceed to avoid breaking it completely.

❓ Have we successfully tested these changes locally?
It would be great to have some smoke testing instructions in the README or PR description.

First, I naively tried using bin/cdklocal and ran into an issue:

../bin/cdklocal init app --language python
Error: Cannot find module 'aws-cdk/lib/api/aws-auth'
Require stack:
- /Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal
    at Function._resolveFilename (node:internal/modules/cjs/loader:1225:15)
    at Function._load (node:internal/modules/cjs/loader:1055:27)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:220:24)
    at Module.require (node:internal/modules/cjs/loader:1311:12)
    at require (node:internal/modules/helpers:136:16)
    at patchPre_2_14 (/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal:453:16)
    at Object.<anonymous> (/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal:500:3)
    at Module._compile (node:internal/modules/cjs/loader:1554:14)
    at Object..js (node:internal/modules/cjs/loader:1706:10) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal' ]
}
`aws-cdk` module NOT found! Have you tried adding it to your `NODE_PATH`?
/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal:458
      throw e;
      ^

Error: Cannot find module 'aws-cdk/lib/api/aws-auth'
Require stack:
- /Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal
    at Function._resolveFilename (node:internal/modules/cjs/loader:1225:15)
    at Function._load (node:internal/modules/cjs/loader:1055:27)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:220:24)
    at Module.require (node:internal/modules/cjs/loader:1311:12)
    at require (node:internal/modules/helpers:136:16)
    at patchPre_2_14 (/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal:453:16)
    at Object.<anonymous> (/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal:500:3)
    at Module._compile (node:internal/modules/cjs/loader:1554:14)
    at Object..js (node:internal/modules/cjs/loader:1706:10) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/Users/joe/Projects/LocalStack/aws-cdk-local/bin/cdklocal' ]
}

Node.js v22.14.0

Then, I did an npm install ., but I still get the deprecation warning:

cdklocal --version

█████████████████████████████████████████████████████████████████████████
█                                                                       █
█  ⚠ WARNING: You are using LEGACY EXPORTS from the aws-cdk package!    █
█                                                                       █
█  These exports were never officially supported and will be removed    █
█  after 2026-03-01.                                                    █
█  Please migrate to using the official CDK Toolkit Library instead:    █
█  https://docs.aws.amazon.com/cdk/api/toolkit-lib/                     █
█                                                                       █
█  For more information: https://github.com/aws/aws-cdk-cli/issues/310  █
█  To disable this warning: CDK_DISABLE_LEGACY_EXPORT_WARNING=1         █
█                                                                       █
█████████████████████████████████████████████████████████████████████████

cdklocal v3.0.1
cdk cli version v2.1113.0

I was able to create a new app using cdklocal init app --language javascript and deploy it. However, I still get the deprecation error and when manually deleting the legacy directory, deployment fails:

cdklocal bootstrap
Error: Cannot find module '/Users/joe/.nvm/versions/node/v22.14.0/lib/node_modules/aws-cdk/lib/legacy-exports.js'
    at createEsmNotFoundErr (node:internal/modules/cjs/loader:1261:15)
    at finalizeEsmResolution (node:internal/modules/cjs/loader:1250:15)
    at resolveExports (node:internal/modules/cjs/loader:639:14)
    at Function._findPath (node:internal/modules/cjs/loader:728:31)
    at Function._resolveFilename (node:internal/modules/cjs/loader:1211:27)
    at Function._load (node:internal/modules/cjs/loader:1055:27)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:220:24)
    at Module.require (node:internal/modules/cjs/loader:1311:12)
    at require (node:internal/modules/helpers:136:16) {
  code: 'MODULE_NOT_FOUND',
  path: '/Users/joe/.nvm/versions/node/v22.14.0/lib/node_modules/aws-cdk'
}
`aws-cdk` module NOT found! Have you tried adding it to your `NODE_PATH`?
/Users/joe/.nvm/versions/node/v22.14.0/lib/node_modules/aws-cdk-local/bin/cdklocal:452
      throw e;
      ^

Error: Cannot find module '/Users/joe/.nvm/versions/node/v22.14.0/lib/node_modules/aws-cdk/lib/legacy-exports.js'
    at createEsmNotFoundErr (node:internal/modules/cjs/loader:1261:15)
    at finalizeEsmResolution (node:internal/modules/cjs/loader:1250:15)
    at resolveExports (node:internal/modules/cjs/loader:639:14)
    at Function._findPath (node:internal/modules/cjs/loader:728:31)
    at Function._resolveFilename (node:internal/modules/cjs/loader:1211:27)
    at Function._load (node:internal/modules/cjs/loader:1055:27)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:220:24)
    at Module.require (node:internal/modules/cjs/loader:1311:12)
    at require (node:internal/modules/helpers:136:16) {
  code: 'MODULE_NOT_FOUND',
  path: '/Users/joe/.nvm/versions/node/v22.14.0/lib/node_modules/aws-cdk'
}

Node.js v22.14.0

[joe4dev]

❓ Is it not necessary anymore to catch ERR_PACKAGE_PATH_NOT_EXPORTED for detecting post 2.177 (and I guess pre today's release after 2.1113.0 🤷 ) anymore to apply configureEnvironment selectively?

❓ Is distinguishing aws-cdk/lib and aws-cdk/lib/legacy-exports not required anymore ?

[skyrpex]

I've pushed a more conservative set of changes. The patching and env config logic remains the same as the original code, but with some necessary changes:

• Removes the esbuild heuristic (which won't work anymore) in favor of comparing package versions with semver.
• Since the current way of invoking the AWS CLI will fail in future versions, adds an alternative way spawning the AWS CLI directly.

[joe4dev]

Thank you for the walkthrough and the launch refinement.

I can confirm that the latest changes now work. I also simulated the upcoming AWS removal changes by editing them manually using:

• npm install . -g
• Remove the legacy directories and package.json exports

Test with cdklocal bootstrap && cdklocal deploy 🚀