AWS CDK Python to TypeScript Converter

How to convert a CDK app from Python to TypeScript

To convert an AWS CDK app from Python to TypeScript, paste a stack into the editor above and press Convert to TypeScript. Keyword arguments are gathered into one props object with camelCase keys, self becomes this and each from aws_cdk import becomes an aws-cdk-lib import. Put the result in a TypeScript CDK app, run tsc and check cdk diff.

1. Add your Python stackPaste a stack into the AWS CDK (Python) editor, use Open file for a .py or .txt file up to 500 KB, or drop a file onto the editor. Sample loads an S3 bucket, a Lambda function and a nightly EventBridge schedule.
2. Let the secret check runThe page scans for AWS access keys, secret keys, private keys and common API tokens before sending anything, and points out any it finds so you can swap in a placeholder.
3. Convert to TypeScriptClick Convert to TypeScript or press Ctrl + Enter. The result streams in as it's written, and Stop cancels it. Each conversion takes up to 60,000 characters.
4. Review the TypeScriptCompare construct IDs with the original and look for TODO: comments marking Python code with no direct TypeScript form. Copy the result or Download it as stack.ts.
5. Compile and diffCreate a project with cdk init app --language typescript, put the stack in lib/ and instantiate it from the file in bin/. Run npx tsc --noEmit, then cdk diff against the deployed stack.

Why move a CDK app from Python to TypeScript

TypeScript is the language the CDK itself is written in, and every jsii construct library is authored in it. The compiler checks each prop name, type and enum value while you edit. In Python, a misspelled keyword argument or enum member only fails when cdk synth runs the app, and some mistakes, such as passing the wrong kind of value, can get further than that.

Teams also switch when their application code is already TypeScript, such as a Node.js API or a frontend deployed with the CDK. One language, one package manager and one test runner then cover both the app and its infrastructure.

Both languages use the same aws-cdk-lib, so your architecture doesn't change. Converting by hand means regrouping every keyword argument into an object and renaming every method and property. The converter does that for a full stack file, which leaves your review time for construct IDs and custom helpers. Going the other way? Use the CDK TypeScript to Python converter.

Moving CDK code from Python to TypeScript

TypeScript is the CDK's native language, so every construct your Python app uses has a direct TypeScript equivalent. Keyword arguments such as removal_policy=RemovalPolicy.RETAIN become props objects like { removalPolicy: RemovalPolicy.RETAIN }, self becomes this, and from aws_cdk import aws_s3 as s3 becomes import * as s3 from "aws-cdk-lib/aws-s3".

As long as the stack names and construct IDs stay the same, the synthesized CloudFormation template matches the one you deployed from Python, and cdk diff shows no resource changes.

Set the project up with cdk init app --language typescript, then copy the converted stack into lib/. AWS's guide to working with CDK in TypeScript covers the build and cdk.json details.

Where Python and TypeScript CDK code differ

The language-level differences to expect in the converted code. Construct classes and enums keep their names in both.

Key features

• Keyword arguments regroupedEvery keyword argument after the scope and ID moves into one props object, with camelCase keys that the TypeScript types expect.
• Imports rewritten for aws-cdk-libfrom aws_cdk import aws_s3 as s3 becomes import * as s3 from "aws-cdk-lib/aws-s3", and aliases like lambda_ go back to lambda.
• camelCase methods and propertiesgrant_write, bucket_name and from_asset become grantWrite, bucketName and fromAsset.
• Typed stack constructorsStacks get the standard (scope: Construct, id: string, props?: StackProps) signature, so the compiler can check how they're used.
• Construct IDs copied exactlyIDs stay as written, even when they don't look like TypeScript names, because changing them would replace resources.
• Untranslatable code flaggedComments carry over, and anything without a direct TypeScript equivalent gets a TODO: comment.
• Checked, streamed and downloadableKeys are detected in your browser before sending, the result streams in with a Stop button, and you can save it as stack.ts.
• Free, with no signupConvert right away. A free account raises your limits and lists recent conversions on your dashboard.

Examples: CDK Python converted to TypeScript

Three stacks that show how Python idioms map to TypeScript ones. Choose Try this example to load the Python into the converter. The TypeScript shown is what correct output looks like; yours may be formatted differently.

from aws_cdk import Stack, RemovalPolicy
from aws_cdk import aws_dynamodb as dynamodb
from constructs import Construct


class UsersStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        table = dynamodb.Table(
            self, "Users",
            partition_key=dynamodb.Attribute(name="userId", type=dynamodb.AttributeType.STRING),
            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
            removal_policy=RemovalPolicy.RETAIN,
        )
        table.add_global_secondary_index(
            index_name="byEmail",
            partition_key=dynamodb.Attribute(name="email", type=dynamodb.AttributeType.STRING),
        )

