New Constructs Creation Guide

By design and convention, aws-cdk-lib contains different "levels" of constructs. Since L1 constructs are auto-generated from the AWS CloudFormation resource specification, new resources are automatically released when a new version of the specification is consumed. However, higher level constructs, such as L2 and L3 constructs, are written by hand and therefore do not currently cover 100% of the resources available in cloudformation.

Depending on demand from the community, developers at aws from the aws-cdk team or any other team may contribute L2 constructs that were previously not defined. Additionally, a lot of times users of the aws-cdk from outside of AWS are using a service that currently has no L2 constructs and may wish to create these constructs for themselves and others to use.

If you wish to create new L2 (or potentially L3) constructs, this guide can help you get started.

Consider Mixins First

Before building a full L2 construct, consider whether the functionality you need can be delivered as a Mixin, Facade, or Trait. These composable building blocks work with L1, L2, and custom constructs alike, and are the preferred approach for new features in aws-cdk-lib.

• Mixins modify a resource's own configuration (e.g. enabling versioning, auto-deleting objects). They are applied via .with() and target L1 resources.
• Facades provide resource-specific integrations with external things (e.g. BucketGrants, BucketMetrics). They are standalone classes with a static factory method.
• Traits describe service-agnostic capabilities that any resource can have (e.g. "has a resource policy", "is encrypted"). Facades use Traits to discover capabilities on L1 resources.

A full L2 construct is a composition of these building blocks around a CFN Resource. If you only need one or two features, implementing them as Mixins or Facades is faster, more reusable, and does not require building an entire L2.

For details, see the Design Guidelines and the Mixins Design Guidelines.

A full L2 is still the right choice when you need to provide curated defaults, integrate multiple resources into a single abstraction, or offer a comprehensive opinionated experience for a service.

Do My Constructs Belong in aws-cdk-lib?

Users of the aws-cdk can use constructs from a number of packages within their application. aws-cdk-lib and/or any of the other constructs vended from npm, maven, pypi, nuget, or GitHub (for go) that are publicly available are indexed and searchable on Construct Hub. Anyone can create and publish new constructs that will be indexed on Construct Hub using repositories and packages that they own. However, if you believe your constructs should be part of the core aws construct library, here are some guidelines that they must adhere to.

1. They meet the definition of L2 constructs
2. They follow the relevant design guidelines
3. They can follow the aws-cdk's versioning and release strategy, ie: if they are to be vended in aws-cdk-lib they must be stable or instead be vended in an -alpha package.
4. They provide constructs for a service that intersect with core aws usage patterns. For example, IAM, Lambda, EC2, DynamoDB, RDS, etc. 100% L2 coverage of every AWS service is not a goal of aws-cdk-lib.

If your constructs do not meet these guidelines, see the publishing your own package section of this guide, otherwise, you may choose to publish your own package or open a PR to aws-cdk-lib.

Publishing Your Own Package

Whether you want to pursue inclusion of your new constructs in aws-cdk-lib or not, the easiest way to get started is to create your own package. This will allow you to create, publish, test, and gather feedback on your new constructs as fast as possible without waiting for the aws cdk team to review the design and implementation of them. This also will allow you to deviate from the design and conventions of aws-cdk-lib if you wish to explore a more experimental or alternative api design. This also will enable you to gather feedback from users, make additions and changes, including breaking changes, without worrying about the versioning and support lifecycle of aws-cdk-lib.

To get started creating your own construct package, we recommend using projen. Additionally you can follow this guide which will help you set up your repository, packages and tooling step by step.

Once your constructs have been published for some time and you feel that the apis are stable and bugs have been identified, you can continue to distribute it as a separate package and/or attempt to add them to aws-cdk-lib via a PR.

Open a PR to aws-cdk-lib

You can create a PR in the aws/aws-cdk repository with your constructs at any time if you believe they are ready for inclusion. Here are some cases where opening a PR directly without publishing your own package first is ideal.

1. It is a small addition to a service that has had stable L2 constructs for some time
2. The service usage is well known and the API is unlikely to change.
3. The defaults provided by the L2 are well known best practice

If all of the above are true and your constructs adhere to the relevant guidelines, we encourage you to follow the contributing guide and create a new pull request. Specifically, see the section on within the Design section. Since the bandwidth of the aws-cdk team is limited, reviews and iteration may take some time. Additionally pull requests for new constructs are more likely to be accepted if they have any of the following:

1. An existing package with users who have used and tested the Constructs and provided feedback
2. Strong documentation
3. Good unit and integration test coverage

New Construct Development lifecycle

Whether publishing your own package or making a PR against aws-cdk-lib immediately, the following is the recommended lifecycle for new construct development.

Self Publishing

1. Publish: design, write, and publish your new constructs
2. Iterate: respond to issues from users, fix bugs, optimize usage patterns and gain consensus
3. Stabilize: settle on the api Optionally
4. Upstream: open a PR to aws-cdk-lib to include if still relevant

Alpha CDK Package

1. Design: create a draft PR with the new README detailing the API, socialize, and gain consensus
2. Implement: write the construct as designed and create a new pull request
3. Iterate: respond to feedback from pull request reviewers on the aws-cdk team
4. Publish: publish your new constructs as an alpha module
5. Iterate: respond to issues from users, fix bugs and optimize usage patterns
6. Stabilize: settle on the api and create a new PR migrating all constructs stability to "stable"