Skip to content

CLAUDE.md

Latest commit

 

History

History
160 lines (111 loc) · 6.06 KB

CLAUDE.md

File metadata and controls

160 lines (111 loc) · 6.06 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TerraConstructs is a TypeScript library that provides AWS CDK-like constructs for infrastructure as code, built on top of CDKTN (CDK Terrain, the community fork of CDKTF / Terraform CDK). It combines AWS CDK patterns with Terraform's provider ecosystem and state management capabilities.

Development Commands

Core Development Workflow

  • pnpm install - Install dependencies, dependencies must be added in ./.projen.ts
  • pnpm compile - Compile TypeScript to JavaScript (required before integration tests)
  • pnpm build - Full build including compile, test, and package
  • pnpm jest --passWithNoTests --updateSnapshot --coverage=false ./test/aws/compute/launch-template.test.ts - run test for one test file only
  • pnpm test - Run All Jest unit tests (likely exceed memory and crash)
  • pnpm test:watch - Run tests in watch mode
  • pnpm eslint - Run ESLint for code quality

Integration Testing

  • IMPORTANT: Must run pnpm compile before integration tests (terratest uses compiled lib folder)
  • go test -v -count 1 -timeout 180m ./... - Run all integration tests (takes significant time)
  • Use individual make targets per service instead: cd integ/aws/compute && make instance
  • Requires AWS credentials and Bun runtime for synthesis

Make Target Patterns

For faster development iteration, use make target suffixes to skip certain stages:

  • %-validate-only - Skip synth, deploy, and cleanup (e.g., make instance-public-validate-only)
  • %-no-cleanup - Skip cleanup step to inspect outputs (e.g., make instance-public-no-cleanup)
  • %-synth-only - Skip deploy, validate, and cleanup (e.g., make instance-public-synth-only)
  • %-cleanup-only - Skip synth, deploy, and validate (e.g., make instance-public-cleanup-only)

Use make help to see all available targets and patterns.

Example workflow for iterating on integration test validation:

cd integ/aws/compute
make instance-public-no-cleanup  # Deploy and keep resources
make instance-public-validate-only  # Test validation logic repeatedly
make instance-public-cleanup-only  # Clean up when done

Tool Management

  • mise install - Install correct versions of required tools (Node.js, pnpm, Bun, Go, OpenTofu)
  • mise ls - View required tool versions

Architecture

Code Organization

  • src/ - TypeScript source code organized by architectural module
    • src/aws/compute/ - EC2, VPC, Lambda, Autoscaling, ELB, ... constructs
    • src/aws/network/ - legacy networking constructs (to be deprecated, use compute)
    • src/aws/storage/ - S3, Parameter Store, RDS, DynamoDb, ... constructs
    • src/aws/iam/ - IAM constructs
    • src/construct-base.ts - Base construct class
    • src/stack-base.ts - Base stack class
  • lib/ - Compiled JavaScript output
  • test/ - Jest unit tests
  • integ/ - Terratest integration tests

Key Design Patterns

  • JSII Compatibility: Library designed for multi-language support
  • Construct Hierarchy: Base classes provide common functionality
  • AWS CDK Patterns: Similar abstractions and developer experience
  • Generated Code: Many configuration files are auto-generated by Projen

Dependencies

  • CDKTN (0.23.0) - Core Terraform CDK framework (CDK Terrain, the community CDKTF fork)
  • AWS Provider (24.8.0) - Primary cloud provider
  • JSII (~5.9) - Multi-language library generation
  • Projen (^0.98.32) - Project synthesis and configuration management

Testing Strategy

Unit Tests (Jest)

  • Custom setup in setup.js for CDKTN testing
  • Assertions helpers in test/assertions.ts
  • Snapshot testing supported for template validation

Integration Tests (Terratest)

  • Real AWS resource deployment and validation
  • Modular tests using same categories as the library in integ/aws/
  • Automatic resource cleanup after tests
  • Requires compiled lib folder and AWS credentials

Testing Patterns

Integration Test Structure

Integration tests should follow this validation pattern (see validateMachineImage in integ/aws/compute/ec2_test.go):

  1. Terraform Outputs: Use registerOutputs or add TerraformOutput statements to test apps for validation access (depending on TerraConstruct support)

Unit Test Patterns

When changing construct behavior, update corresponding unit tests in test/.

Notes on Assertion helpers:

// Check resource count
Template.resources(stack, ResourceType).toHaveLength(0);

// Or using template instance method
const template = Template.synth(stack);
template.expectResources(ResourceType).toHaveLength(0);

Template validation should match actual Terraform behavior and update snapshot tests if resource structure changes.

Common Development Patterns

Integration Test Validation

Follow the pattern established in validateMachineImage and validateInstancePublic:

func validateYourFeature(t *testing.T, tfWorkingDir, awsRegion string) {
    terraformOptions := test_structure.LoadTerraformOptions(t, tfWorkingDir)
    // for Constructs that support registerOutputs:
	  topicArn := util.LoadOutputAttribute(t, terraformOptions, "my_topic", "topicArn")

    // in case of using TerraformOutput instead:
    outputs := terraform.OutputAll(t, terraformOptions)
    resourceID := outputs["ResourceId"].(string)

    // Wait for resource readiness
    util.WaitForResourceReady(t, awsRegion, resourceID, 10, 10*time.Second)

    // Fetch resource details
    details := util.GetResourceDetails(t, awsRegion, resourceID)

    // Validate properties
    assert.Equal(t, "expected-value", details.Property)

    // Test functionality (if applicable)
    if needsConnectivityTest {
        util.PingHost(t, details.PublicIP, 5*time.Second)
    }
}

Important Notes

  • Generated Files: Many files are auto-generated by Projen - modify .projenrc.ts instead
  • Package Manager: Uses pnpm (9.9.0) exclusively
  • Node.js Version: Requires >=18.18.0
  • Multi-language: Supports Python, Go, Java via JSII compilation
  • License: GPL-3.0-or-later