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 😉

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.