Show a deprecation notice that points to lstk cdk

.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

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)

__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();
+  });
+});

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();

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"

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,
 };