Skip to content
TerraDart

Getting Started

This guide matches the README quickstart for the 0.24.x line. TerraDart is alpha — breaking changes land only on minor bumps; see Status & versioning for the change policy and the path to beta.

Prerequisites

Section titled “Prerequisites”
  • Dart SDK ≥ 3.6
  • Terraform CLI ≥ 1.11.0
  • A GCP project with Pub/Sub enabled and Application Default Credentials (gcloud auth application-default login)

1. Add dependencies

Section titled “1. Add dependencies”
pubspec.yaml
dependencies:
  terradart_core: ^0.24.x
  terradart_google: ^0.24.x

Check pub.dev for the latest patch, then run:

Terminal window
dart pub get

Non-curated google_* resources are not generated locally. Request new factories via a GitHub feature issue.

2. Define a Stack

Section titled “2. Define a Stack”

Create lib/orders_stack.dart (or follow the pubsub quickstart):

import 'package:terradart_core/terradart_core.dart';
import 'package:terradart_google/provider.dart';
import 'package:terradart_google/pubsub.dart';


final class OrdersStack extends Stack {
  OrdersStack({required String projectId})
      : super(providers: [GoogleProvider(project: projectId)]) {
    final topic = add(GooglePubsubTopic(
      localName: 'orders',
      name: TfArg.literal('orders-prod'),
    ));
    addExport('ORDERS_TOPIC_NAME', ResourceIdExport(topic.nameRef));
    setAppExportsOutputPath('lib/generated/orders_stack.app.dart');
  }
}

3. Synth Terraform JSON

Section titled “3. Synth Terraform JSON”

From bin/infra.dart:

import 'package:my_pkg/orders_stack.dart';


Future<void> main() async {
  final stack = OrdersStack(projectId: 'YOUR-PROJECT-ID');
  await stack.writeTo('tf-out');
}
Terminal window
dart run bin/infra.dart

This writes tf-out/main.tf.json and, when exports are literal-resolvable, lib/generated/orders_stack.app.dart.

4. Plan and apply

Section titled “4. Plan and apply”
Terminal window
cd tf-out
terraform init
terraform plan
terraform apply

Your existing remote state backend and modules stay unchanged — TerraDart only replaces HCL/JSON authoring.

5. The boundary (optional)

Section titled “5. The boundary (optional)”

Import generated constants in app code instead of string literals:

import 'generated/orders_stack.app.dart';


bool acceptsTopic(String eventTopic) =>
    eventTopic == OrdersStackExports.ORDERS_TOPIC_NAME;

Rename orders-prod in the Stack without updating the subscriber and dart analyze fails. See Architecture — AppExport and the runnable pubsub quickstart (lib/subscriber_stub.dart).

Next steps

Section titled “Next steps”