Development

Requirements

Mandatory

• Node.js >= 22
• pnpm 10
• AWS CLI

Recommended

• Visual Studio Code
  • AWS Toolkit
  • ESLint
  • Prettier
• AWS Logs — for tailing CloudWatch logs
• Act — for running GitHub Actions locally

Docker System Requirements

Resource	Value
CPUs	1 (more performant if >2 available)
Memory	5 GB
Swap	1 GB
Disk	10 GB

Project Structure

cdk-utils/
├── packages/
│   ├── aws/              # AWS CDK constructs and service managers
│   ├── azure/            # Azure Pulumi constructs and service managers
│   ├── cloudflare/       # Cloudflare Pulumi constructs and service managers
│   ├── common/           # Shared utilities, types, and enums
│   └── cdk-utils/        # Umbrella package re-exporting all sub-packages
├── docs/                 # Project documentation (rendered in API docs)
├── img/                  # Architecture diagrams and logo
├── theme/                # Custom TypeDoc theme (CSS + JS)
├── .github/              # GitHub Actions workflows and actions
└── app/                  # Example applications
Copy

Each package under packages/ follows a consistent structure:

packages/<name>/
├── src/
│   ├── common/           # Base constructs, stacks, and shared types
│   ├── construct/        # High-level construct patterns
│   ├── services/         # Service manager classes
│   └── index.ts          # Public API exports
├── test/                 # Unit and integration tests
├── package.json
└── tsconfig.json
Copy

Setting up the Development Environment

1. Clone the repository

git clone https://github.com/gradientedge/cdk-utils.git
cd cdk-utils
Copy

2. Install dependencies

pnpm install
Copy

3. Build all packages

pnpm build
Copy

4. Run tests

pnpm test
Copy

Common Tasks

Install dependencies

pnpm install
Copy

Build all packages

pnpm build
Copy

Run the full validation suite (prettier + lint + test)

pnpm validate
Copy

Run tests with watch mode

pnpm test:watch
Copy

Lint and auto-fix

pnpm fix
Copy

Format code with Prettier

pnpm prettify
Copy

Generate API documentation

pnpm run docs
Copy

Update dependencies

pnpm update:deps
Copy

Build a specific package

pnpm --filter @gradientedge/cdk-utils-aws build
Copy

Run tests for a specific package

pnpm --filter @gradientedge/cdk-utils-aws test
Copy

Code Style

• TypeScript — strict mode enabled, noImplicitAny, strictNullChecks
• Formatting — Prettier with organized imports
• Linting — ESLint with TypeScript and JSDoc plugins
• Module system — ESM ("type": "module") with Node.js module resolution

All code is automatically formatted and linted via pre-commit hooks (powered by Husky).

Commit Conventions

This project uses Conventional Commits:

<type>(<scope>): <description>
Copy

Common types:

Type	Description
feat	A new feature
fix	A bug fix
docs	Documentation changes
style	Formatting, missing semicolons, etc.
refactor	Code change that neither fixes nor adds
test	Adding or updating tests
chore	Maintenance tasks (deps, CI, build, etc.)

Commit messages are validated automatically via a commit-msg hook using commitlint.