Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free

Write Terraform with Typescript and Python


Install cdktf and Run a Quick Start Demo

To use cdktf you will need to install it. The tool is available as a Typescript application from npm.


In order to use cdktf, you'll need Terraform, Node.js, and Yarn.

See the Terraform install tutorial for instructions on installing Terraform via package manager, source, or binary download.

Node.js publishes a graphical installer that will install Node.js and npm on your platform.

Yarn is an alternate JavaScript package manager that can be installed via Homebrew, precompiled binary, or from source.

»Install cdktf

To install the most recent stable release of cdktf, use npm.

$ npm install --global cdktf-cli

Because cdktf is being constantly improved, we recommend keeping up to date with the cutting edge development version by using the @next tag.

$ npm install --global cdktf-cli@next

»Verify the installation

Verify that the installation worked by opening a new terminal session and running the cdktf command to show available subcommands.

$ cdktf

cdktf [command]

  cdktf deploy [OPTIONS]   Deploy the given stack
  cdktf destroy [OPTIONS]  Destroy the given stack
  cdktf diff [OPTIONS]     Perform a diff (terraform plan) for the given stack
  cdktf get [OPTIONS]      Generate CDK Constructs for Terraform providers and modules.
  cdktf init [OPTIONS]     Create a new cdktf project from a template.
  cdktf login              Retrieves an API token to connect to Terraform Cloud.
  cdktf synth [OPTIONS]    Synthesizes Terraform code for the given app in a directory.

Add --help to any subcommand to learn more about what it does and available options.

$ cdktf deploy --help

»Quick start tutorial

Now that you've installed cdktf, you can write TypeScript code that will provision an NGINX server using Docker on Mac, Windows, or Linux. This example is free and requires no cloud credentials to run.

If you have cdktf and Docker installed on your local machine, start Docker Desktop by launching the application in your file browser or by running this command in a macOS terminal.

$ open -a Docker

»Create and initialize the project

Create the project from scratch, starting with a directory named typescript-docker.

$ mkdir typescript-docker && cd $_

Initialize the project with the init command. For this quick start, use the --local flag so that all state will be stored locally.

$ cdktf init --template=typescript --local

You'll be prompted for a project name and description. You can use the defaults as listed.

»Edit the code

Add code to two files: cdktf.json and main.ts.

In cdktf.json, list docker as one of the Terraform providers that you'll be using in the application. You can replace the existing "aws" example in the file.

"terraformProviders": [

Delete the contents of main.ts and paste the following TypeScript code into the main.ts file. We've included the equivalent HCL configuration in a tab for comparison.

import { Construct } from 'constructs'
import { App, TerraformStack } from 'cdktf'
import { Container, Image } from './.gen/providers/docker'

class MyStack extends TerraformStack {
  constructor(scope: Construct, name: string) {
    super(scope, name)

    const dockerImage = new Image(this, 'nginxImage', {
      name: 'nginx:latest',
      keepLocally: false,

    new Container(this, 'nginxContainer', {
      image: dockerImage.latest,
      name: 'tutorial',
      ports: [
          internal: 80,
          external: 8000,

const app = new App()
new MyStack(app, 'typescript-docker')

»Install dependencies and deploy

You're almost there! Run the get command to download the dependencies for using Docker with Typescript.

$ cdktf get

Now run deploy to compile the code and provision the NGINX container within Docker.

$ cdktf deploy

Stack: typescript-docker
 + DOCKER_CONTAINER     nginxContainer      docker_container.
 + DOCKER_IMAGE         nginxImage          docker_image.

Diff: 2 to create, 0 to update, 0 to delete.
Do you want to continue (Y/n)?

Verify the existence of the NGINX container by visiting localhost:8000 in your web browser or run docker ps to see the container.

NGINX running in Docker via Terraform

$ docker ps

CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                    NAMES
425d5ee58619        e791337790a6              "nginx -g 'daemon of…"   20 seconds ago      Up 19 seconds>80/tcp     tutorial

»Destroy the container

To stop the container, run cdktf destroy.

$ cdktf destroy

Stack: typescript-docker
 - DOCKER_CONTAINER     nginxContainer      docker_container.
 - DOCKER_IMAGE         nginxImage          docker_image.

Diff: 0 to create, 0 to update, 2 to delete.
Do you want to continue (Y/n)?

You've now provisioned and destroyed an NGINX webserver with cdktf.