Skip to content

About

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

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

369 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Cloud Blocks logo

Cloud Blocks

GitHub license Maintained CI ReleaseCode style: Biome

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! 🎉

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.


Leighton Digital logo

About

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

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages