From ff3fe1fc97ff4b79f23a7dd45f061d6b615f6102 Mon Sep 17 00:00:00 2001 From: Anisa Oshafi Date: Thu, 8 Oct 2026 17:25:55 +0200 Subject: [PATCH 1/2] Show a deprecation notice that points to lstk cdk --- README.md | 10 ++++++++++ __tests__/index.test.js | 36 +++++++++++++++++++++++++++++++++++- bin/cdklocal | 4 +++- package-lock.json | 4 ++-- package.json | 2 +- src/index.js | 32 ++++++++++++++++++++++++++++++++ 6 files changed, 83 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2eb5901..f64ceb0 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,14 @@ # AWS Cloud Development Kit (CDK) for LocalStack +> [!WARNING] +> **`cdklocal` is deprecated. Use `lstk cdk` instead.** +> +> `cdklocal` no longer receives updates. +> +> - Get started with `lstk`, the new LocalStack CLI: [docs.localstack.cloud/.../lstk](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) +> - Switch your scripts and CI workflows to `lstk cdk`: [docs.localstack.cloud/.../lstk/migration](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/migration/#infrastructure-as-code) + This project provides a thin wrapper script `cdklocal` for using the [AWS CDK](https://github.com/aws/aws-cdk) library against local APIs provided by [LocalStack](https://localstack.cloud). **Note:** This project replaces the [old (deprecated) repo](https://github.com/localstack/aws-cdk) which was a fork of the AWS CDK repo. Instead of forking the repo and applying changes, we now simply provide a simple wrapper script `cdklocal` which applies runtime patching. The advantage of the new approach is that you should be able to use arbitrary CDK versions under the cover. @@ -50,6 +58,7 @@ The following environment variables can be configured: * `USE_SSL` (deprecated): Whether to use SSL to connect to the LocalStack endpoint, i.e., connect via HTTPS. * `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). Note: may require CDK version <2.14.0 to be fully functional. * `BUCKET_MARKER_LOCAL`: Magic S3 bucket name for Lambda mount and [hot reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading) (default: `__local__`, will default to `hot-reload` in a future release) +* `DISABLE_DEPRECATION_NOTICE`: Set to `1` to hide the deprecation notice ### Path-style S3 URLs for remote endpoints @@ -95,6 +104,7 @@ $ awslocal sns list-topics ## Change Log +* 3.1.0: Print a deprecation notice that points to `lstk cdk` * 3.0.4: Fix asset publishing failures for CDK >= 2.177.0 against remote LocalStack endpoints (e.g. `*.sandbox.localstack.cloud`) * 3.0.3: Add missing `semver` dependency * 3.0.2: Add support for `aws-cdk` versions after 2026-03-01 (see https://github.com/aws/aws-cdk-cli/issues/310) diff --git a/__tests__/index.test.js b/__tests__/index.test.js index 9698bd7..ac91a8c 100644 --- a/__tests__/index.test.js +++ b/__tests__/index.test.js @@ -1,4 +1,4 @@ -const { configureEnvironment, EnvironmentMisconfigurationError } = require("../src"); +const { configureEnvironment, EnvironmentMisconfigurationError, LSTK_MIGRATION_URL, printDeprecationNotice } = require("../src"); describe("configureEnvironment", () => { test("empty environment", () => { @@ -107,3 +107,37 @@ describe("configureEnvironment", () => { }); }); }); + +describe("printDeprecationNotice", () => { + let errorSpy; + let originalValue; + + beforeEach(() => { + errorSpy = jest.spyOn(console, "error").mockImplementation(() => {}); + originalValue = process.env.DISABLE_DEPRECATION_NOTICE; + delete process.env.DISABLE_DEPRECATION_NOTICE; + }); + + afterEach(() => { + errorSpy.mockRestore(); + if (originalValue === undefined) { + delete process.env.DISABLE_DEPRECATION_NOTICE; + } else { + process.env.DISABLE_DEPRECATION_NOTICE = originalValue; + } + }); + + test("prints the notice to stderr", () => { + printDeprecationNotice(); + expect(errorSpy).toHaveBeenCalledTimes(1); + const message = errorSpy.mock.calls[0][0]; + expect(message).toContain("WARNING: 'cdklocal' is deprecated. Use 'lstk cdk' instead."); + expect(message).toContain(`${LSTK_MIGRATION_URL}\n`); + }); + + test("can be turned off", () => { + process.env.DISABLE_DEPRECATION_NOTICE = "1"; + printDeprecationNotice(); + expect(errorSpy).not.toHaveBeenCalled(); + }); +}); diff --git a/bin/cdklocal b/bin/cdklocal index 9bdd05a..73a630f 100755 --- a/bin/cdklocal +++ b/bin/cdklocal @@ -11,7 +11,7 @@ const net = require('net'); const semver = require('semver'); const { spawnSync } = require('child_process'); -const { isEnvTrue, EDGE_PORT, PROTOCOL, configureEnvironment } = require(path.resolve(__dirname, "..", "src")); +const { isEnvTrue, EDGE_PORT, PROTOCOL, configureEnvironment, printDeprecationNotice } = require(path.resolve(__dirname, "..", "src")); const pkg = require(path.resolve(__dirname, "..", "package.json")); const cdkCliVersion = getCdkCliVersion() @@ -534,6 +534,8 @@ const patchPost_2_14 = () => { } }; +printDeprecationNotice(); + // handle printing version information if (process.argv[2] === "--version" || process.argv[2] === "-v") { printVersion(); diff --git a/package-lock.json b/package-lock.json index 886d57e..10da448 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "aws-cdk-local", - "version": "3.0.4", + "version": "3.1.0", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "aws-cdk-local", - "version": "3.0.4", + "version": "3.1.0", "license": "Apache-2.0", "dependencies": { "diff": "^5.0.0", diff --git a/package.json b/package.json index 7d39cc4..2908d1e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "aws-cdk-local", "description": "CDK Toolkit for use with LocalStack", - "version": "3.0.4", + "version": "3.1.0", "main": "src/index.js", "bin": { "cdklocal": "bin/cdklocal" diff --git a/src/index.js b/src/index.js index e4ed8aa..a710e31 100644 --- a/src/index.js +++ b/src/index.js @@ -4,6 +4,36 @@ const DEFAULT_EDGE_PORT = 4566; const EDGE_PORT = process.env.EDGE_PORT || DEFAULT_EDGE_PORT; const PROTOCOL = isEnvTrue("USE_SSL") ? "https" : "http"; +const LSTK_DOCS_URL = "https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/"; +const LSTK_MIGRATION_URL = "https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/migration/#infrastructure-as-code"; + +// Point users to 'lstk cdk'. Goes to stderr to keep stdout clean. +const printDeprecationNotice = () => { + if (isEnvTrue("DISABLE_DEPRECATION_NOTICE")) { + return; + } + + const separator = "=".repeat(76); + console.error([ + separator, + " WARNING: 'cdklocal' is deprecated. Use 'lstk cdk' instead.", + separator, + "", + " 'cdklocal' no longer receives updates.", + "", + " Get started with 'lstk', the new LocalStack CLI:", + ` ${LSTK_DOCS_URL}`, + "", + " Switch your scripts and CI workflows to 'lstk cdk':", + ` ${LSTK_MIGRATION_URL}`, + "", + separator, + "", + "Continuing with 'cdklocal'...", + "", + ].join("\n")); +}; + class EnvironmentMisconfigurationError extends Error { constructor(message) { super(message); @@ -73,4 +103,6 @@ module.exports = { PROTOCOL, configureEnvironment, EnvironmentMisconfigurationError, + LSTK_MIGRATION_URL, + printDeprecationNotice, }; From b8f73a68fbeb4a9888f98eb5d9449c4257f896f3 Mon Sep 17 00:00:00 2001 From: Anisa Oshafi Date: Thu, 8 Oct 2026 17:38:55 +0200 Subject: [PATCH 2/2] Pin aws-cdk-lib to the template minimum in CDK version tests --- .github/workflows/test.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 66ae49e..dd4e5a2 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -125,6 +125,10 @@ jobs: working-directory: ${{env.WORK_DIR}} run: | source .venv/bin/activate + if [ -n "${{ matrix.cdk-version }}" ]; then + # pin aws-cdk-lib to the lowest version the template allows, since newer libs can need a newer CLI + sed -i 's/^aws-cdk-lib>=\([0-9.]*\),.*/aws-cdk-lib==\1/' requirements.txt + fi pip install -r requirements.txt - name: Run bootstrap