DEV Community

Dinesh_gowtham
Dinesh_gowtham

Posted on • Edited on

cdk type script migration silos

#serverless #cdk #typescript #aws

Our team spent 3 months migrating 27 CDK projects to TypeScript 5.5, only to discover a hidden issue that doubled our deployment time. We were not prepared for the isolatedDeclarations gotcha.

Introduction to CDK and TypeScript

CDK (Cloud Development Kit) is a popular framework for defining cloud infrastructure in code. TypeScript is a superset of JavaScript that adds optional static typing and other features. To get started with CDK and TypeScript, you need to install the required packages:

import { Command } from '@aws-sdk/client-cdk';
import * as cdk from 'aws-cdk-lib';

// Initialize the CDK Command
const command = new Command('init', {
  lang: 'typescript',
  app: 'my-app',
});

// Run the command
command.exec().then((output) => {
  console.log(output);
}).catch((error) => {
  console.error(error);
});
Enter fullscreen mode Exit fullscreen mode

Be aware that CDK bootstrap is required per account and region. Teams often forget to do this when moving to a new region, resulting in an error like ERROR: Failed to fetch the AWS account ID: No region specified.

The TypeScript 5.5 Upgrade

The recent TypeScript 5.5 update promises better type safety, but its effects on CDK projects are more complex than initially thought. To upgrade your CDK project to TypeScript 5.5, you need to update your package.json file:

import { readPackage } from 'read-pkg';

// Read the package.json file
readPackage('.').then((packageJson) => {
  // Update the TypeScript version
  packageJson.devDependencies['typescript'] = '^5.5';

  // Write the updated package.json file
  const fs = require('fs');
  fs.writeFileSync('package.json', JSON.stringify(packageJson, null, 2));
}).catch((error) => {
  console.error(error);
});
Enter fullscreen mode Exit fullscreen mode

Keep in mind that the isolatedDeclarations feature in TypeScript 5.5 can silently break CDK project builds if not properly configured. This can lead to an error like TypeError: Cannot read properties of undefined (reading 'constructor').

Migration Challenges

Migrating a CDK project to TypeScript 5.5 can be challenging, especially when dealing with large stacks. CDK deploy time for large stacks (500+ resources) can be painfully slow. Here's an example of how to benchmark the deploy time:

import * as cdk from 'aws-cdk-lib';
import { performance } from 'perf_hooks';

// Create a new CDK stack
const stack = new cdk.Stack();

// Add resources to the stack
for (let i = 0; i < 500; i++) {
  new cdk.aws_s3.Bucket(stack, `Bucket${i}`);
}

// Deploy the stack
const start = performance.now();
stack.deploy().then(() => {
  const end = performance.now();
  console.log(`Deploy time: ${end - start}ms`);
}).catch((error) => {
  console.error(error);
});
Enter fullscreen mode Exit fullscreen mode

Watch out for the 500 resource limit per stack. Large CDK apps can easily hit this limit, resulting in an error like ERROR: Stack resource limit exceeded (500). You can use CDK aspects to split resources into multiple stacks.

The isolatedDeclarations Gotcha

The isolatedDeclarations feature in TypeScript 5.5 can silently break CDK project builds if not properly configured. This is because CDK uses a lot of ambient declarations that are not isolated by default. To fix this issue, you need to add the following configuration to your tsconfig.json file:

{
  "compilerOptions": {
    // ... other options ...
    "isolatedModules": true,
    "moduleResolution": "node",
    "module": "commonjs"
  }
}
Enter fullscreen mode Exit fullscreen mode

Be aware that CDK token resolution means you can't use construct values in some contexts. This can lead to an error like TypeError: Cannot read properties of undefined (reading 'token').

Best Practices for CDK TypeScript Migrations

To avoid common pitfalls when migrating a CDK project to TypeScript 5.5, follow these best practices:

import * as cdk from 'aws-cdk-lib';

// Use explicit types for construct properties
interface MyConstructProps {
  readonly foo: string;
}

class MyConstruct extends cdk.Construct {
  public readonly foo: string;

  constructor(scope: cdk.Construct, id: string, props: MyConstructProps) {
    super(scope, id);
    this.foo = props.foo;
  }
}
Enter fullscreen mode Exit fullscreen mode

Keep in mind that CDK aspects fire after synth. Teams often try to use them to modify resources and fail, resulting in an error like ERROR: Aspect failed to execute.

The Takeaway

Here are some key takeaways from our experience migrating CDK projects to TypeScript 5.5:

  • Always configure isolatedDeclarations properly to avoid silent build breaks.
  • Watch out for the 500 resource limit per stack and use CDK aspects to split resources into multiple stacks if necessary.
  • Use explicit types for construct properties to avoid type errors.
  • Be aware of CDK token resolution limitations and avoid using construct values in some contexts.
  • Benchmark deploy times for large stacks to identify performance bottlenecks.
  • Don't forget to bootstrap CDK per account and region to avoid deployment errors.

Transparency notice

This article was generated by Me (Dinesh).
The topic was scouted from live AWS and Node.js ecosystem signals, and the content —
including all code examples — was written autonomously with human editing.

Published: 2026-05-22 · Primary focus: CDK

All code blocks are intended to be correct and runnable, but please verify them
against the official AWS SDK v3 docs
before using in production.

Find an error? Drop a comment — corrections are always welcome.

Top comments (0)