Skip to content

Writing arguments

Every factory argument has one shape per kind of value, and the analyzer tells you which kind it wants. The rules are the same on every provider package: Google Cloud, AWS, Azure, Cloudflare and Appwrite.

Pick the form by where the value comes from. The argument’s type tells you which forms it takes, and a dot shorthand (.literal, .new, .providedAl2023) names the constructor of that type.

The value isWrite
known when you synth.literal(...)
another resource of this Stack (a RefTo<R> input)its ref
one attribute of another blockits getter
a resource outside this Stack (a RefTo<R> input).literal(...) with its name, ID or ARN
one of a fixed set (an enum)the member
one of several exclusive arguments (a sealed type)the variant
a nested blockits helper class; .new(...) inside another block or a variant
a Terraform variablethe handle variable<T>() returns
a variable in an enum or RefTo<R> input.arg(handle)
a secret (a Sensitive<T> input)a sensitive variable, never a literal
a reference inside a literal list or mapthe getter’s .interpolation
anything else Terraform evaluates.expression(...)

Each row is an argument of this Stack body, marked with its row:

final memory = variable<num>('memory_mb');
final runtimeName = variable<String>('runtime');
final dbPassword = variable<String>('db_password', sensitive: true);
final trust = add(
DataAwsIamPolicyDocument(
'trust',
statement: [
DataIamPolicyDocumentStatement(
actions: .literal(['sts:AssumeRole']), // known when you synth
principals: [
// a nested block inside another block
.new(
type: .literal('Service'),
identifiers: .literal(['lambda.amazonaws.com']),
),
],
),
],
),
);
// one attribute of another block
final role = add(AwsIamRole('hello', assumeRolePolicy: trust.json));
add(
AwsLambdaFunction(
'hello',
functionName: .literal('hello'),
role: role.ref, // another resource of this Stack
runtime: .arg(runtimeName), // a variable in an enum input
code: .filename(.literal('build/fn.zip')), // a variant
memorySize: memory, // a Terraform variable
// a nested block
environment: LambdaFunctionEnvironment(
// a reference inside a literal map
variables: .literal({'ROLE_ARN': role.arn.interpolation}),
),
),
);
add(
AwsSsmParameter(
'db_password',
name: .literal('/hello/db_password'),
type: .securestring, // one of a fixed set
keyId: .literal('alias/aws/ssm'), // a resource outside this Stack
value: .value(dbPassword), // a secret
),
);
add(
AwsIamRole(
'deploy',
// anything else Terraform evaluates
assumeRolePolicy: .expression(r'${file("trust.json")}'),
),
);

The same table is in the README, on the dartdoc pages of TfArg, RefTo and every provider package, and in the agent skill. The sections below say more about each row.

A value known when you synth is .literal(...). Numbers, booleans, lists and maps work the same way:

add(
AppwriteWebhook(
'orders',
name: .literal('orders'),
url: .literal('https://example.com/hooks/orders'),
events: .literal(['databases.*.tables.*.rows.*.create']),
tls: .literal(true),
),
);

An argument can only be null when it is optional; leave it out instead of passing .literal(null).

An input that names another resource is typed RefTo<R>. Pass the resource’s ref, and the input writes the attribute the provider expects (self_link, id, arn, name), so you never pick one, and a resource of the wrong type does not compile:

final zone = add(
CloudflareZone('site', name: .literal('example.com'), account: ZoneAccount(id: .literal('acc'))),
);
add(
CloudflareDnsRecord(
'www',
zoneId: zone.ref,
name: .literal('www'),
type: .cname,
ttl: .literal(1),
content: .content(.literal('ghs.googlehosted.com')),
proxied: .literal(true),
),
);

Every attribute also has a getter (zone.id, role.arn, topic.name) that is a TfArg of its type, so it goes into any argument that takes one. A resource outside the Stack goes into a RefTo<R> input as .literal(...), its name, ID or ARN. A module output or another string you cannot type goes in as .arg(...), unchecked.

add(
CloudflareDnsRecord(
'apex',
zoneId: .literal('023e105f4ecef8ad9ca31a8372d0c353'),
name: .literal('@'),
type: .a,
ttl: .literal(1),
content: .content(.literal('192.0.2.1')),
),
);

An input with a fixed set of values takes the member, bare, as the DNS record’s type above and the function’s runtime below do. A list of them is a literal Dart list of members, as the function’s architectures shows:

final role = AwsIamRole(
'fn',
assumeRolePolicy: .expression(r'${file("trust.json")}'),
);
add(role);
add(
AwsLambdaFunction(
'hello',
functionName: .literal('hello'),
role: role.ref,
runtime: .providedAl2023,
handler: .literal('bootstrap'),
architectures: .literal([.x8664]),
code: .filename(.literal('build/bootstrap.zip')),
),
);

When the provider accepts exactly one (or at most one) of several arguments, they are one sealed argument, and each variant sets one of them. Its name is the concept (code, content, name, delivery), and its variants are named after the Terraform arguments:

add(
AwsIamRole(
'deploy',
assumeRolePolicy: .expression(r'${file("trust.json")}'),
name: .namePrefix(.literal('deploy-')),
),
);

A variant whose block has no fields takes no argument, as the BigQuery endpoint of this profile does:

add(
GoogleDatastreamConnectionProfile(
'warehouse',
connectionProfileId: .literal('warehouse'),
location: .literal('us-central1'),
displayName: .literal('Warehouse'),
endpoint: .bigqueryProfile(),
),
);

A nested block is a helper class. Name the class on the resource’s own arguments, where it tells a reader which block starts, and write .new(...) for a block inside another block or inside a variant, such as the push configuration a subscription’s delivery variant takes. A block that repeats is a Dart List of helpers:

add(
GoogleStorageBucket(
'logs',
name: .literal('my-project-logs'),
location: .literal('EU'),
lifecycleRule: [
StorageBucketLifecycleRule(
action: .new(type: .delete),
condition: .new(age: .literal(30)),
),
],
),
);

variable<T>() declares a Terraform variable on the Stack and returns its handle, which a TfArg<T> input takes as is. An enum or RefTo<R> input takes it through .arg(handle).

An input the provider marks sensitive is Sensitive<T>. It takes a sensitive variable, an expression or another block’s attribute, but has no .literal, so a secret never ends up in main.tf.json:

final dbPassword = variable<String>('db_password', sensitive: true);
add(
GoogleSecretManagerSecretVersion(
'db_password',
secret: .literal('projects/my-project/secrets/db-password'),
payload: .plaintext(dbPassword),
),
);

Expressions and references inside literals

Section titled “Expressions and references inside literals”

Anything Terraform has to evaluate — a function call, a conditional, terraform.workspace — is .expression(...), written as a Terraform template. Use a raw string (r'...') so Dart leaves ${ alone.

A literal list or map holds plain values, so a reference inside one goes in as the getter’s .interpolation (${aws_iam_role.hello.arn}), as the function’s environment variables do in the fence under the rules.

Synth checks what the analyzer cannot: a variable you never declared, a reference to a block you never added, a negative timeout. stack.validate() lists every issue at once.