The origin story explained why Dinghy renders TSX to Terraform. This post is the how, at two levels. First we create an EC2 instance by hand from the lowest-level pieces Dinghy gives you, one component per Terraform resource. Then we bundle those pieces into composite components and watch eight lines of TSX turn into a complete server stack: VPC, subnet, security group, IAM, and more.

Part 1: Basic service components

One component per Terraform resource

The foundation of Dinghy's AWS support is a set of basic service components. There is one component for every Terraform resource, generated directly from the provider schema:

The mapping is mechanical: the snake_case resource name becomes a Aws-prefixed PascalCase component, every argument becomes a prop, and the whole thing is type checked against the provider schema. There are around 245 AWS services covered this way, so if Terraform can describe it, there is a component for it.

These are deliberately thin. A basic component does not add opinions or defaults. It is a 1:1 typed wrapper around a single resource. That makes them the building blocks everything else is assembled from.

Building a server by hand

Here is a complete program that creates an EC2 instance, using nothing but a basic component:

import { Shape } from '@dinghy/base-components'
import { AwsProvider } from '@dinghy/tf-aws'
import { LocalBackend } from '@dinghy/tf-common'
import { AwsInstance } from '@dinghy/tf-aws/serviceEc2'

export default () => (
  <Shape _title='Server With Basic Building Blocks'>
    <AwsProvider>
      <Server />
      <LocalBackend />
    </AwsProvider>
  </Shape>
)

const Server = (props: any) => (
  <AwsInstance
    ami='ami-005e54dee72cc1d00'
    instance_type='t3.nano'
    _title='my-demo-server'
    {...props}
  />
)

Three pieces do the work:

• AwsProvider configures the AWS provider (region and so on).
• LocalBackend stores Terraform state on disk. In production you would swap this for an S3 backend, but local is perfect for a first run.
• AwsInstance is the resource we actually want.

That is the whole point of a basic component. AwsInstance is a typed, 1:1 stand-in for the aws_instance resource: its props (ami, instance_type, and the rest) map straight onto the resource's arguments, with nothing added.

What renders out

Running this through Dinghy produces plain Terraform JSON:

{
  "resource": {
    "aws_instance": {
      "awsinstance_mydemoserver": {
        "ami": "ami-005e54dee72cc1d00",
        "instance_type": "t3.nano",
        "tags": {
          "Name": "my-demo-server",
          "iac:id": "awsinstance_mydemoserver"
        }
      }
    }
  }
}

The only thing in there you did not type is the tag block. iac:id is how Dinghy keeps a stable identity for each resource across renders, and Name comes from the _title. Everything else is a plain translation of the props you wrote. This is regular Terraform: you can read it, diff it, and apply it with the standard tooling.

Basic components give you complete control and a 1:1 map to Terraform, at the cost of writing every resource yourself. For a single instance that is fine. But a real server also needs a VPC, a subnet, an internet gateway, a security group, and an IAM role. Writing all of those by hand is a lot of repetitive work. That is where the second layer comes in.

Part 2: Composite components

Infrastructure in one tag

A single instance is small. Composite components pay off when the thing you want is made of a dozen resources that all have to reference each other correctly. A working EC2 server needs a VPC, a subnet, an internet gateway, a route, a security group, IAM, an AMI lookup, and the instance itself. Here is all of it:

import { AwsStack } from '@dinghy/tf-aws'
import { Ec2Servers } from '@dinghy/tf-aws/ec2'

export default () => (
  <AwsStack>
    <Ec2Servers />
  </AwsStack>
)

Two composites do all the work:

AwsStack replaced the scaffolding. In Part 1 we wrote Shape, AwsProvider, and LocalBackend ourselves. AwsStack folds the provider, the state backend, and an optional regional log bucket into one wrapper with sensible defaults. You only reach for the individual pieces when you want to override one.

Ec2Servers built the server. Eight lines of TSX render to 248 lines of Terraform JSON. It looks at what you asked for and creates whatever is missing:

• Networking: aws_vpc, aws_subnet, aws_internet_gateway, a route, and the security group with ingress and egress rules.
• Identity: an aws_iam_role, a policy attachment, and an aws_iam_instance_profile.
• Image: a data.aws_ami lookup for the latest Amazon Linux 2023 (or Ubuntu) image.
• The instance: aws_instance, plus an output with its id and public IP.

It also wires up AWS Session Manager by default, so you can connect to the instance without opening SSH or managing keys.

When the defaults are not what you want, you override through configuration rather than by dropping down to raw resources:

# dinghy.config.yml
servers:
  web1:
    instance_type: t4g.nano # arm64 instead of the t3.nano default
    linuxFlavor: ubuntu
  web2:
    instance_type: t3.small

That gives you two servers, on different architectures and distributions, still in the same eight lines of TSX.

The full example, with the source, the generated diagram, the complete 248-line Terraform, and the commands to deploy and connect, is at dinghy.dev/show-cases/ec2-servers.

A composite is just a component

The 248 lines might look surprising, so it is worth seeing that Ec2Servers is not a special language feature. It is an ordinary TSX component built from the basic building blocks of Part 1. The part that creates each instance, with the detail removed, looks like this:

function Ec2Server({ _server }: any) {
  const { awsAmi } = useAwsAmi()
  const { awsSubnet } = useAwsSubnet('public')
  const { instanceProfile } = useAwsIamInstanceProfile()
  return (
    <AwsInstance
      ami={awsAmi.id}
      subnet_id={awsSubnet.id}
      iam_instance_profile={instanceProfile.name}
      {..._server}
    />
  )
}

That is the same AwsInstance we wrote by hand in Part 1, now fed by the context lookup the origin story described. The composite renders the VPC, subnet, AMI lookup, and IAM role alongside the instance, and each useAws...() call reaches up the tree to find them, so you never pass references down through props by hand. The opinions and the boilerplate live in one place instead of being copied into every server you ever create.

It also creates only what you did not supply. Before rendering the instances, the composite inspects each server's props and decides which supporting resources to build on demand:

const createVpc = servers.some((s) => !s.subnet_id)
const referenceAmi = servers.some((s) => !s.ami)
const createInstanceProfile = servers.some((s) => !s.iam_instance_profile)

Pass your own iam_instance_profile and the composite uses it. Leave it out and it builds an IAM role and an aws_iam_instance_profile for you, with the SSM policy attached so dinghy aws connect can reach the instance. The VPC and the AMI lookup work the same way: supplied means reused, missing means created on demand.

Two levels, one model

That is the whole picture:

• Basic components are the 1:1 building blocks. Complete control, more typing.
• Composite components are ordinary components assembled from those blocks, with opinions and defaults built in. Less typing, fewer mistakes.

Neither replaces the other. A composite is built from basics, so you can always reach past it: nest a raw AwsVpcSecurityGroupIngressRule as a child of <Ec2Servers>, or swap an internal piece through the _components prop, when you need something the defaults do not cover. You start at the high level and drop down only where it matters.