{"id":13561837,"url":"https://github.com/localstack/aws-cdk-local","last_synced_at":"2025-04-04T02:06:03.997Z","repository":{"id":37258973,"uuid":"304708454","full_name":"localstack/aws-cdk-local","owner":"localstack","description":"Thin wrapper script for using the AWS CDK CLI with LocalStack","archived":false,"fork":false,"pushed_at":"2023-04-04T08:06:41.000Z","size":125,"stargazers_count":246,"open_issues_count":10,"forks_count":17,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-04-24T08:16:29.338Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-10-16T18:28:33.000Z","updated_at":"2024-04-11T01:30:03.000Z","dependencies_parsed_at":"2024-01-14T03:44:51.521Z","dependency_job_id":"7a22f5a5-af38-4814-8218-f42a55964fa6","html_url":"https://github.com/localstack/aws-cdk-local","commit_stats":{"total_commits":23,"total_committers":9,"mean_commits":"2.5555555555555554","dds":0.3913043478260869,"last_synced_commit":"348de148d30021bb611e9cdb1a8b8ce83d9a59a5"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Faws-cdk-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Faws-cdk-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Faws-cdk-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Faws-cdk-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/aws-cdk-local/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247107818,"owners_count":20884793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:01.843Z","updated_at":"2025-04-04T02:06:03.991Z","avatar_url":"https://github.com/localstack.png","language":"JavaScript","readme":"[![Integration Tests](https://github.com/localstack/aws-cdk-local/actions/workflows/build.yml/badge.svg)](https://github.com/localstack/aws-cdk-local/actions/workflows/build.yml)\n\n# AWS Cloud Development Kit (CDK) for LocalStack\n\nThis 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://github.com/localstack/localstack).\n\n**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.\n\n## Quick Installation\n\nThe `cdklocal` command line is published as an [npm library](https://www.npmjs.com/package/aws-cdk-local):\n```bash\n$ npm install -g aws-cdk-local aws-cdk\n...\n$ cdklocal --version\n1.65.5\n```\n\n**Note:** Starting with version `1.65.2`, the dependency `aws-cdk` needs to be installed manually\n(to decouple the two libraries, and allow using arbitrary versions of `aws-cdk` under the covers).\n\n(Note: Depending on your local setup, you may or may not have to use the global `npm` installation flag `-g` above.)\n\n### Mac OS specific `MODULE_NOT_FOUND` issue\nOn Mac OS, brew can be used to install AWS CDK, which might result in a `MODULE_NOT_FOUND` error from `cdklocal`.\nTo resolve this, set the `NODE_PATH` variable pointing to your AWS CDK's `node_module` folder to expand the lookup path for modules.\n```bash\n$ export NODE_PATH=$NODE_PATH:/opt/homebrew/Cellar/aws-cdk/\u003cCDK_VERSION\u003e/libexec/lib/node_modules\n```\n\n## Version support\n\n`cdklocal` supports all installed versions of the node `aws-cdk` package, however some complications are present for `aws-cdk \u003e= 2.177.0`.\n\nFor these CDK versions, we remove AWS configuration environment variables like `AWS_PROFILE` from the shell environment before invoking the `cdk` command, and explicitly set `AWS_ENDPOINT_URL` and `AWS_ENDPOINT_URL_S3` to target LocalStack.\n\n1. We do this because other environment variables may lead to a conflicting set of configuration options, where the wrong region is used to target LocalStack, or `cdklocal` tries to deploy into upstream AWS by mistake. If individual configuration variables are needed for the deploy process (e.g. `AWS_REGION`) these configuration variables can be propagated to the `cdk` command by configuring `AWS_ENVAR_ALLOWLIST`, for example: `AWS_ENVAR_ALLOWLIST=AWS_REGION,AWS_DEFAULT_REGION AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdklocal ...`.\n2. If you are manually setting `AWS_ENDPOINT_URL`, the new value will continue to be read from the environment, however `AWS_ENDPOINT_URL_S3` _must_ also be set and should include a `.s3.` component to ensure we correctly detect S3 requests.\n\n## Configurations\n\nThe following environment variables can be configured:\n\n* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below)\n* `AWS_ENDPOINT_URL_S3`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below) for S3 requests\n* `AWS_ENVAR_ALLOWLIST`: Allow specific `AWS_*` environment variables to be used by the CDK\n* `EDGE_PORT` (deprecated): Port under which LocalStack edge service is accessible (default: `4566`)\n* `LOCALSTACK_HOSTNAME` (deprecated): Target host under which LocalStack edge service is accessible (default: `localhost`)\n* `USE_SSL` (deprecated): Whether to use SSL to connect to the LocalStack endpoint, i.e., connect via HTTPS.\n* `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). Note: may require CDK version \u003c2.14.0 to be fully functional.\n* `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)\n\n## Deploying a Sample App\n\nThe CDK command line ships with a sample app generator to run a quick test for getting started:\n```bash\n$ mkdir /tmp/test; cd /tmp/test\n$ cdklocal init sample-app --language=javascript\n...\n```\n\nMake sure that LocalStack is installed and started up with the required services:\n```bash\n$ SERVICES=serverless,sqs,sns localstack start\n```\n\nThen deploy the sample app against the local APIs via the `cdklocal` command line:\n```bash\n$ cdklocal deploy\n...\nDo you wish to deploy these changes (y/n)? y\n...\nStack ARN:\narn:aws:cloudformation:us-east-1:000000000000:stack/TestStack/e3debc0a-311e-4968-8230-ed78f89cb614\n```\n\nOnce the deployment is done, you can inspect the created resources via the [`awslocal`](https://github.com/localstack/awscli-local) command line:\n```bash\n$ awslocal sns list-topics\n{\n    \"Topics\": [\n        {\n            \"TopicArn\": \"arn:aws:sns:us-east-1:000000000000:TestStack-TestTopic339EC197-79F43WWCCS4Z\"\n        }\n    ]\n}\n```\n\n## Change Log\n\n* 3.0.0: Sanitise environment of configuration environment variables before deployment\n* 2.19.2: Fix SDK compatibility with aws-cdk versions \u003e= 2.177.0\n* 2.19.1: Fix SDK compatibility with older CDK versions; Fix patched bucket location in TemplateURL\n* 2.19.0: Add support for aws-cdk versions \u003e= `2.167.0`\n* 2.18.1: Throw better exception if `aws-cdk` not found\n* 2.18.0: Add support for AWS_ENDPOINT_URL, USE_SSL, and BUCKET_MARKER_LOCAL configurations\n* 2.17.0: Fix IPv4 fallback check to prevent IPv6 connection issue with `localhost` on macOS\n* 2.16.0: Add check to prevent IPv6 connection issue with `localhost` on MacOS\n* 2.15.0: Fix issue with undefined BUCKET_NAME_OUTPUT variable; add CI build and eslint config\n* 2.14.0: Add switches in patches to accommodate new esbuild packaging mechanism in CDK v2.14.0+\n* 1.65.7: Add switch that checks for asset existence before symlinking assets; fix parsing fetched template body for JSON/YAML formats; add missing dependency to \"diff\" package\n* 1.65.6: Create symlinks to Lambda assets to enable persistent code mounting of Lambdas on \"cdklocal synth\"\n* 1.65.5: Add support for `LAMBDA_MOUNT_CODE` config to enable local Lambda code mounting\n* 1.65.4: Add support for large stacks by patching bucketUrl for ToolkitInfo\n* 1.65.2: Patch missing getPromise() in forceCredentialRetrieval; remove aws-cdk from npm dependencies\n* 1.65.1: Override BucketURL to use path style addressing\n* 1.65.0: Initial release\n\n## License\n\nThe AWS CDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Faws-cdk-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Faws-cdk-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Faws-cdk-local/lists"}