cdk watch - AWS Cloud Development Kit (AWS CDK) v2
UsageArgumentsOptionsExamples

This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

cdk watch

Continuously watch a local AWS CDK project for changes to perform deployments and hotswaps.

This command is similar to cdk deploy, except that it can perform continuous deployments and hotswaps through a single command.

This command is a shortcut for cdk deploy --watch.

To end a cdk watch session, interrupt the process by pressing Ctrl+C.

The files that are observed is determined by the "watch" setting in your cdk.json file. It has two sub-keys, "include" and "exclude", that accepts a single string or an array of strings. Each entry is interpreted as a path relative to the location of the cdk.json file. Both * and ** are accepted.

If you create a project using the cdk init command, the following default behavior is configured for cdk watch in your project’s cdk.json file:

  • "include" is set to "**/*", which includes all files and directories in the root of the project.

  • "exclude" is optional, except for files and folders already ignored by default. This consists of files and directories starting with ., the CDK output directory, and the node_modules directory.

The minimal setting to configure watch is "watch": {}.

If either your CDK code or application code requires a build step before deployment, cdk watch works with the "build" key in the cdk.json file.

Note

This command is considered experimental and may have breaking changes in the future.

The same limitations of cdk deploy --hotswap applies to cdk watch. For more information, see cdk deploy --hotswap.

Usage

$ cdk watch <arguments> <options>

Arguments

CDK stack ID

The construct ID of the CDK stack from your app to watch.

Type: String

Required: No

Options

For a list of global options that work with all CDK CLI commands, see Global options.

--build-exclude, -E ARRAY

Do not rebuild asset with the given ID.

This option can be specified multiple times in a single command.

Default value: []

--change-set-name STRING

The name of the CloudFormation change set to create.

--concurrency NUMBER

Deploy and hotswap multiple stacks in parallel while accounting for inter-stack dependencies. Use this option to speed up deployments. You must still factor in CloudFormation and other AWS account rate limiting.

Provide a number to specify the maximum number of simultaneous deployments (dependency permitting) to perform.

Default value: 1

--exclusively, -e BOOLEAN

Only deploy requested stacks and don't include dependencies.

--force, -f BOOLEAN

Always deploy stacks, even if templates are identical.

Default value: false

--help, -h BOOLEAN

Show command reference information for the cdk watch command.

--hotswap BOOLEAN

By default, cdk watch uses hotswap deployments when possible to update your resources. The CDK CLI will attempt to perform a hotswap deployment and will not fall back to a full CloudFormation deployment if unsuccessful. Any changes detected that cannot be updated through a hotswap are ignored.

Default value: true

--hotswap-fallback BOOLEAN

By default, cdk watch attempts to perform hotswap deployments and ignores changes that require CloudFormation deployments. Provide --hotswap-fallback to fall back and perform a full CloudFormation deployment if the hotswap deployment is unsuccessful.

--logs BOOLEAN

By default, cdk watch monitors all CloudWatch log groups in your application and streams the log events locally to stdout.

Default value: true

--progress STRING

Configure how the CDK CLI displays deployment progress.

  • bar – Display stack deployment events as a progress bar, with the events for the resource currently being deployed.

  • events – Provide a complete history, including all CloudFormation events.

You can also configure this option in the project’s cdk.json file or at ~/.cdk.json on your local development machine:

{
   "progress": "events"
}

Valid values: bar, events

Default value: bar

--rollback BOOLEAN

During deployment, if a resource fails to be created or updated, the deployment will roll back to the latest stable state before the CDK CLI returns. All changes made up to that point will be undone. Resources that were created will be deleted and updates that were made will be rolled back.

Use --no-rollback or -R to deactivate this behavior. If a resource fails to be created or updated, the CDK CLI will leave changes made up to that point in place and return. This may be helpful in development environments where you are iterating quickly.

Note

When false, deployments that cause resource replacements will always fail. You can only use this value for deployments that update or create new resources.

Default value: true

--toolkit-stack-name STRING

The name of the existing CDK Toolkit stack.

By default, cdk bootstrap deploys a stack named CDKToolkit into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.

The CDK CLI uses this value to verify your bootstrap stack version.

Examples

Watch a CDK stack with logical ID DevelopmentStack for changes

$ cdk watch DevelopmentStack
Detected change to 'lambda-code/index.js' (type: change). Triggering 'cdk deploy'
DevelopmentStack: deploying...

 ✅  DevelopmentStack

Configure a cdk.json file for what to include and exclude from being watched for changes

{
   "app": "mvn -e -q compile exec:java",
   "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
   }
}

Build a CDK project using Java before deployment by configuring the cdk.json file

{
  "app": "mvn -e -q exec:java",
  "build": "mvn package",
  "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
  }
}