Cloud Blocks

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

Read more in the docs here: Cloud Blocks Docs

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 { ApiCloudFrontDistribution } 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 ApiCloudFrontDistribution(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 dev:setup

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

Code Quality Tools

This project uses several tools to maintain code quality and consistency:

• Biome: Fast linting and formatting for TypeScript/JavaScript
• CSpell: Spell checking configured for UK English
• TypeScript: Type checking and compilation
• Lefthook: Git hooks for automated quality checks

Language Standards: All documentation and comments use UK English spelling (colour, behaviour, organisation, etc.)

Common Commands

• Build all packages

  pnpm run build

• Run tests

  pnpm test

• Lint & format (Biome)

  pnpm run lint
  pnpm run format:check

• Spell check (CSpell)

  pnpm spell:check

• Check for unused dependencies (Knip)

  pnpx knip --include dependencies

• Remove unused dependencies (Knip)

  pnpx knip --fix

• 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, check spelling (CSpell), and run type/build checks before commits and pushes.

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

API Documentation

Comprehensive API documentation is available at:

📚 Cloud Blocks API Reference

The API documentation is automatically generated from TypeScript source code and includes:

• Complete API signatures for all constructs, types, and utilities
• Detailed parameter descriptions and return types
• Type definitions and interfaces
• Code examples and usage patterns

Examples

The tests/test-project directory contains working examples of all constructs in a real CDK application. These examples demonstrate best practices and can be used as a reference for your own implementations.

Construct Examples

Each construct has a corresponding example file showing real-world usage:

• ApiCloudFrontDistribution - API Gateway with CloudFront distribution, custom domain, SSL certificate, and monitoring
• ProgressiveLambda - Lambda function with progressive deployment using AWS CodeDeploy
• RestApi - REST API Gateway with CloudWatch logging, CORS configuration, and observability
• IdempotencyTable - DynamoDB table optimized for idempotency patterns
• CloudWatchDashboard - Centralized monitoring dashboard with custom widgets
• CustomStack - Extended Stack with built-in tagging, dashboard creation, and best practices

Running the Examples

To run the example project locally:

# Build the package
pnpm run build

# Navigate to the test project
cd tests/test-project

# Synthesize the CloudFormation templates
pnpx cdk synth --all

# View the generated templates
ls cdk.out/

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, spelling is checked (UK English), and type/build checks run pre-commit and 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.