Aligent CDK Constructs

This repo contains different CDK constructs to assist in setting up static webpages with common features such as: prerender for SEO, regional redirection, data transformation, firewalls, and hosting. All constructs are configurable with the intent to be usable for all use cases.

These are all written for CDK v2. See the official AWS guide for how to migrate from CDK v1: https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html.

Construct	Description
basic-auth	Restricts CloudFront access behind authentication
cloudfront-security-headers	Adds HTTP security headers to origin responses
domain-hosting	Provides a construct to manage a Route53 or external domain along with (optionally) the certificate and records
esbuild	Provides a construct which allows AWS CDK's bundling process to use the esbuild tool to generate a bundled output
feature-env-handlers	Lambda@Edge handlers to support feature environments
geoip-redirect	Lambda@Edge handlers to redirect users based on region
graphql-server	Creates a GraphQL Mesh server to assist with data transformation from multiple sources
nodejs-function-from-entry	Resolves a source entry path to a pre-bundled Lambda code asset
header-change-detection	Creates a Lambda function that periodically scans security headers and sends the results to SNS
prerender-fargate	Self-hosted prerender to handle prerender bot requests
prerender-proxy	Provides functions to adjust self-hosted prerender behaviour
rabbitmq	Create a RabbitMQ cluster within CDK
secure-rest-api	API Gateway REST API secured with API key authentication and usage plan throttling
shared-vpc	Creates a single VPC with static IP for micro-services with DNS management
static-hosting	Construct to deploy infrastructure for static webpage hosting
step-function-from-file	Create a Step Function state machine definition from a given JSON or YAML file
waf	Configurable WAF infrastructure

Contributing

Development

Make your changes in the package of choice then

• Build it. yarn nx build <package_name>
• Pack it. cd dist/<package-name> && npm pack
• Import it. npm i <path_to_tarball> back in your main codebase

From here anytime you rerun the npm pack step your changes will be in sync.

Testing

To run tests for the entire monorepo:

yarn nx run-many -t test

To run tests for a specific package:

yarn nx test <package-name>

To run a single test file:

yarn nx test <package-name> --testFile=<test-file-name>

Adding a new package

To add a new construct package to the monorepo:

1. Create a new directory under packages/constructs/<name>/, mirroring the layout of an existing package. Each package should include:
   • index.ts — main exports
   • lib/ — construct source (and lib/handlers/ for any Lambda handlers)
   • package.json — with the npm name @aligent/cdk-<name> and starting version: 0.0.1
   • project.json — Nx targets (build / lint / test)
   • tsconfig.json, tsconfig.app.json, tsconfig.spec.json
   • jest.config.ts
   • README.md
2. Add the package to the constructs table at the top of this README.
3. Add a changeset (yarn changeset) for the initial release.

First publish must be done manually

Important

The first time a new package is published to npm, it must be published manually by a maintainer. Subsequent releases are then handled automatically by the changeset-release workflow.

Our release workflow (.github/workflows/changeset-release.yml) uses npm OIDC trusted publishing. OIDC can only publish new versions of packages that already exist on npm — it cannot create a brand new package. The package name has to be registered on the npm registry before automated releases can take over.

To bootstrap a new package:

1. Build the package locally: yarn nx build <package-name>
2. From the package directory, log in to npm (npm login) with maintainer credentials and publish: npm publish --access public
3. Once the package exists on npm, future versions will be released automatically by the changeset-release workflow when the corresponding "Release: Version Packages" PR is merged.

Merging

Once happy with the changes and there's no errors update the readme (if there's any functional changes) and create a PR for your branch

Once the changes have been approved, you can commit/merge the changes to the main branch and create a release.

Creating a release

Each construct/package maintains an independent release cycle.

Note that for all the finalized releases, the source branch should be the main branch.

If the release is experimental, you may use the main or the feature branch.

Release Tags When making a release (including experimental releases), the release tag should maintain following formation.

• experimental releases: [package-name]-[version number]-[experimental tag]
• finalized releases: [package-name]-[version number]

Note that the version number should follow [0-9].[0-9].[0-9] structure.

Experimental	Final
1.1.0-beta	1.1.0