aws-cdk
The command-line half of AWS Cloud Development Kit. An application written with AWS construct libraries produces a cloud assembly; the aws-cdk executable synthesizes it into CloudFormation, compares it with deployed stacks, publishes file and container assets, creates change sets, deploys, watches, imports, rolls back and destroys infrastructure. This npm package provides the cdk command. It is not the aws-cdk-lib construct library imported by a TypeScript application.
The default toolkit for teams committed to AWS CDK and willing to treat infrastructure as an executable application. Pin it locally, inspect synthesized templates and change sets, and keep production deployments on full CloudFormation rather than hotswap.
Use it if
- Your infrastructure is primarily AWS and your team wants to model CloudFormation resources in TypeScript, JavaScript, Python, Java, C# or Go
- You need a supported CLI for synth, diff, bootstrap, asset publishing, change sets, deployment, drift checks and teardown
- You want reusable higher-level constructs while retaining synthesized CloudFormation templates as the deployment mechanism
- You need the current toolkit to deploy cloud assemblies produced by the same or older supported construct-library releases
- You need one infrastructure language across several cloud providers: the toolkit provisions through AWS CloudFormation and its core abstractions remain AWS-specific
- Your security team will not permit CDK bootstrap resources and deployment roles in each target account and region; asset-heavy deployments depend on that toolkit stack
- You want a tiny declarative stack with no application runtime or build step: direct CloudFormation, SAM or Terraform can be easier to review than executing a CDK app to discover its template
- You expect hotswap to preserve CloudFormation as the source of truth: the README says hotswap updates supported resources directly and uses current credentials, which intentionally creates temporary drift
- You want to call deployment functions from application code: the package export map exposes the CLI and a few assets, while AWS directs programmatic consumers to @aws-cdk/toolkit-lib
Setup reality
Install aws-cdk as a project dev dependency and run it through npx so CI and teammates use the pinned CLI. Version 2.1135.1 requires Node 18 or newer, but the CDK app itself also needs a language runtime and its own construct library such as aws-cdk-lib. The project needs cdk.json with an app command that can compile or execute the program. AWS credentials must resolve through environment variables, a named profile, IAM role, SSO or another SDK provider, and the chosen identity needs CloudFormation plus the permissions required for lookups, bootstrap and deployment. Run cdk bootstrap separately for every account and region that will receive assets or use modern synthesis. Bootstrap creates the CDKToolkit stack, roles, an S3 bucket and commonly an ECR repository, so review its trust and execution policies before granting cross-account access. Synthesis writes cdk.out and can run local bundlers or Docker for assets. Context lookups may contact AWS and cache values in cdk.context.json; commit intentional context so CI does not synthesize a different template, then refresh it deliberately. Diff is not automatically a deployment gate unless you use --fail, and template-only diff can misclassify replacements. Deploy can prompt for security changes, which means CI must choose an explicit approval policy. Hotswap is for development, not production. The CLI version now advances independently from aws-cdk-lib, so use the compatibility table or, more simply, keep the CLI current because newer toolkits read older cloud-assembly schemas.
Patterns
Pin the CDK CLI in a projectinstall-local-cli
npm install --save-dev aws-cdk
npx cdk --versionA local dev dependency makes CI and developer machines use the same CLI. The aws-cdk package is the command, not the aws-cdk-lib constructs imported by your app.
Create a TypeScript CDK applicationinitialize-project
mkdir orders-infra
cd orders-infra
npx cdk init app --language typescriptcdk init expects an empty directory and creates package, compiler, test and cdk.json files. Review generated dependency versions before adopting it in an existing monorepo.
Tell the CLI how to run the appconfigure-app-command
{
"app": "npx tsx bin/orders.ts",
"output": "cdk.out",
"context": {
"environment": "development"
}
}Save this as cdk.json. The app command is executed during synth, diff and deploy, so it must be deterministic and available in CI.
Bootstrap one AWS account and regionbootstrap-environment
AWS_PROFILE=platform npx cdk bootstrap aws://123456789012/us-east-1Bootstrap mutates the account by creating the CDKToolkit CloudFormation stack and deployment resources. Review trust and execution policies before cross-account use.
Synthesize a stack without deployingsynthesize-template
npx cdk synth OrdersStack --quiet
# inspect the complete cloud assembly
find cdk.out -maxdepth 1 -type f -printSynthesis can perform AWS context lookups and local or Docker asset bundling. It is not necessarily an offline or side-effect-free compile.
List stacks as machine-readable datalist-stacks
npx cdk list --long --jsonUse --json for scripts. Pipeline stages can expose hierarchical stack paths, so top-level --all does not necessarily select every nested stack.
Fail CI when infrastructure differsgate-on-diff
npx cdk diff OrdersStack --method=change-set --failA change-set diff needs deployment permissions but gives more accurate replacement information. Template-only diff is faster and can report cosmetic changes as replacements.
Deploy one stack with explicit approval policydeploy-reviewed-stack
npx cdk deploy OrdersStack \
--require-approval broadening \
--progress events \
--outputs-file cdk-outputs.jsonCI should choose its approval policy explicitly. Use never only after an external review gate because it suppresses interactive confirmation for security-sensitive changes.
Separate change-set creation from executionprepare-change-set
npx cdk deploy OrdersStack \
--method=prepare-change-set \
--change-set-name reviewed-release
# after external approval
npx cdk deploy OrdersStack \
--method=execute-change-set \
--change-set-name reviewed-releaseexecute-change-set skips asset publishing and change-set creation. Ensure the first step already published every referenced asset before approval.
Inspect and deliberately refresh cached contextrefresh-context
npx cdk context
npx cdk context --reset 3
npx cdk synth OrdersStackLookups are cached in cdk.context.json. Commit intentional values for repeatable CI, and reset only the keys you mean to query again.
Watch a development stack with fallbackwatch-development-stack
AWS_PROFILE=developer npx cdk watch DevStack --hotswap-fallbackHotswap bypasses CloudFormation for supported changes, uses current AWS credentials directly and creates drift. Restrict it to disposable development environments.
Destroy an explicitly named stackdestroy-stack
npx cdk destroy DevStack --forceThis deletes CloudFormation-managed resources without prompting. Retained resources, non-empty buckets and data-protection policies can leave resources behind or block deletion.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| @pulumi/pulumi | npm | Choose it for general-purpose language infrastructure across AWS and other clouds with Pulumi's state and provider model |
| cdktf | npm | Choose it when you want TypeScript or another supported language but must stay in the Terraform provider and state ecosystem |
| serverless | npm | Choose it for function-centered AWS applications where API Gateway, Lambda and event wiring dominate the stack |