@exanubes/cdk

A custom nx plugin for working with aws cdk with typescript in a nx monorepo

Getting started

Install the plugin in your nx project with npm i -D @exanubes/cdk and generate a new cdk app with npx nx g @exanubes/cdk:init my-new-cdk-app

Generators

Init

This is an equivalent of cdk init sample-app --language=typescript with an altered file structure. It will create a new project using the appsDir.

Options

| Option | Alias | Description | Required | | ------------------------ | :----: | :-------------------------------------------------------------------------------------------------------------------------------- | -------- | | cloudFormationAccessRole | cfrole | aws role that will be assumed by cloudformation when deploying/destroying infrastructurename of the lambda project for this event | ✅ | | directory | | nx default behaviour | |

Example

npx nx g @exanubes/cdk:init sample-app --directory=infrastructure --cloudFormationAccessRole=exanubes-access-role

CREATE app/infrastructure/sample-app/project.json
CREATE app/infrastructure/sample-app/cdk.json
CREATE app/infrastructure/sample-app/src/config.ts
CREATE app/infrastructure/sample-app/src/index.ts
CREATE app/infrastructure/sample-app/tsconfig.json
UPDATE package.json

Stack

Options

| Option | Alias | Description | Required | | --------- | :---: | :------------------- | -------- | | directory | | nx default behaviour | |

Example

Create one

npx nx g @exanubes/cdk:stack comment-section --directory=stacks --lib

CREATE lib/stacks/comment-section/project.json
CREATE lib/stacks/comment-section/src/comment-section.stack.ts
CREATE lib/stacks/comment-section/src/index.ts
CREATE lib/stacks/comment-section/tsconfig.json
UPDATE tsconfig.base.json

Create multiple

You can create multiple stacks at once by using comma-separated names

npx nx g @exanubes/cdk:stack comment-section,api-gateway,cognito,database --directory=stacks

CREATE lib/stacks/comment-section/project.json
CREATE lib/stacks/comment-section/src/comment-section.stack.ts
CREATE lib/stacks/comment-section/src/index.ts
CREATE lib/stacks/comment-section/tsconfig.json
UPDATE tsconfig.base.json
CREATE lib/stacks/api-gateway/project.json
CREATE lib/stacks/api-gateway/src/api-gateway.stack.ts
.
.
.

Lambda

Creates a new lib with lambda stack and handler code.

It uses the NodejsFunction construct from aws-cdk-lib/aws-lambda-nodejs to bundle the code with esbuild when synthesizing with cdk.

Among the files generated is also a package.json. This package.json should contain all the dependencies that should be bundled with the lambda, however, dependencies should be installed in monorepo root, not in the lambda lib.

Best approach would be to move the dependencies to a Lambda Layer and add it to excluded modules.

** Did not test with Docker Images yet **

Options

| Option | Alias | Description | Required | | --------- | :---: | :----------------------------------------------- | -------- | | project | | Infrastructure project that will use this lambda | | | directory | | nx default behaviour | |

Example

Create one

npx nx g @exanubes/cdk:lambda create-comment --directory=lambdas

CREATE lib/lambdas/create-comment/project.json
CREATE lib/lambdas/create-comment/package.json
CREATE lib/lambdas/create-comment/src/create-comment.handler.ts
CREATE lib/lambdas/create-comment/src/create-comment.ts
CREATE lib/lambdas/create-comment/src/index.ts
CREATE lib/lambdas/create-comment/tsconfig.json
UPDATE app/infrastructure/sample-app/project.json
UPDATE tsconfig.base.json
UPDATE package.json

Create multiple

You can create multiple lambdas at once by using comma-separated names

npx nx g @exanubes/cdk:lambda create,list,update,remove --directory=lambdas/comments

