EXAMPLE: Splitting a Monolithic CDK App Into Reusable Stacks

Example post — This is placeholder content to preview how a post in this space would look. Not a real article.

You start with one Stack that does everything: VPC, ECS, RDS, SQS, and a dozen Lambda functions. It deploys, but every change runs a full diff and your team is stepping on each other. Splitting the app into smaller stacks is the right move — but CDK’s physical IDs mean that moving a construct between stacks usually wants to replace the resource, which can mean data loss or downtime.

Here’s the approach that’s worked for me.

Keep construct IDs stable

When you move a construct from MainStack to NetworkStack, CDK generates a new logical ID by default (it includes the stack path). That new ID implies a new physical resource. To avoid that:

  • Don’t change the construct’s id when moving it.
  • Do pass the construct by reference (e.g. vpc: IVpc) from the stack that owns it into stacks that need it, so only one stack creates it.

Once the construct lives in one stack and others receive it via props, you’re no longer “moving” it — you’re just refactoring where it’s defined. The logical (and physical) ID stays the same.

Use a clear stack boundary

A practical split I use:

  1. Network stack — VPC, subnets, security groups that nothing else creates.
  2. Data stack — RDS, DynamoDB, S3 buckets. Depends on network.
  3. Compute stack — ECS, Lambdas, queues. Depends on network and optionally data.

Dependency is “pass in the IVpc or ITable” — no cross-stack references for things that change often, or you’ll hit export/import limits and deployment ordering headaches.

What to do next

  • Export the VPC (or other shared bits) from the network stack.
  • In the app’s main.ts, instantiate stacks in order and pass the exported objects as props.
  • Run cdk diff and confirm you see no “Replacement” for resources that must stay. Fix any that do by keeping the original construct ID in the stack that now owns it.

This keeps your CDK app maintainable without big-bang rewrites. When you’re ready to retire this example, replace it with a real post or delete it.