RFC for CDK LSP and Web Explorer by megha-narayanan · Pull Request #923 · aws/aws-cdk-rfcs

megha-narayanan · 2026-05-22T19:19:27Z

Add RFC for CDK LSP and Web Explorer tools to enhance CDK development experience.

This is a request for comments about CDK LSP and Web Explorer. See #920 for
additional details.

APIs are signed off by @ShadowCat567.

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

Add RFC for CDK LSP and Web Explorer tools to enhance CDK development experience.

… spaces

kaizencc

nice! a few comments here and there

kaizencc · 2026-05-28T20:40:30Z

+Wireframe:
+![Wireframe Design](../images/WebExplorerWireframe.png)
+
+Clicking any element in one panel highlights the corresponding elements in the other two. Click a


hmm: for your actual readme, consider embedding a video/demo of going through the site

kaizencc · 2026-05-28T20:41:39Z

+construct in the tree to see which CloudFormation resources it produces and which line of code created it. Click a resource in the template to jump to
+the CDK code that generated it.
+
+A violations sidebar shows offline validation findings grouped by severity. Clicking a violation navigates all three panels to the relevant construct.


potential extension: if the violation has a suggested fix, maybe we can add a "click to fix" UI button

added to extensions section

kaizencc · 2026-05-28T20:43:11Z

+#### Limitations
+
+* Re-synthesis on save depends on synth speed; large apps (50+ stacks) may take 10-30s to refresh
+* The explorer is read-only — it does not modify source files or deploy resources


any specific reason why? i feel like a "click to deploy" button might be a natural move after visualization, although that might be closer to cdk-as-a-service

click to deploy is a good point, I'll add that to extensions! see next comment about being read-only

kaizencc · 2026-05-28T20:45:35Z

+
+### Do I need AWS credentials?
+
+No. Both tools work entirely offline by reading the synthesized cloud assembly (`cdk.out/`).  


synthesis uses aws credentials though

i think we talked about this briefly in my RFC meeting: for stuff like lookups which do require credentials, synth won't fail. I think keeping this credential-free is useful

kaizencc · 2026-05-28T20:52:06Z

+source-linking and violation annotations. By end of Phase 3, VS Code users can click constructs to navigate to source, see violations as tree
+annotations, and access construct-to-resource mappings natively.
+
+#### Features


nit: what do the P0, P1 labels stand for? If they are priority, you should say so and also we typically don't have that many distinct priorities. I think perhaps you mean milestones? if so lets make it clear that M0 is prework, M1 is MVP, M2 is improvements, etc

yep, i did mean priority, but I'll make it milestones.

kaizencc · 2026-05-28T20:52:35Z

+
+### What are the drawbacks of this solution?
+
+* **Synth latency as a bottleneck.** The CDK LSP's data comes from the cloud assembly, which requires running the entire CDK app. For large apps,


how will we communicate that the app is out of date?

There's a staleness indicator in the wireframe below the synth button.

9pace · 2026-05-28T22:35:24Z

+A violations sidebar shows offline validation findings grouped by severity. Clicking a violation navigates all three panels to the relevant construct.
+The explorer watches your source files and re-synthesizes automatically on save.  While synthesis is running, a progress indicator appears. If
+synthesis fails, the explorer shows the failure and continues displaying the last successful results. A timestamp shows when data was last refreshed;
+if source files have been modified since, a staleness warning appears. A manual "Synth now" button is available for forced refresh or when auto-synth


Where do I disable autosynth

Let me add a toggle in the wireframe, and an option to startup

9pace · 2026-05-28T22:41:27Z

+
+#### AI Agent Integration
+
+In Claude Code, install the CDK LSP plugin or add to your `.lsp.json`:


i dislike that there are so many sources of truth for "how should i configure my agents to do cdk." Maybe it can be bundled with aws agent-toolkit

9pace · 2026-05-28T23:06:14Z

+* **Validation report schema stabilization.** The `policy-validation-report.json` schema is not yet part of the versioned cloud assembly schema
+  (`cdklabs/cloud-assembly-schema`). This is pending and expected to be resolved by project launch.
+
+## Appendix


i would like something along the lines of: what is out of scope / what are good follow up issues or improvements (or could fold this into '### Are there any open issues that need to be addressed later?' section if you want). for example:

non-ts LSP diagnostic support

fix button on violations

other ui ideas that are interesting but not planned

Added this section at the end of the doc

9pace · 2026-05-29T19:55:11Z

