Deprecation of legacy exports from AWS CDK CLI pacakge

[youngkwangk]

aws/aws-cdk-cli#310

It looks like cdklocal is using legacy export functions from the AWS CDK CLI package. We are getting the following message when we do cdklocal deploy

Looks like there's a deadline: 2026-03-01

[traviswimer]

I looked into this a little, and it seems like bin/cdklocal is 99% deprecated code, and that code is what is require()ing the aws-cdk legacy exports.

If you look at this line it says none of this has been necessary since aws-cdk < 2.14.0.

In other words, I think it is safe to simply ignore this warning message, since those legacy exports wont actually be used unless you're using an ancient version of aws-cdk, and the require() calls are wrapped in try/catches.

That being said, is there any good reason for maintaining support for a version that old? Seems to me like it would make sense to remove the unnecessary code and release a new major version.

Would any of the maintainers be able to confirm any of this?

[dytyniuk]

Hello there 👋

In other words, I think it is safe to simply ignore this warning message, since those legacy exports wont actually be used unless you're using an ancient version of aws-cdk, and the require() calls are wrapped in try/catches.

I'm not a maintainer, but I have been looking into this issue for a couple of hours. In short, I agree that for AWS CDK versions > 2.177.0 things won't break, as all it has to do is to configure the environment properly:

switch (e.code) {
   // ...
   case "ERR_PACKAGE_PATH_NOT_EXPORTED":
      // post 2.177
      configureEnvironment(process.env, AWS_ENVAR_ALLOWLIST);
      break;
    // ...
}

What makes this even more strange is that devDependencies in package.json has aws-cdk@^2.1004.0, which is 4 versions higher than the 2.177.0 "highwater mark" used here. Trying to support people with an outdated CDK is admirable, no doubt. However, that's the reason people use semantic versioning - the aws-cdk-local@v3 could cap its support of AWS CDK CLI at ^2.10004.0 and be done with it.

On the other hand, cdklocal does not just patch the environment, it also mutates the assembly template to support Localstack's Lambda Hot Reloading. The code is a little outdated, though:

The magic S3 bucket name changed from __local__ to hot-reload in LocalStack v2.0.

(cdklocal code still contains __local__ references).

Now, IMHO, the real question is:

Should cdklocal be responsible just for environment patching to bridge AWS CDK and Localstack?
Or should it also modify the CDK cloud assembly internally to support Localstack's Lambda Hot Reload?

And before you cast your vote for the Hot Reload, I'd ask if cdk(local) watch --hotswap is good enough for you?

Given that:

• Localstack's Hot Reload is not instantaneous (there is a documented at least 500ms sync delay).
• cdk(local) watch --hotswap monitors your source code and, yes, builds your Lambda functions and updates them without the need to redeploy the whole stack.

All in all, whichever feature set is there for aws-cdk-local, I'd consider:

• using @aws-cdk/toolkit-lib to avoid any further patching magic.
• bumping the aws-cdk-local major version to denote backward compatibility break.

[traviswimer]

@dytyniuk I don't know enough about the hot reloading to have an opinion on it, but doesn't that code only run if you're using aws-cdk <= 2.117?

It looks to me like the decision was already made to deprecate that feature.