> ## Documentation Index
> Fetch the complete documentation index at: https://cdktn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Setup - CDK Terrain

> Build a CDKTN application from a template or existing HCL project, and configure storage for Terraform state.

There are several ways to create a new CDK Terrain (CDKTN) project. You can create a new application from a pre-built or a custom template, and you can also convert an existing HCL project. When you create a new project, you can store Terraform state locally or use a [remote backend](/concepts/remote-backends). This page discusses these setup options in more detail.

<Tip>Try the [CDK Terrain Quick Start Demo](/tutorials/install) and language-specific [Get Started tutorials](/tutorials/install).</Tip>

## Initialize Project from a Template

Use `init` with a project template to automatically create and scaffold a new CDKTN project for your chosen programming language.
Templates generate a new application with the necessary file structure for you to start defining infrastructure.

You can use a `cdktn-cli` pre-built template or a custom-built [remote template](/create-and-deploy/remote-templates) when you initialize a new project.

```bash theme={null}
$ cdktn init --template="templateName"
```

Use these template names for the available pre-built templates:

* `typescript`
* `python`
* `c#`
* `java`
* `go`

Note: Even though the CDKTN Java template sets up the Gradle build system for performance reasons, you can still use Maven to build your project. For more information refer to the Java examples which also include Maven examples: [Java Examples](/examples-and-guides/examples#java).

### Use a Local Backend

Add the `--local` flag to created a scaffolded project that is pre-configured to use a [local backend](https://developer.hashicorp.com/terraform/language/settings/backends/local). This means that your application stores [Terraform state](https://developer.hashicorp.com/terraform/language/state) on your local machine and all Terraform operations run locally.

```
$ cdktn init --template="typescript" --local
```

### Use HCP Terraform as a Remote Backend

When you run `cdktn init` without the `--local` flag, CDKTN defaults to using HCP Terraform as a remote backend. This lets you store state and run Terraform operations remotely in HCP Terraform. Refer to [Set Up CDKTN With HCP Terraform](/create-and-deploy/hcp-terraform#set-up-cdktn-with-hcp-terraform) for details.

## Project Configuration

Initializing your project with a template generates a basic project in your preferred programming language that you can customize for your use case. You can manage global configuration for your project by customizing the `cdktf.json` configuration file or the application context.

### `cdktf.json` Configuration File

The `cdktf.json` configuration file is where you can define the [providers](/concepts/providers) and [modules](/concepts/modules) that should be added to the project and supply custom configuration settings for the application. Refer to the [cdktf.json documentation](/create-and-deploy/configuration-file) for more detail.

### Application Context

All of the classes in your application can access the application `context`, so it is an ideal place to store project configuration. Context becomes available to any construct in your application after you run `cdktn synth`.

You can configure context as a static value in `cdktf.json` by setting the `context` property.

```jsonc theme={null}
{
  // ...
  "context": {
    "myConfig": "value"
  }
```

You can also provide context when instantiating the `App` class.

```typescript theme={null}
const app = new App({ context: { myConfig: "value" } });
```

The following example uses `App` context to provide a custom tag value to an AWS EC2 instance.

```typescript theme={null}
import { Construct } from "constructs";
import { App, TerraformStack } from "cdktn";
import { AwsProvider } from "./.gen/providers/aws/provider";
import { Instance } from "./.gen/providers/aws/instance";

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

    new AwsProvider(this, "aws", {
      region: "us-east-1",
    });

    new Instance(this, "Hello", {
      ami: "ami-2757f631",
      instanceType: "t2.micro",
      tags: {
        myConfig: this.node.getContext("myConfig"),
      },
    });
  }
}

const app = new App({ context: { myConfig: "value" } });
new MyStack(app, "hello-cdktn");
app.synth();
```

## Generate Terraform Configuration

Run [`cdktn synth`](/cli-reference/commands#synth) to synthesize your application into JSON configuration files that Terraform can use to manage infrastructure. You can then either use the JSON file with Terraform directly or provision your infrastructure using CDKTN CLI commands.

Refer to [Deployment Patterns](/create-and-deploy/deployment-patterns#example-workflows) for example workflows, including connecting your CDKTN application to a Continuous Integration pipeline.

## Convert an HCL Project to a CDKTN TypeScript Project

You can initialize a new CDKTN TypeScript project from an existing project written in HashiCorp Configuration Language (HCL). This option is currently limited to the `typescript` template.

To convert an existing HCL project, add `--from-terraform-project` to the `init` command with the TypeScript template.

```
$ cdktn init --template=typescript --from-terraform-project /path/to/my/tf-hcl-project
```

### Usage Example

The following HCL configuration defines the `random` provider.

```hcl theme={null}
# File: /tmp/demo/main.tf

terraform {
  required_providers {
    random = {
      source = "hashicorp/random"
      version = "3.1.0"
    }
  }
}

provider "random" {
}

resource "random_pet" "server" {
}
```

Run the command to convert the HCL project in a new folder.

```sh theme={null}
cdktn init --template=typescript --from-terraform-project /tmp/demo --local
```

CDKTN bootstraps a Typescript project and generates the equivalent configuration in JSON.

```jsonc theme={null}
// File: /tmp/cdktn-demo/cdktf.json

{
  "language": "typescript",
  "app": "npm run --silent compile && node main.js",
  "projectId": "83684893-0e58-4a71-989a-ecb7c593a690",
  "terraformProviders": ["hashicorp/random@3.1.0"],
  "terraformModules": [],
  "context": {},
}
```

```typescript theme={null}
// File: /tmp/cdktn-demo/main.ts

/*Provider bindings are generated by running cdktn get.
Refer to https://www.terraform.io/cdktn/concepts/providers#providers for more details.*/
import { RandomProvider } from "./.gen/providers/random/provider";
import { Pet } from "./.gen/providers/random/provider";

import { Construct } from "constructs";
import { App, TerraformStack } from "cdktn";

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

    new RandomProvider(this, "random", {});
    new Pet(this, "server", {});
  }
}

const app = new App();
new MyStack(app, "cdktn-demo");
app.synth();
```

## Convert HCL Files to CDKTN Format

Use the `cdktn convert` command to convert individual HCL files to CDKTN-compatible files in your preferred programming language. Refer to the [`cdktn convert` command documentation](/cli-reference/commands#convert) for more information.