Quickstart

Get started with tfts in 5 minutes

Get your first tfts project running in just a few steps.

Prerequisites

Before you begin, make sure you have:

• Node.js 18+ or Bun installed
• Terraform CLI installed (installation guide)

Step 1: Create a new project

Create a new directory and initialize a TypeScript project:

mkdir my-infrastructure
cd my-infrastructure
npm init -y

Step 2: Install tfts

npm install tfts

Step 3: Create configuration file

Create a cdktf.json file in your project root:

{
  "language": "typescript",
  "app": "npx ts-node main.ts",
  "terraformProviders": ["hashicorp/google@~>6.0"]
}

You can also use tfts.json as the configuration file name.

Step 4: Generate provider bindings

Generate TypeScript bindings for your providers:

npx tfts get

This creates a .gen directory with fully-typed provider classes.

Step 5: Write your infrastructure

Create a main.ts file:

import { App, TerraformStack, TerraformOutput } from "tfts";
import { GoogleProvider } from "./.gen/providers/hashicorp/google/provider.js";
import { ComputeInstance } from "./.gen/providers/hashicorp/google/resources/compute-instance.js";

class MyStack extends TerraformStack {
  constructor(scope: App, id: string) {
    super(scope, id);

    new GoogleProvider(this, "google", {
      project: "my-project",
      region: "us-central1",
    });

    const instance = new ComputeInstance(this, "vm", {
      name: "my-instance",
      machineType: "e2-micro",
      zone: "us-central1-a",
      bootDisk: {
        initializeParams: {
          image: "debian-cloud/debian-11",
        },
      },
      networkInterface: [{ network: "default" }],
    });

    new TerraformOutput(this, "ip", {
      value: instance.networkInterface.get(0).networkIp,
    });
  }
}

const app = new App();
new MyStack(app, "my-stack");
app.synth();

Step 6: Synthesize and deploy

Synthesize Terraform JSON configuration:

npx tfts synth

This creates a cdktf.out directory with your Terraform configuration.

Navigate to the stack directory and deploy:

cd cdktf.out/stacks/my-stack
terraform init
terraform apply

Using the CLI

tfts provides commands to streamline the workflow:

# Generate provider bindings
npx tfts get

# Synthesize Terraform configuration
npx tfts synth

# Show planned changes (terraform plan)
npx tfts diff

# Deploy the stack (terraform apply)
npx tfts deploy

# Destroy the stack
npx tfts destroy

Next steps

Core Concepts

Learn about App, Stack, and Constructs.

CLI Reference

Explore all available CLI commands.

Variables and Outputs

Work with Terraform variables and outputs.

Functions

Use Terraform functions in your code.