CREATE lib/lambdas/comments/create/project.json
CREATE lib/lambdas/comments/create/package.json
CREATE lib/lambdas/comments/create/src/create.handler.ts
CREATE lib/lambdas/comments/create/src/create.ts
CREATE lib/lambdas/comments/create/src/index.ts
CREATE lib/lambdas/comments/create/tsconfig.json
UPDATE tsconfig.base.json
UPDATE package.json
CREATE lib/lambdas/comments/list/project.json
CREATE lib/lambdas/comments/list/package.json
CREATE lib/lambdas/comments/list/src/list.handler.ts
.
.
.

Layer

Creates a new lib with two constructs and a separate directory for layer code as well as adding a lambda env path alias for importing code from layer inside a lambda handler e.g., /opt/nodejs/database

The layer is split into two constructs Read/Write. This is due to an issue with updating layer versions. Read more in this github issue

Example

Create one

npx nx g @exanubes/cdk:layer dynamodb --directory=layers

CREATE lib/layers/dynamodb/project.json
CREATE lib/layers/dynamodb/src/dynamodb.layer.ts
CREATE lib/layers/dynamodb/src/const.ts
CREATE lib/layers/dynamodb/src/index.ts
CREATE lib/layers/dynamodb/src/layer/dynamodb.ts
CREATE lib/layers/dynamodb/src/layer/index.ts
CREATE lib/layers/dynamodb/src/read-dynamodb.layer.ts
CREATE lib/layers/dynamodb/tsconfig.json
UPDATE tsconfig.base.json

Create multiple

You can create multiple layers at once by using comma-separated names

npx nx g @exanubes/cdk:layer database,users,comments --directory=layers

CREATE lib/layers/database/project.json
CREATE lib/layers/database/src/database.layer.ts
CREATE lib/layers/database/src/const.ts
CREATE lib/layers/database/src/index.ts
CREATE lib/layers/database/src/layer/database.ts
CREATE lib/layers/database/src/layer/index.ts
CREATE lib/layers/database/src/read-database.layer.ts
CREATE lib/layers/database/tsconfig.json
UPDATE tsconfig.base.json
CREATE lib/layers/users/project.json
CREATE lib/layers/users/src/users.layer.ts
.
.
.

Event

Creates an event and adds an executor to target lambda's project.json which uses SAM for locally invoking the lambda.

Creates an event directory with [event_name].event.json name template.

Creates template.yml file in lib root for SAM

Creates invoke.js file in lib root for invoking the lambda

Creates local-invoke.env.json file in project root for defining environment variables

| Option | Alias | Description | Required | | ------------ | :---: | :----------------------------------------------------------------------------------------------------------------------------- | :------: | | project | | name of the lambda project for this event | ✅ | | source | | aws service that is the source of the event. If left empty it will show a prompt with all possible options | ✅ | | type | | type of the event based on the source selected. If unsure, leave it empty or write anything, and it will show possible options | ✅ | | runtime | | node version to be used. If left empty it will show a prompt with all possible options. For now, only nodejs is supported | ✅ | | functionName | fn | function name to be used in the template.yml | | | skipTemplate | skip | will not create invoke.js and template.yml files. Useful when files were moved from their original location | |

Example

npx nx g @exanubes/cdk:event authorizer-create-comment --source=apigateway --type=authorizer --project=lambdas-create-comment --runtime=nodejs18.x

CREATE lib/lambdas/create-comment/events/authorizer-create-comment.event.json
UPDATE lib/lambdas/create-comment/project.json

Invoke

In order to invoke the lambda we first need to bundle all the code together with npx nx lambdas-create-comment:build. Which will bundle all the code and dependencies into a single app.js file and put it in /dist/path/to/lib

Once that's done we can invoke the lambda with npx nx lambdas-create-comment:invoke. Which will actually just run the invoke.js file.

In case of an error asking if you have a Docker running (and you do), add a --docker-host flag to the command.

The invoke.js file is responsible for actually running the SAM local invoke, however, it does more than that. Based on the layerNames array, it will use the aws cli to find the layerVersion ARNs that your lambda depends on. In case you have multiple event sources and want to test it against each one, you can pass it an event name. By default it will use the first event that was generated.