import { Stack, StackProps, RemovalPolicy } from "aws-cdk-lib";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export class UsersStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, "Users", {
      partitionKey: { name: "userId", type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: RemovalPolicy.RETAIN,
    });
    table.addGlobalSecondaryIndex({
      indexName: "byEmail",
      partitionKey: { name: "email", type: dynamodb.AttributeType.STRING },
    });
  }
}

from aws_cdk import App, Stack
from aws_cdk import aws_sqs as sqs
from constructs import Construct


class QueueStack(Stack):
    def __init__(
        self, scope: Construct, construct_id: str, *, queue_name: str, fifo: bool = False, **kwargs
    ) -> None:
        super().__init__(scope, construct_id, **kwargs)
        sqs.Queue(self, "Jobs", queue_name=queue_name, fifo=fifo)


app = App()
QueueStack(app, "JobsStack", queue_name="jobs.fifo", fifo=True)
app.synth()

import { App, Stack, StackProps } from "aws-cdk-lib";
import * as sqs from "aws-cdk-lib/aws-sqs";
import { Construct } from "constructs";

interface QueueStackProps extends StackProps {
  queueName: string;
  fifo?: boolean;
}

export class QueueStack extends Stack {
  constructor(scope: Construct, id: string, props: QueueStackProps) {
    super(scope, id, props);
    new sqs.Queue(this, "Jobs", { queueName: props.queueName, fifo: props.fifo ?? false });
  }
}

const app = new App();
new QueueStack(app, "JobsStack", { queueName: "jobs.fifo", fifo: true });

from aws_cdk import Stack, Duration
from aws_cdk import aws_lambda as lambda_
from aws_cdk import aws_sqs as sqs
from aws_cdk.aws_lambda_event_sources import SqsEventSource
from constructs import Construct


class WorkerStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        queue = sqs.Queue(self, "Tasks", visibility_timeout=Duration.minutes(2))
        worker = lambda_.Function(
            self, "TaskWorker",
            runtime=lambda_.Runtime.PYTHON_3_12,
            handler="worker.handler",
            code=lambda_.Code.from_asset("worker"),
            timeout=Duration.minutes(1),
            environment={"QUEUE_URL": queue.queue_url},
        )
        worker.add_event_source(SqsEventSource(queue, batch_size=5))

import { Stack, StackProps, Duration } from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as sqs from "aws-cdk-lib/aws-sqs";
import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
import { Construct } from "constructs";

export class WorkerStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const queue = new sqs.Queue(this, "Tasks", { visibilityTimeout: Duration.minutes(2) });
    const worker = new lambda.Function(this, "TaskWorker", {
      runtime: lambda.Runtime.PYTHON_3_12,
      handler: "worker.handler",
      code: lambda.Code.fromAsset("worker"),
      timeout: Duration.minutes(1),
      environment: { QUEUE_URL: queue.queueUrl },
    });
    worker.addEventSource(new SqsEventSource(queue, { batchSize: 5 }));
  }
}

Tips for better results

• Keep construct IDs identical. "NightlyReport" must stay "NightlyReport", or CloudFormation sees a new resource and replaces the old one.
• Let the compiler help. Run npx tsc --noEmit after converting. Wrong prop names and missing required props show up as type errors.
• Convert helper modules too. Python helpers that build construct props need their own TypeScript versions, so paste them separately.
• Check Duration and enum calls. Duration.minutes(5) is the same in both languages, but Python-only helpers must be replaced.
• Confirm with cdk diff. Once cdk.json runs the TypeScript app, the diff against the deployed stack should be empty.

Common mistakes when moving CDK to TypeScript

• Renaming IDs to look like TypeScript. An ID such as "reports_bucket" is just a string. Leave it as it is, even if it doesn't match your new naming style.
• Leaving out new. Every construct is a class, so TypeScript needs new s3.Bucket(...). tsc reports any call that's missing it.
• Keeping snake_case keys. removal_policy isn't a known prop in a TypeScript props object, so the compiler rejects it. Every key must be camelCase.
• Rewriting the Lambda code as well. Only the infrastructure moves to TypeScript. Keep Runtime.PYTHON_3_12 and the asset path if the function itself stays in Python.
• Translating is None checks literally. Optional props are undefined in TypeScript. Use props.name ?? "default" rather than comparing with null.

Frequently asked questions

Related tools and next steps

• CDK TypeScript to Python converterConvert a stack back to Python, or move a different app the other way.
• Terraform to CDK TypeScript converterPull Terraform modules into the same TypeScript CDK app.
• IAM policy from TypeScript codeGet a least-privilege policy for the AWS SDK calls in your TypeScript Lambda code.
• CDK to Terraform converterLeaving the CDK entirely? Rewrite a stack as Terraform HCL.
• All AWS code convertersSDKs, infrastructure as code and IAM policy generators in one place.