Build and Deployment

Make Commands (Recommended)

Use

make

for deterministic, hermetic builds that work the same locally and in CI/CD:

# Show all available commands
make help

# Install dependencies
make install

# Clean build artifacts
make clean

# Build all packages in dependency order
make build-all

# Build root package only
make build

# Build CDK app only
make build-app

Code Quality Commands

# Run linter
make lint

# Fix linting issues
make lint-fix

# Format code
make format

# Check formatting (CI)
make format-check

# Format and fix linting
make format-fix

# Run all quality checks (format + lint)
make check

CDK Commands

# Synthesize CloudFormation templates
make synth

# Show CDK diff
make diff

# Deploy all stacks
make deploy

# Deploy specific stack
make deploy-stack STACK=StackName

CI/CD Commands

# CI check (format-check + lint)
make ci-check

# CI build (checks + full build)
make ci-build

# CI deploy (checks + build + synth)
make ci-deploy

Underlying npm Commands

The Makefile wraps these npm commands:

npm install              # Install dependencies
npm run clean            # Clean build artifacts
npm run build            # Build root package
npm run build:workspaces # Build all packages
npm run build:app        # Build CDK app
npm run lint             # Run linter
npm run lint:fix         # Fix linting
npm run format           # Format code
npm run format:check     # Check formatting
npm run format:fix       # Format and fix linting
npm run synth            # Synthesize CDK
npm run diff             # CDK diff
npm run deploy           # Deploy CDK

Build Order

The build process ensures packages are built in dependency order:

1. Root package (

   src/

   ) - Built first
2. Base packages (

   aws

   ) - No internal dependencies
3. Dependent packages (

   codeartifact

   ) - Built after dependencies
4. CDK app (

   bin/

   ,

   lib/

   ) - Built last, can import from all packages

Build Script Details

The

build:workspaces

script:

1. Builds root package (

   npm run build

   )
2. Copies root to

   node_modules/@cdk-constructs/cdk/

   for workspace resolution
3. Builds all workspace packages using TypeScript project references
4. Builds CDK app files (

   bin/

   ,

   lib/

   )

TypeScript Configuration

Root Package (

tsconfig.json

)

• Builds

  src/**/*

  only
• Excludes

  bin/

  ,

  lib/

  , and

  packages/

CDK App (

tsconfig.app.json

)

• Builds

  bin/**/*

  and

  lib/**/*

• Can import from workspace packages after they're built

Workspace Build (

tsconfig.build.json

)

• Lists packages in dependency order
• Uses TypeScript project references for incremental builds

Deployment Patterns

Multi-Account Strategy

This project follows a strict multi-account deployment pattern for security, isolation, and supply chain integrity.

Account Structure

Account	Purpose	Access Pattern
BUILD	CI/CD pipelines, artifact generation, supply chain security	Isolated account. Other accounts can access readonly/immutable.
DEV	Active development and testing	Can access BUILD artifacts (readonly).
STAGING	Pre-production testing and validation	Can access BUILD artifacts (readonly).
PROD	Production workloads	Can access BUILD artifacts (readonly).

BUILD Account Principles

CRITICAL: The BUILD account MUST be its own isolated AWS account.

1. Isolation: BUILD account is completely separate from application environments
2. Readonly Access: DEV, STAGING, and PROD can only read from BUILD (never write)
3. Immutable Artifacts: Once built in BUILD, artifacts cannot be modified
4. Supply Chain Security: All dependencies and builds happen in isolated BUILD environment
5. Access Control: BUILD account has read/write. Other accounts have readonly only.

CodeArtifact Access Patterns

// BUILD environment - owns the artifact repository
{
  ...buildEnv,
  codeArtifact: {
    codeArtifactDomainName: 'cdk-constructs',
    codeArtifactRepositoryName: 'cdk-constructs-library-build',
    codeArtifactRepositoryDescription: 'Build Repository - Supply Chain Security',
    // All accounts can access, but only BUILD can write
    allowedAccounts: [Account.BUILD, Account.DEV, Account.STAGING, Account.PROD],
  },
}

// Application environments - consume artifacts from BUILD
{
  ...devEnv,
  codeArtifact: {
    // DEV has its own repository but also accesses BUILD
    allowedAccounts: [Account.DEV, Account.STAGING, Account.BUILD],
  },
}

Environment Configuration Location

Environment configurations follow CDK conventions:

• Types:

  lib/types/project.ts

  - ProjectEnvironment type
• Configs:

  lib/config/environments.ts

  - buildEnv, devEnv, stagingEnv, prodEnv
• Re-exports:

  bin/environment.ts

  - Backwards compatibility

This follows the pattern:

bin/

→

lib/

for CDK applications.

Deployment Security

1. Never deploy BUILD artifacts to BUILD account - BUILD creates, others consume
2. Enforce readonly - Use IAM policies to prevent write access from non-BUILD accounts
3. Tag everything - Environment and Owner tags applied automatically via EnvironmentConfig
4. Audit access - Monitor cross-account access to BUILD artifacts

Common Build Issues

Issue: "Cannot find module '@cdk-constructs/...'"

Solution:

1. Run

   make install

   to set up workspace links
2. Run

   make build-all

   to build packages in order
3. Ensure package is listed in

   tsconfig.build.json

Issue: Circular dependency detected

Solution:

1. Check package dependencies in

   package.json

2. Verify build order in

   tsconfig.build.json

3. Ensure no package depends on a package that depends on it