fix(cli): cdk watch glob pattern support broken after chokidar v3 -> v4 upgrade

[iankhou]

Fixes #1126

Description

The cdk watch command stopped working correctly after upgrading to CDK CLI v2.1100.1+. File changes were not being detected, causing watch mode to appear broken.

Root Cause

Chokidar v4 removed built-in glob pattern support. The CDK CLI was passing glob patterns like **, **/*.ts directly to chokidar.watch(), which no longer expands them. Instead, chokidar v4 treats these as literal file paths.

Solution

Use picomatch library to handle glob pattern matching. The fix created a createIgnoreMatcher utility in toolkit-lib that:

• Takes include/exclude glob patterns and rootDir
• Returns an ignored function for chokidar that filters files based on patterns
• Normalizes directory names to glob patterns (e.g., my-dir → my-dir/**) for backward compatibility
• Updated watch implementations in both toolkit-lib and aws-cdk:
• Changed chokidar.watch(patterns, ...) to chokidar.watch('.', { ignored: fn, cwd: rootDir })

Fixed default include pattern in aws-cdk:

• Changed from returning absolute rootDir path to ** glob pattern
• Chokidar reports relative paths, so absolute patterns never matched
• API Compatibility

This is a backwards-compatible change and there were no changes to the public API. Users continue to configure watch the same way in cdk.json:

{
  "watch": {
    "include": ["**/*.ts", "**/*.js"],
    "exclude": ["node_modules/**", "cdk.out/**"]
  }
}

Testing

• Manual verification using the built cdk binary; verified that the currently released version does not work, then verified the new changes function as expected, and behave the same as versions before 2.1100.1 (see logs)
• Added unit tests for createIgnoreMatcher including pattern normalization
• Added unit tests for chokidar configuration in toolkit-lib
• Updated watch tests in aws-cdk to verify filtering behavior

Logs

Tested on MacOS. Initialized a new CDK app and ran cdk watch using CDK CLI v2.1100.0 (version before cdk watch stopped working). See annotated logs.

Logs from cdk watch using CDK CLI v2.1100.0 (previously working version) in a sample project

$ cdk watch
'watch' is observing directory '' for changes
'watch' is observing directory 'bin' for changes
'watch' is observing directory 'lib' for changes
'watch' is observing the file 'bin/new-app.ts' for changes
'watch' is observing the file 'lib/new-app-stack.ts' for changes
Triggering initial 'cdk deploy'

✨  Synthesis time: 5.01s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 1.04s


 ✅  NewAppStack (no changes)

✨  Deployment time: 2.84s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 7.85s

Here, I create a new file called track-me-please, to verify watch redeploys the app

Detected change to 'track-me-please' (type: add). Triggering 'cdk deploy'

✨  Synthesis time: 3.18s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 0.79s


 ✅  NewAppStack (no changes)

✨  Deployment time: 1.67s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 4.85s

Here, I make a change to lib/new-app-stack.ts to verify watch redeploys the app

Detected change to 'lib/new-app-stack.ts' (type: change). Triggering 'cdk deploy'

✨  Synthesis time: 2.97s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 1.02s


 ✅  NewAppStack (no changes)

✨  Deployment time: 2.11s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 5.08s

During this run, I also create a file called .dont-track-me and make a change to test/new-app.test.ts. Neither of these changes result in a deployment. This validates that these files are properly ignored.

Then, I ran cdk watch using my locally built cdk (new changes). See annotated logs.

Logs from cdk watch using locally built CDK CLI in a sample project

Note that these logs immediately follow the logs above.

$ /Users/ianhou/workplace/aws-cdk-cli/packages/aws-cdk/bin/cdk watch
'watch' is observing directory '' for changes
'watch' is observing the file 'track-me-please' for changes
'watch' is observing directory 'bin' for changes
'watch' is observing directory 'lib' for changes
'watch' is observing the file 'lib/new-app-stack.ts' for changes
'watch' is observing the file 'bin/new-app.ts' for changes
Triggering initial 'cdk deploy'

✨  Synthesis time: 4.29s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 0.8s


 ✅  NewAppStack (no changes)

✨  Deployment time: 2.72s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 7s

Here, I create a new file called track-me-too. watch deploys, as expected.

Detected change to 'track-me-too' (type: add). Triggering 'cdk deploy'

✨  Synthesis time: 3.12s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 0.92s


 ✅  NewAppStack (no changes)

✨  Deployment time: 1.96s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 5.08s

Here, I make a change to lib/new-app-stack.ts, which triggers a deployment, as expected.

Detected change to 'lib/new-app-stack.ts' (type: change). Triggering 'cdk deploy'

✨  Synthesis time: 3.02s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 1.24s


 ✅  NewAppStack (no changes)

✨  Deployment time: 2.2s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 5.23s

I also verified that the latest version of the CDK CLI does not track files correctly. Below are the logs, which show no activity, even though I made several file changes. The logs also do not indicate that watch is tracking any files.

$ cdk --version
2.1105.0 (build 3e25a4e)

$ cdk watch
Triggering initial 'cdk deploy'

✨  Synthesis time: 3.94s

⚠️ The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
⚠️ They should only be used for development - never use them for your production Stacks!

NewAppStack: deploying... [1/1]

✨  hotswap-deployment time: 1.18s


 ✅  NewAppStack (no changes)

✨  Deployment time: 3.23s

Stack ARN:
arn:aws:cloudformation:us-east-1:229816860325:stack/NewAppStack/c76b2220-07b8-11f1-b773-0e04b5bd43cd

✨  Total time: 7.17s

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.72%. Comparing base (756d6c2) to head (e9c629b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1134      +/-   ##
==========================================
+ Coverage   87.71%   87.72%   +0.01%     
==========================================
  Files          72       72              
  Lines       10116    10129      +13     
  Branches     1337     1337              
==========================================
+ Hits         8873     8886      +13     
  Misses       1217     1217              
  Partials       26       26              

Flag	Coverage Δ
suite.unit	87.72% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[iankhou]

new-app.zip
See attached the app that I used to test my changes. I removed node_modules, as that made the upload too big.