+* **Asset exploration.** Surface asset metadata (size, type, connected resources) through the LSP and web explorer.
+* **Feature flags management.** Display and manage feature flag state from the web explorer.
+* **Online validation.** Trigger online validation from the explorer or editor. Requires AWS credentials and surfaces account-specific findings.
+* **AI-powered quick fixes.** Using an AI model to generate fixes for violations based on structured context (rule name, construct path, resource


is this different than Click-to-fix UI for violations or do they work the same way and you are just separating ui from functionality

yeah, just separating UI from functionality. the click to fix button was more about adding fixes to the web explorer (which in the MVP is completely read-only) and this point is more about hooking that button up to a model with context to do dynamic fixes, rather than just deterministic very simple fixes without AI.

ShadowCat567 · 2026-06-10T16:54:25Z

+* **API Bar Raiser**: @ShadowCat567
+
+CDK developers cannot see what their code creates, discover deployment failures too late, and must jump between disconnected tools to debug. The CDK
+LSP and Web Explorer close this gap by surfacing construct-to-resource mappings, validation diagnostics, and three-way linked navigation directly in


Can you elaborate a bit more on what tools users would have to use to debug with the current CDK experience? Another thing to consider is currently users may have to run several different commands and dig through their Cloudformation templates to get info that is surface automatically be the explorer/LSP.
Can you also explain a but what the 3-way linked navigation is since at this point it is very mysterious.

Yep, added a couple sentences spelling this out

ShadowCat567 · 2026-06-10T17:05:00Z

+* Had to repeatedly run `cdk synth` to check for validation errors while iterating on code
+* Struggled to trace from a CloudFormation error back to the CDK code that caused it
+
+These tools close that gap. The explorer gives you a visual map of your entire app. The LSP gives you immediate feedback while writing code without


I want you to dig a bit deeper and explain how the Web Explorer and LSP addresses these bullet points, this would also be a good opportunity to talk about other cool things you have planned for the Web Explorer and LSP server.
(essentially, I want to see you rephrase the above section of what we are launching with a focus on how exactly what we are launching helps fix customer pain points)

will do, redid this responding to each point directly and also added a sentence on future features we have planned

ShadowCat567 · 2026-06-10T17:16:05Z

+
+### Why should we *not* do this?
+
+**Why build both an LSP server and a web interface?** Maintaining two UI surfaces adds complexity. However, the two tools serve fundamentally


This doesn't really explain why we might not want to do this. I think you could lead this section with Why not only build the web explorer? and hit a lot of the same points (based on your alternatives introduced later it might be better to think about this second option). Or Why build these tools at all?, they add operational burden for us and no one has really been asking for them, what makes you think the usefulness of these tools is worth the cost of building them?
I think this section could be made stronger if you focused on a different question here

got it, rephrased this section that way

ShadowCat567 · 2026-06-10T17:31:11Z

+The web explorer is launchable from the CDK CLI, which is IDE-agnostic and accessible to all customers. The LSP integrates into VSCode via the AWS
+Toolkit plugin, and the Toolkit's existing CDK tree view is enhanced with source-linking and violation annotations.
+
+Functionality will be built as new packages here: https://github.com/aws/aws-cdk-cli/tree/main/packages


you could also say 'Functionality will be build as a new package in the CDK CLI.' but this also works.

ShadowCat567 · 2026-06-10T17:34:53Z

+* **VSCode extension:** an AWS Toolkit integration that spawns `cdk lsp` and connects as a standard LSP client
+
+**Cloud assembly as the data layer**
+The LSP server reads from the cloud assembly (`cdk.out/`) produced by `cdk synth`. This gives it a consistent, offline data source with no credentials


Can you make it a bit more clear that the LSP uses the shared core to interpret the below files. I also think your design has changed a bit since you last touched this section so can you discuss the updates you made?

got it, yep, redid to reflect the new architecture

ShadowCat567 · 2026-06-10T17:35:38Z

+The web explorer adds visual, navigable context that a flat JSON report cannot provide — clicking through the construct tree to see what a line of
+code produces is qualitatively different from reading a validation report.
+
+### What is the technical solution (design) of this feature?


How are we keeping the synth fresh? Are we getting synth data from cdk synth/cdk deploy?

added a section on this. we don't run deploy, but yes, data comes from synth

- Expand intro with the current debug workflow and define three-way linked navigation - Map customer pain points to LSP/Explorer capabilities and add planned extensions - Reframe the why-not section around 'Why not only build the web explorer?' - Clarify the shared core library interprets the cloud assembly, and that the web explorer now embeds the core directly instead of spawning cdk lsp over JSON-RPC - Move file watching, synth triggering, and caching to the shared core - Add a 'Keeping the data fresh' note (data comes from cdk synth, not cdk deploy)

RFC for CDK LSP and Web Explorer

061f942

Add RFC for CDK LSP and Web Explorer tools to enhance CDK development experience.

megha-narayanan marked this pull request as draft May 22, 2026 19:20

Fix markdownlint violations: wrap lines to 150 chars, remove trailing…

de69e01

… spaces

megha-narayanan marked this pull request as ready for review May 22, 2026 19:31

megha-narayanan assigned megha-narayanan and unassigned megha-narayanan May 22, 2026

Megha Narayanan and others added 2 commits May 26, 2026 09:53

remove quip link and add image

4d1d0ee

update API Bar Raiser

c32aee9

kaizencc reviewed May 28, 2026

View reviewed changes

9pace reviewed May 28, 2026

View reviewed changes

respond to comments

8734224

megha-narayanan requested review from 9pace and kaizencc May 29, 2026 17:53

9pace reviewed May 29, 2026

View reviewed changes

ShadowCat567 reviewed Jun 10, 2026

View reviewed changes

megha-narayanan requested a review from ShadowCat567 June 11, 2026 19:06


		### Do I need AWS credentials?

		No. Both tools work entirely offline by reading the synthesized cloud assembly (`cdk.out/`).


		### What are the drawbacks of this solution?

		* Synth latency as a bottleneck. The CDK LSP's data comes from the cloud assembly, which requires running the entire CDK app. For large apps,


		#### AI Agent Integration

		In Claude Code, install the CDK LSP plugin or add to your `.lsp.json`:


		### Why should we not do this?

		Why build both an LSP server and a web interface? Maintaining two UI surfaces adds complexity. However, the two tools serve fundamentally

Conversation

megha-narayanan commented May 22, 2026 • edited by ShadowCat567 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kaizencc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

megha-narayanan May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

megha-narayanan commented May 22, 2026 •

edited by ShadowCat567

Loading

megha-narayanan May 29, 2026 •

edited

Loading