CDK Stacks

CDK Stacks define complete deployments of a single Runtime Element (Infrastructure, Partition, or Component) in a reusable, parametrized way. Stacks are defined in src/cdk/stacks/ organized into subdirectories by element kind.

Standard Stack Pattern

Each stack module defines the following types:

Type	Description
Configuration	True configuration parameters that affect resource behavior
Props extends Configuration	Adds CDK binding types (e.g., ec2.IVpc) for context dependencies. All members readonly
Built	Resources and values produced by the stack instantiation. All members readonly
ExportKeys	String union type of all CloudFormation output keys
ExportDefinition	Record<ExportKeys, StackIODefinition> — key and export name for each output
ExportValues	Record<ExportKeys, StackIOValue> — key and resolved value for each output

Two exported functions:

• importValues(forElement: ElementLocatorType): ExportValues — imports CloudFormation outputs from a deployed element
• exportDefinition(locator: ElementTypeLocator): ExportDefinition — returns the concrete export definitions for a given locator

Stack Constructor Signature

constructor(scope: cdk.App, id: string, locator: ElementLocatorType, props: Props)

Public members:

• readonly build: Built — results of stack instantiation
• readonly exportDefinition: ExportDefinition
• readonly exportValues: ExportValues
• publish(): void — emits exportValues as CloudFormation Outputs

Best practice: include static validateProps(prefix: string, id: string, props: Props): boolean to validate inputs before any resource creation begins.

Stack Template

import * as cdk from 'aws-cdk-lib';
import { stackTypes } from '../types';

export interface Configuration { /* ... */ }
export interface Props extends Configuration { /* CDK binding types */ }
export interface Built { /* produced resources */ }

export type ExportKeys = 'Key1' | 'Key2';
export type ExportDefinition = Record<ExportKeys, stackTypes.StackIODefinition>;
export type ExportValues = Record<ExportKeys, stackTypes.StackIOValue>;

export function importValues(forElement: ElementLocatorType): ExportValues { /* ... */ }
export function exportDefinition(locator: ElementTypeLocator): ExportDefinition {
  return {
    Key1: { exportName: `${locator.fqn}-Key1`, value: 'Value1' },
  };
}

export class MyStack extends cdk.Stack {
  public readonly build: Built;
  public readonly exportDefinition: ExportDefinition;
  public readonly exportValues: ExportValues;

  static validateProps(prefix: string, id: string, props: Props): boolean { /* ... */ }

  constructor(scope: cdk.App, id: string, locator: ElementLocatorType, props: Props) {
    validateProps(prefix, id, props);
    super(scope, id);
    this.exportDefinition = exportDefinition(locator);
    // define resources using props...
    this.exportValues = { Key1: { ...this.exportDefinition.Key1, value: '...' } };
  }

  public publish(): void { /* emit CloudFormation Outputs */ }
}

CloudFormation Output Shape

interface StackIODefinition {
  key: string;        // Unique within the stack
  exportName: string; // Globally unique within the AWS account+region
  value: string;      // String value or comma-separated list
}

Export Name Pattern:

• Infrastructure stack output: <infrastructureName>-<outputName>
• Partition stack output: <infrastructureName>-<purposeName>-<outputName>

Full regex: ^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]?)*-[A-Z][a-zA-Z0-9]*$

Export Name Conventions:

• Cross-repository (API) outputs: Logical ID matches /.*_?API$/, export name matches /.*-API-.*/
• Internal outputs: Logical ID matches /.*_?I$/, export name matches /.*-I-.*/

Component code should only import *-API-* outputs from other repositories.