Cloud Blocks is an open-source collection of AWS CDK constructs designed to help teams build secure, reusable, and production-ready cloud infrastructure faster.

Purpose​

• Provide reusable building blocks for AWS CDK projects.
• Promote best practices in networking, observability, security, and more.
• Reduce boilerplate by delivering ready-to-use constructs.
• Empower teams to adopt CDK more quickly and consistently.

Installation & Usage​

Install the @leighton-digital/cloud-blocks npm package in the project:

pnpm install @leighton-digital/cloud-blocks

Use in your CDK app:

import * as cdk from "aws-cdk-lib";
import { ApiGatewayCloudFrontDistribution } from "@leighton-digital/cloud-blocks";

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new ApiGatewayCloudFrontDistribution(this, "ApiGwCdn", {
      domainName: "example.com"
    });
  }
}

See each Constructs README for construct-specific props and examples.

Getting Started (Developers)​

Clone the repo and install dependencies:

git clone https://github.com/leighton-digital/cloud-blocks.git
cd cloud-blocks
pnpm install

Set up development environment:

pnpm run dev:setup

This installs Lefthook git hooks for automated formatting, linting, and pre-commit checks.

Common Commands​

• Build all packages

  pnpm run build
  

• Run tests

  pnpm test
  

• Lint & format (Biome)

  pnpm run lint
  pnpm run format:check
  

• Type-check

  pnpm run typecheck
  

• Test CDK synthesis

  cd tests/test-project
  pnpx cdk synth --all
  

Lefthook (installed via pnpm run dev:setup) runs local git hooks to format/lint staged files and run checks before push.

Testing & Validation​

CDK Construct Validation​

This project includes a comprehensive testing approach to ensure all CDK constructs work correctly:

Test Project (tests/test-project/)

• Contains a real CDK application that uses the constructs from this package
• Validates that constructs can be instantiated and synthesized without errors
• Serves as both a test and example implementation

Automated Synthesis Testing

• GitHub Actions automatically runs cdk synth --all on the test project
• Tests against multiple CDK versions to ensure compatibility
• Catches compilation errors, configuration issues, and CDK-specific problems
• Ensures constructs generate valid CloudFormation templates
• Runs on every pull request to prevent broken constructs from being merged

CDK Version Compatibility

• Best endeavours are made to ensure compatibility with CDK versions up to 6 months old
• Automated testing validates constructs against both current and previous CDK versions
• This ensures existing projects can upgrade Cloud Blocks without being forced to update CDK immediately

Local Testing

# Build the constructs
pnpm run build

# Test synthesis locally
cd tests/test-project
pnpx cdk synth --all

This approach ensures that:

• ✅ Constructs compile correctly
• ✅ CDK synthesis succeeds
• ✅ CloudFormation templates are generated properly
• ✅ Real-world usage patterns work as expected

Project Structure​

.
├── src/                       # Individual CDK construct packages
│   ├── api-gateway-cloudfront-distribution/
│   └── ...
├── tests/
│   └── test-project/          # CDK test application for construct validation
│       ├── lib/               # Test stack implementations
│       ├── bin/               # CDK app entry point
│       └── cdk.json           # CDK configuration
├── .changeset/                # Changesets for versioning & changelogs
├── CONTRIBUTING.md            # How to contribute
├── CONTRIBUTORS.md            # Project contributors
├── CODE_OF_CONDUCT.md         # Community guidelines
├── PUBLISHING.md              # Publishing process
└── README.md

Creating New Constructs​

This project includes a Plop generator to create new CDK constructs with consistent structure and boilerplate:

pnpm generate construct

The generator creates:

• Complete directory structure following project conventions
• TypeScript construct class with props interface
• Comprehensive Jest tests with CDK Nag compliance
• Documentation (README.md) with examples
• Automatic export updates

See Plop Generator Documentation for detailed usage instructions.

Contributing​

We welcome contributions from the community! 🎉

• Read the Contributing Guide for branching, coding standards, and review process.
• Follow the Code of Conduct.
• See Contributors for acknowledgements.
• Maintainers: follow Publishing Guidelines for releases.

Typical flow

1. Fork → feature branch.
2. Make changes, add tests, run checks.
3. Open a PR.

Lefthook (set up via pnpm run dev:setup) ensures format/lint fixes are applied pre-commit and runs checks pre-push.

Release Process​

Releases are automated via GitHub Actions:

1. Contributors create changesets with their PRs.
2. A Release PR is generated with version bumps and changelogs.
3. When merged, CI builds and publishes to the public npm registry.

Manual steps are documented in PUBLISHING.md.

License​

MIT License — see the LICENSE file for details.