Best practices for discoverability of a construct library on Construct Hub

In this blog post, I will provide an overview of best practices to improve the discoverability of your construct libraries on Construct Hub. I will also describe how Construct Hub automates some aspects of the discovery without additional effort from the publisher.

Construct Hub is an online registry of open-source Cloud Development Kit (CDK) libraries published by the open-source community and cloud service providers such as Datadog, MongoDB, Aqua Security, most AWS services, and more.

Construct Hub helps builders create cloud applications using high-level abstractions and familiar programming languages. Each library includes documentation, API reference and code samples in TypeScript, Python, Java and .NET. You can also find installation instructions for each programming language, dependency list, number of downloads, licensing information, and helpful links.

Screenshot of Construct Hub homepage.

Constructs and Construct Hub

Constructs are object-oriented classes which define a “piece of desired state”. Constructs can be composed together to form higher-level building blocks which represent more complex desired state. AWS, enterprises, start-ups, and individual developers use CDK constructs to share proven architecture patterns as reusable code libraries, so that everyone can benefit from the collective wisdom of the community.

Constructs intended for Construct Hub must be published to the npm Registry under Apache, BSD, EPL, MPL-2.0, ISC and CDDL or MIT open source licenses and annotated with a keyword recognized by Construct Hub (awscdk, cdk8s, or cdktf).

Additionally, since one of the main goals of Construct Hub is to enable an ecosystem of constructs that can be consumed by all CDK languages, your library must be compiled with JSII, a TypeScript-based compiler for building multi-language libraries. Construct Hub leverages the type information produced by the JSII compiler to render a rich multi-language experience for each library.

Construct Hub continuously monitors the npm Registry. Packages that meet the above requirements usually appear in Construct Hub in about 5-10 minutes. If your package does not appear in Construct Hub, but meets these requirements, please file an issue against our GitHub repository.

The community has provided some great resources about publishing construct libraries that meet Construct Hub requirements. For example, see “A Beginner’s Guide to Create AWS CDK Construct Library with projen” by hayao-k.

If you already have a library written in TypeScript and want to migrate it to JSII so it can be included in Construct Hub, see the JSII library author guide.

Now that I described how Construct Hub surfaces constructs, I will walk you through the best practices for discoverability of a construct library on Construct Hub.

Best practices

I will use cdk-remote-stack construct library by Pahud Hsieh as an example of applying the best practices explained throughout the section. For each topic, I will show and link to the related location in the source code and how Construct Hub uses this information.

Screenshot of cdk-remote-stack documentation.

1. Helpful description

Publish your library with a description. Libraries without a description have lower chances to be discovered by users. When you write your library’s description, think: Why would someone use it? What makes it unique? Make the description as accurate and differentiated as possible.

Add the description in package.json file:

{
  ...
  "description": "Get outputs and AWS SSM parameters from cross-region AWS CloudFormation stacks",
  ...
}

Construct Hub will display the description under the construct library name:

2. Helpful keywords

Publish your library with helpful keywords, ones that can help potential users to find your package. Helpful keywords can be technologies that are being used by the library, use cases the library is useful for, service names that are being used by the library etc. You can also use any of the category keywords found on the Construct Hub homepage.

Add the keywords field in package.json file:

{
  ...
  "keywords": [
    "aws",
    "cdk",
    "cross-account",
    "cross-region",
    "cross-stack",
    "remote"
  ],
  ...
}

Construct Hub will display the keywords under the construct library name. It will analyze dependencies to infer the CDK type and major version the construct supports.

3. Helpful README

Developer-friendly READMEs help readers quickly understand your library’s relevance to their needs and its unique value compared to similar libraries on the Construct Hub.

I would suggest to have the following structure in a README:

State and maturity of the library
Short description
Code samples
API documentation
Diagrams
Author information
License and support

The examples for the suggested structure that follow are from the cdk-remote-stack README.

3a. State and maturity of the library.

Start your READMEs with helpful badges that help users see the state of your package.

The following badges show latest versions on npm/PyPI and build status:

[![npm version](https://badge.fury.io/js/cdk-remote-stack.svg)](https://badge.fury.io/js/cdk-remote-stack)
[![PyPI version](https://badge.fury.io/py/cdk-remote-stack.svg)](https://badge.fury.io/py/cdk-remote-stack)
[![release](https://github.com/pahud/cdk-remote-stack/actions/workflows/release.yml/badge.svg)](https://github.com/pahud/cdk-remote-stack/actions/workflows/release.yml)

Construct Hub supports the Markdown format and displays the badges as visuals:

3b. Short description.

What does this library do? Which use case does it solve? Which technologies and services does it use or support?

Screenshot of the short description of the library.

3c. Code samples.

Include as many complete and working code samples as you can to help developers quickly understand how they can use your library. Some developers read code samples before anything else. Write your code samples in TypeScript, and Construct Hub will transliterate them to the other programming languages your library supports. A good practice is to include a minimal code sample of how to use your library in the first page of your README. A minimal usage sample should be something that users can copy/paste and immediately use your library with the minimal amount of configuration.

Here is an example in TypeScript from the source:

Example of TypeScript from the source.

I switched to Python language in the Construct Hub, and voilà! Construct Hub automatically transliterated the example to Python language. Construct Hub will enable transliteration for programming languages supported by your construct. This capability saves you time on documenting the construct library for all languages that your construct library supports.

Example of Construct hub transliterating to Python.

3d. API documentation.

Document the library classes, methods, properties in the library’s code using TypeScript JSDocs. Construct Hub will display this information when it automatically generates the API documentation.

Construct Hub automatically generates documentation for the library’s code, and displays the API reference after the README section:

Example of Construct Hub automatically generating documentation.

Selecting a construct will display the class, methods and properties documentation. For example, let’s look at RemoteOutputs construct class:

Screenshot of RemoteOutputs Construct Class.

Construct Hub will generate documentation based on the documentation strings and object types. Importantly, Construct Hub also generates a usage example to help you get started with the construct.

Usage example generated by Construct Hub.

3e. Diagrams.

Diagrams always help readers quickly understand what a library does. Consider adding diagrams for libraries that create multiple services that work together.

Screenshot of diagram example.

3f. Author information.

Share information about you and a helpful link that can improve your credibility with readers.

Add the author field in package.json file:

{
  ...
  "author": {
    "name": "Pahud Hsieh",
    "email": "pahudnet@gmail.com",
    "url": "https://twitter.com/pahudnet",
    "organization": false
  },
  ...
}

Construct Hub will display the author name, and you can click on it to find all construct libraries by that author:

Example of Construct Hub displaying author name.

You can also add an “Author” section in the README for additional visibility.

3g. License and support.

Include a “License” and “Contributing” sections that invite users to contribute via links to your source code repository and issue tracker. Construct Hub shows the license in the construct library’s package page, but it’s convenient to have both in the README too.

Screenshot of contributing section.

The license is also shown as part of the package metadata:

Screenshot of package metadata.

4. AWS Partner Network (APN) badge

If you’re an AWS partner and you are publishing a library for your offering, please reach out to us.

Conclusion

Construct Hub aims to simplify cloud development. Builders can solve for various use cases with pre-built constructs provided by you, the publishers. Following the best practices mentioned in this blog post can help to improve your construct library(ies) discoverability on the Construct Hub.

If you have any feedback, open an issue for any discoverability features that you would like to see added. Navigate to https://constructs.dev/contribute to learn more about publishing constructs. The Construct Hub FAQ contains additional details on the project. You are also welcome to join the #construct-hub-dev channel in CDK community Slack workspace.

AWS Open Source Blog