How to migrate to AWS CDK v2


During last year’s re:Invent (2021), AWS CDK v2 got announced as generally available to the public. This meant that you could upgrade to the newer version without having to worry about any breaking changes that might be introduced when CDK v2 was in beta.

So now that it’s publicly available I see a lot of questions and concerns from people who have trouble upgrading their existing projects from AWS CDK v1 to v2.

This guide will address these concerns and show you how you can upgrade an existing AWS CDK v1 app to v2 without breaking its functionality.

The migration process consists of the following 2 steps:

  1. Change the AWS CDK npm package
  2. Update your imports

1. Change the AWS CDK npm package

The biggest change that was added to AWS CDK v2 was that all AWS Construct Libraries got combined into a single npm package.

The original AWS CDK v1 was released as 150+ modules, one for every AWS service and a few framework modules. These models have complex interdependencies.

This meant that you needed to install multiple npm packages if you wished to build different AWS resources as shown in the dependencies of this example package.json:

// AWS CDK v1 package.json
{
  "name": "application-load-balanced-fargate-service",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "cdk": "cdk"
  },
  "author": {
    "name": "Danny Steenman",
    "url": "https://towardsthecloud.com",
    "organization": false
  },
  "license": "Apache-2.0",
  "devDependencies": {
    "@types/node": "^10.17.27",
    "typescript": "~3.9.7"
  },
  "dependencies": {
    "@aws-cdk/aws-ec2": "*",
    "@aws-cdk/aws-ecs-patterns": "*",
    "@aws-cdk/aws-ecs": "*",
    "@aws-cdk/aws-logs": "*",
    "@aws-cdk/aws-rds": "*",
    "@aws-cdk/core": "*"
  }
}

The AWS CDK v2 is now a monolithic package that contains all modules so a package.json in an upgraded project will look like:

AWS CDK v2 package.json
{
  "name": "application-load-balanced-fargate-service",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "cdk": "cdk"
  },
  "author": {
    "name": "Danny Steenman",
    "url": "https://towardsthecloud.com",
    "organization": false
  },
  "license": "Apache-2.0",
  "devDependencies": {
    "@types/node": "^10.17.27",
    "typescript": "~3.9.7"
  },
  "dependencies": {
    "aws-cdk-lib": "2.15.0"
  }
}

2. Update your imports

After replacing the dependencies in the package.json you need to update the imports in your code to make use of the new aws-cdk-lib package.

In AWS CDK v1 you import every module independently as shown in the example below:

import * as ec2 from '@aws-cdk/aws-ec2';
import * as cdk from '@aws-cdk/core';
import * as ecs from '@aws-cdk/aws-ecs';
import * as ecspatterns from '@aws-cdk/aws-ecs-patterns';
import * as logs from '@aws-cdk/aws-logs';

To make the imports compatible with v2 all you have to do is a simple search and replace as explained simply in my tweet πŸ˜‰

Tweet with the text: Upgrading from CDKv1 to CDKv2 like…

The end result will look like this:

import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ecspatterns from 'aws-cdk-lib/aws-ecs-patterns';
import * as logs from 'aws-cdk-lib/aws-logs';

Note: The Construct module from @aws-cdk/core package is not placed in the aws-cdk-lib package. You need to install the package constructs and import it like this

import { Construct } from 'constructs';

If you need more details on how to migrate your project from AWS CDK v1 to v2 then have a look at this commit that I made on my GitHub project.

It shows all the changes that I made in order to get my project compatible with AWS CDK v2.

Elevate Your AWS CDK App with Expert Review & Guidance

Unlock the full potential of your AWS CDK app with our Expert AWS CDK App Code Review Service, conveniently delivered through AWS IQ.

Gain invaluable insights, minimize risks, and set a clear path forward for your project’s success.



Danny Steenman

A Senior AWS Cloud Engineer with over 9 years of experience migrating workloads from on-premises to AWS Cloud.

I have helped companies of all sizes shape their cloud adoption strategies, optimizing operational efficiency, reducing costs, and improving organizational agility.

Connect with me todayΒ to discuss your cloud aspirations, and let’s work together to transform your business by leveraging the power of AWS Cloud.

I need help with..
stacked cubes
Improving or managing my CDK App.Maximize the potential of your AWS CDK app by leveraging the expertise of a seasoned CDK professional.
Reducing AWS Costs.We can start by doing a thorough assessment of your current AWS infrastructure, identifying areas with potential for cost reduction and efficiency improvement.
Verifying if my infrastructure is reliable and efficient.We’ve created a comprehensive AWS Operations Checklist that you can utilize to quickly verify if your AWS Resources are set up reliably and efficiently.