Wtf is construct hub

If you've ever seen my github repo you'll know there are a bunch of cdk style projects in there that are usually paired with a blog explaining the details. These are examples of how to develop your own cdk apps but aren't a good example of a reusable construct.

Construct hub was launched towards the end of 2021 (oof, that long already), I vaguely remember the announcement and was keen to understand how it might work. I've always been aware of construct hub, but, tbh it's not front of mind when I'm looking at CDK and I haven't contributed to the catalog.

Let's take a look at construct hub, I'll also provide a very basic example repo that should help others get into construct hub if they wish.

What is construct hub?

What I'm talking about is constructs.dev aka construct hub.

Find and use open-source Cloud Development Kit (CDK) libraries

OK, so what this sounds like is a catalog of all CDK things. This reminds me a little of the npm registry but just for CDK.

When I got to the homepage I notice a few things:

• A global search to find CDK libraries
• A search by publisher which appears to list top libraries split by community, AWS and Hashicorp
• Feature packages

So this looks pretty easy navigate we can assume that if I publish to construct hub that I would appear in the catalog as a community package. It makes sense that there would be other categories e.g. AWS and Hashicorp. When you consider the AWS CDK library this would fall under AWS and Hashicorp makes sense for the terraform providers. Terraform gets a little messy because the providers are often developed by third party companies.

When developing cdk constructs I'm typically following the IntelliSense breadcrumbs and links to the AWS CDK API reference. It looks like constructs hub provides that reference as well (guessing standard doc generation).

TL;DR

Construct hub is a catalog of all CDK libraries that have met the requirements (think package tags, license etc) to be ingested into the catalog. Construct hub provides a standard interface to surface documentation and links about the library that should help developers adopt and contribute to the library.

Note: I mention NPM registry above as a comparison which is still correct imo, but one of the benefits of CDK is the jsii compiler. The benefit here being a library publishing to several different registries e.g. npm and python all discoverable from the same source.

How do you get something into construct hub?

This wasn't super obvious to me, I was guessing it was something along the lines of tagging your project with the correct tags (think npm style package.json) and that would be enough. But, there are a few more things.

If you head over to the contribution docs on construct hub you will see the requirements:

1. Must be published to NPM
2. Must have license (certain types)
3. Must use jsii

There is also a link to a guide that someone has written that probably explains this better than I can, be sure to check it out.

If you do all this right you should see your construct appear in construct hub within about 30 minutes. construct hub seems to be polling at this interval for changes.

While the docs don't say you must use projen it does seem geared around using projen. There are benefits here, projen makes the whole jsii part a tad easier imo. But, projen is super opinionated to the point where it can be frustrating to use. It will come down to where you and your team are at if it's going to work for you. I wrote a piece a while back about project templating (scaffolding) where I touch on projen.

Hello Construct Hub, an npm package

I think the best way to understand construct hub will be to publish something into construct hub. We know we need an NPM package and TypeScript works best for me. I'll be using projen to help get started knowing that we need to use jsii, projen will take care of a few things for us (github actions, build, etc).

I've created a new package hello-construct-hub and published to construct hub. The basic package is my take on the classic hello world, what is a basic IaC package in AWS I wonder? A bucket seems to be the best example I could think of.

The construct will:

1. Extend the existing AWS S3 Bucket Construct
2. Take a single property: name, this will be to...you guessed it name the bucket
3. All defaults remain the same for a bucket (refer to parent class)
4. A bucket deployment will upload the readme.md into the bucket

Diagram

I like diagrams, here is a totally unnecessary simple diagram showing what the new construct provides:

Now, users can use the published package (npm) to create a bucket with a semi predefined naming standard. Room for improvement but you get the idea. You get a simple consistent naming pattern for buckets with a single doc that might help users understand the intent of the bucket.

Because we are using jsii we would also be able to publish this to python as a pip package.

What issues did I find?

• Just projen things, like I said projen is very opinionated so I mainly had issues fighting my existing linters and working within what projen wants me to do (I realise you can override these).
• Github actions failed due to the self mutation action that's added in projen. What this does is run the build steps in an action and compare the output. If there are differences it will commit the changes to your branch. To do this you need a new token in your pipeline (PROJEN_GITHUB_TOKEN). This is optional, the step won't pass until fixed though if you care. The changes are likely docgen API docs that will appear in construct hub which I wanted. Also doing this locally would avoid this.
• You'll need a NPM registry token to publish your package, not an issue to be expected but just calling it out.
• Update your tests, you'll have a boiler plate test that will start failing after you update your construct so be sure to update your tests (not that you'd skip this part...am I right...eh).

Final thoughts

Construct hub is going to suffer the same problem as other registries. Any projen package rightly or wrongly is going to end up in construct hub which may bring the quality of content down or make it harder to find what you're looking for. I wouldn't mind seeing another tag or something as a default for those projects who want to make that effort to publish.

My initial thoughts before digging further into this was that I didn't really see the value in what construct hub was doing. All of this is available in the various registries that you probably already hang out in. But, once I started using it more and understood how things were presented, I concluded that I really should be using this as my go to. I like the standard layout with links to the repo, I like that the AWS CDK library is available here as well and I think the presentation is slightly better than the AWS version.

I think my concerns over using projen with construct hub aren't really a problem, in the end you shouldn't need to use projen to get into construct hub. Just do all the things you need and it will appear. The AWS lib is an example of this.

If you're a heavy CDK TF user I think that the Hashicorp "developed" providers are a little misleading, it would be nice if the original developer flowed through to the platform. The issue likely stems from upstream at the TF provider generation in the AWS CDK TF project. This is minor.

One last thing that is worth a mention is that if you're starting out with CDK this is a good resource and links to other good resources. So when the questions come your way about getting started you can point them at construct hub and they should be able to get started.

TL;DR

Yeah, should probably start using construct even if its to consume other libraries.

Here is a link to the github repo: https://github.com/talkncloud/hello-construct-hub you'll find the construct hub link in this article or in the repo.

Image banner credits: Photo by Matt Ridley on Unsplash