Skip to main content

AWS CDK Construct Library

AWS CDK library projects produce artifacts with reusable constructs which can be consumed by other AWS CDK libraries or apps. Library artifacts are published to private or public package managers under a semantic version.

By default, for every commit to the default branch, a new version is released (trunk-based development). This includes the following steps:

  1. Compile, lint and test the code.
  2. Use JSII to produce library artifacts for all target languages.
  3. Determine the next minor/patch version based on conventional commits. Major versions must be explicitly bumped to protect consumers against breaking changes.
  4. A changelog entry is generated based on commit history.
  5. Packages are published to all target package managers.

Getting Started

Start like all projen projects:

npx projen new awscdk-construct

Review the resulting .projenrc.js file and make changes as needed. The following are some specific areas you may want to set explicitly.

Module Metadata

These fields are your basic Node module setup:

authorAddress: '',
authorName: 'Elad Ben-Israel',
description: 'Watching your CDK apps since 2019',
name: 'cdk-watchful',
license: 'MIT',
repository: '',
keywords: ['cloudwatch', 'monitoring']

All are pretty standard setup and nothing CDK-specific at this point. The keywords automatically gets 'cdk' so you don't need to specify it.


Depending on aws-cdk-lib

Next define the minimum CDK version u:

cdkVersion: '2.89.0', // example

You may set cdkVersionPinning to true to use a fixed version. But this means that any consumer of your library will have to use this exact CDK version and is not recommended.

Depending on other modules

If your library consumes other jsii modules, you should declare them through the deps or peerDeps options. deps should be used if types from the consumed module is not part of the public API of the library (the module is used as an implementation detail), while peerDeps must be used if types from the consumed module are exported as part of your library's API. You can read more here.

deps: [ 'cdk-time-bomb' ]


As this is a jsii project, it will cross-compile to other languages. You can set up any number of jsii target languages.

  publishToNuget: {
dotNetNamespace: 'Acme.HelloNamespace',
packageId: 'Acme.HelloPackage'
publishToMaven: {
javaPackage: 'com.acme.hello',
mavenArtifactId: 'hello-jsii',
mavenGroupId: 'com.acme.hello'
serverId: 'github',
repositoryUrl: '',
publishToPypi: {
distName: 'acme.hello-jsii',
module: 'acme.hello_jsii'

publib is used for publishing, and requires uploading Github project secrets to the repositories you wish to publish to:

  • npm - NPM_TOKEN (docs)

  • .NET - NUGET_API_KEY (docs)



If you don't want to publish a particular package, do not include the dotnet, java, or python field.


Two workflows will be created as Github Actions:

  • The Build workflow - controlled by the buildWorkflow field. On a 'pull_request' or 'workflow_dispatch' the library will be built and checked for anti-tamper (ensure no manual changes to generated files).
  • The Release workflow - controlled by the releaseWorkflow field. On a push to main (overridden at props.defaultReleaseBranch) the library is built, anti-tampered, version bumped with a commit, pushed back to git, and then published to the configured artifact repositories (e.g. npm, pypi).


There are a number of package scripts that are created for you. Any of them can be overwritten using the addScript* methods.

startstarts an interactive command menu
projenregenerates the projen config. Run this if you edit .projenrc.js
no-changesa helper script to prevent unnecessary releases.
bumpbumps the package version number
releasebumps the library's version and pushes to origin
projen:upgradeupgrades the projen cli tool
compilebuilds the library and generates docs
watchcompiles and then re-compiles of further changes
packageruns jsii-pacmak to package your library for publishing
testcompiles and runs automated tests
test:watchwatches for file changes, re-compiles and re-tests
test:updateupdate any test snapshots
eslintruns eslint against all src and test .ts files
compatchecks for jsii compatibility. See here for more info.
docgengenerate documentation

As you develop your library you'll likely be using the test:watch command the most.

API Documentation

Docs will be generated from Typescript comments and saved in the file. Please review this file regularly and document your constructs liberally.

Project structure

|--lib/ (build output)

Source .ts files should reside in the src directory. Constructs should be exported from the index.ts file. Compiled files will be put in the lib directory. Tests are in the test directory. If you need additional resources that are packaged with your library, add those to a resources directory that is besides the src directory and modify your references accordingly:

const thing = require('../resources/some-resource.json')

Migrating existing projects

Your existing CDK constructs likely have a different file structure than what this projen project expects. Projen projects are highly opinionated. There are a few expectations of this project you should modify your existing library to conform to:

  • All .ts files are expected to be in the src/ directory. Existing constructs should all be moved there. However, you can override this directory by setting srcdir.
  • Compiled .js and .d.ts files will go into the lib/ directory. This directory will be removed and rebuilt each build. Do not store source .ts files in your lib/ or 'libdir'.
  • The entrypoint file for all constructs should be src/index.ts. If your existing library is not in the index.ts file, you can add the following to export it:
export * from './our-s3-bucket'