A lot of grey area exists between SAM and the CDK. SAM makes it nice to verify things locally before pushing out to AWS, CDK doesn't provide anything other than seeing your initial stack. So the dev process for the cdk looks like, read docs -> write js -> deploy to CloudFormation (typically a few minutes for anything more than a s3 bucket) -> manually verify -> repeat. Not a fast process at all. Honestly if you could just take the support for local debugging from SAM and give it to the CDK it'd be near perfect.
CDK documentation is pretty confusing. Somewhat understandable given how young it is, but still. Also doesn't help that a lot of the guides that exist are also outdated. Some even coming from AWS themselves. There's also a lot modules in the CDK that are deprecated but left in place which just adds to the confusion. Obviously the docs for a deprecated api shouldn't be neccesarily removed, but maybe some information pertaining to the version that they deprecated it and a guide for migrating would be nice.
Almost feels like there should be a major version separating some of the API's. Certain modules in the package almost play with each other. As in, inside AWS the services are configurable, but inside the CDK certain things don't allow them to be put together. Again kinda goes back to the deprecation issue. There's clearly some deep internal changes that have happened in the CDK but haven't propagated out to the entire library yet, but where those lines are between old and new are about as clear as mud.
The most odd part of the CDK is the fact that everything has to be defined in class constructors. One of the limitations of class constructors is that they have to be synchronous. The JS reasoning behind constructors being synchronous is due to return types. When you define a function as async, the return type automatically becomes
Promise<t>. Which breaks a whole lot of native functionality if you try to do it with a class constructor. However if you've worked with JS in the last 5 years, you'll know that writing strictly synchronous code is not something you do. Even pre async/await almost all of JS was done in callbacks which also doesn't work in CDK code. The reasoning give behind this is
One of the tenets of CDK apps is that given the same source they will always produce the same output (same as a compiler). If you need to perform async operations, it means you are going to the network to consult with an external entity, which by definition means you lose determinism.
Which is clearly a pretty well thought out argument. But as a counter let me pose a situation I've recently encountered, and imagine would be fairly common for any fairly sized non-open source project.
Lets say you're deploying a project with a dependency that is a private github package, but you're building and deploying in AWS and defining those steps via the CDK. In order to install a private github package, you have to have a Personal Access Token from github in your workspace before you can install your dependencies (the first step in your build pipeline). Now the "proper" way to manage this in AWS is via a service called Secrets Manager. It's basically a key/value store with some security related bells and whistles. So now you'll call into this service via one of the SDK's that AWS provides to supply it to your environment, right? ERRRR, not if you're working with the CDK. Since all calls in the CDK have to be synchronous almost (?) the entirety of the JS SDK is off limits. Since the SDK works off either callbacks or promises and nothing else. Both of which are off limits in CDK code.
While finishing writing that ramble, I googled "secrets manager and codebuild" and the top link is AWS CodeBuild Adds Support for AWS Secrets Manager which documents how to integrate Secrets Manager values into your code build environments. So it makes that specific use case moot, but something of that argument still stands in that there is zero interoperability between the CDK and SDK. So with my foot firmly in my mouth I still stand by that as a gripe.
Also if there's interest in seeing a guide for setting up and deploying a serverless TS project, poke me or something.
Sponsor me on Github
Like the article? Buy me a coffee!