aws-cdk-local

When using CDK >= 2.177.0 with remote LocalStack endpoints (e.g., *.sandbox.localstack.cloud), asset uploads to S3 require path-style URLs because wildcard TLS certificates do not cover virtual-hosted-style bucket addresses (e.g., <bucket>.abc.sandbox.localstack.cloud).

cdklocal automatically enables path-style S3 if it detects a .sandbox. hostname in AWS_ENDPOINT_URL. You can also force this behavior manually using AWS_S3_FORCE_PATH_STYLE=1.

To use the AWS CDK with LocalStack, you must install both the aws-cdk-local wrapper and the standard aws-cdk library. Since version 1.65.2, aws-cdk must be installed manually to allow for decoupled version management.

Use the following command to install both globally via npm:

$ npm install -g aws-cdk-local aws-cdk

To verify your installation, you can generate and deploy a sample application.

1. Ensure LocalStack is running: localstack start.
2. Initialize a sample app using cdklocal init.
3. Deploy the app using cdklocal deploy.
4. Verify resources using awslocal (from the awscli-local package).

# 1. Setup directory and initialize sample app
$ mkdir /tmp/test; cd /tmp/test
$ cdklocal init sample-app --language=javascript

# 2. Ensure LocalStack is running
$ localstack start

# 3. Deploy
$ cdklocal deploy

# 4. Inspect resources (requires awslocal)
$ awslocal sns list-topics

You can control how cdklocal interacts with LocalStack using several environment variables.

Note for CDK >= 2.177.0: cdklocal automatically sanitizes the environment by removing variables like AWS_PROFILE to prevent conflicts. If you need to pass specific AWS configuration variables (like AWS_REGION) to the underlying CDK command, you must use the AWS_ENVAR_ALLOWLIST variable.

# Example: Allowing specific variables to pass through to the CDK command
$ AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal deploy

When LAMBDA_MOUNT_CODE=1 is set, cdklocal changes how Lambda assets are handled during synth and deploy:

1. Symlinking: It creates symlinks in cdk.out/asset.lambda.<function_name> pointing to your local source code.
2. Parameter Injection: It modifies the CloudFormation template parameters (specifically those containing S3VersionKey) to point to the local file path instead of an S3 location.
3. Skipping Uploads: It intercepts the FileAssetHandler.publish method to skip the actual upload of zipped Lambda assets to S3, as they are intended to be mounted locally.

This is particularly useful for rapid iteration on Lambda function logic.

export LAMBDA_MOUNT_CODE=1
cdklocal deploy

cdklocal is a wrapper around the standard AWS CDK CLI. It intercepts CDK calls and redirects them to a LocalStack instance by patching the underlying SDK providers, credentials, and toolkit information. This allows you to use standard CDK commands (like deploy, synth, diff) while targeting LocalStack instead of real AWS services.

To use it, ensure you have aws-cdk installed in your environment, then replace the cdk command with cdklocal.

# Instead of:
cdk deploy

# Use:
cdklocal deploy

If you installed AWS CDK via Homebrew on macOS, cdklocal might fail with a MODULE_NOT_FOUND error. To fix this, you must set the NODE_PATH environment variable to point to the AWS CDK node_modules directory within the Homebrew Cellar.

Replace <CDK_VERSION> with your specific installed version:

$ export NODE_PATH=$NODE_PATH:/opt/homebrew/Cellar/aws-cdk/<CDK_VERSION>/libexec/lib/node_modules

The isEnvTrue utility function checks if a specific environment variable is set to a truthy string value. A value is considered true if it is exactly "1" or "true".

const { isEnvTrue } = require('aws-cdk-local');

// Returns true if process.env.USE_SSL is "1" or "true"
const useSsl = isEnvTrue("USE_SSL");

The following constants are exported by the package:

• EDGE_PORT: The port used to access the LocalStack edge proxy. Defaults to 4566 or the value of the EDGE_PORT environment variable.
• PROTOCOL: The network protocol used for endpoints. It is "https" if the USE_SSL environment variable is set to "1" or "true", otherwise it defaults to "http".