Nx-serverless-cdk NPM

nx-serverless-cdk

nx-serverless-cdk is an Nx plugin for creating AWS CDK applications and construct libraries inside an Nx monorepo. It offers the possibility to test and debug infrastructure code and AWS Lambda functions locally. The plugin provides the full flexibility of the AWS CDK CLI and the local AWS SAM CLI commands. It aims to make the usage of these tools as easy as possible inside an Nx monorepo.

Plugin Features

Define the infrastructure as code (IaC)
The infrastructure and application code as well as the configurations are evolved together in one place
Test and debug the infrastructure and application code locally
- Test and debug API Gateway routes that are handled by Lambda functions locally
Use E2E tests to verify the correctness of the cloud applications
Create and share reusable infrastructure definitions (Construct Libraries)
- Publish libraries to npm
Generate test events for Lambda functions
- Use generated events for local and E2E testing
Write everything in TypeScript

AWS CDK Features

High-level constructs that automatically provide sensible, secure defaults
Use programming languages to model your system design
Employ practices such as code reviews, unit tests, and source control to make your infrastructure more robust
Connect your AWS resources together (even across stacks)
Grant permissions using simple, intent-oriented APIs
Import existing AWS CloudFormation templates to give your resources a CDK API
Perform infrastructure deployments predictably and repeatedly, with rollback on error
Easily share infrastructure design patterns among teams within your organization or even with the public

Getting Started

Prerequisites

Install the AWS CLI to authenticate
- SSO via the AWS IAM Identity Center is currently not handled correctly if a separate sso-session section exists in the AWS CLI configuration. This issue can be solved by merging the sso-session section into the profile section.
Install the AWS SAM CLI for local testing and debugging
Install Docker to run your Lambda functions locally (Docker Desktop or Docker Engine)
- Please note, if you want to test Lambda functions locally on a different instruction set architecture than your host machine, additional steps are necessary
Use an existing Nx monorepo or follow the steps below to create a new Nx monorepo

Create a new Nx Monorepo

An empty monorepo can be created with the following command

npx create-nx-workspace@latest --name <WorkspaceName> --preset "apps" --workspaceType "integrated"

The package manager can be chosen freely by using the --packageManager option (e.g. choose pnpm or yarn). The default is npm which is used for the following sections.

Change the working directory to the workspace root of the Nx monorepo

cd <WorkspaceName>

Install

Run the following command in the workspace root directory to install the nx-serverless-cdk plugin

npm install --save-dev nx-serverless-cdk

CDK Application

A CDK application consists of the infrastructure and application code as well as the configurations that together form a cloud application.

Constructs are the basic building blocks of a CDK application. They represent either individual cloud resources or a set of cloud resources that have been interconnected to fulfill a concrete purpose. Inside the application, the constructs are combined into deployable units called stacks.

Create a CDK Application

To create a serverless application run the following command inside the Nx workspace

nx g nx-serverless-cdk:cdk-app <AppName> --type lambda

If the application should only contain infrastructure definitions (generic application) run the following command

nx g nx-serverless-cdk:cdk-app <AppName> --type generic

These commands will create an <AppName> directory in the root of the Nx workspace. Use the --directory option to define another directory for the application. Please note that the created directory is relative to the current working directory.

Note: Use npx nx, if the nx command isn't found or install the nx package globally.

Environments

The generated example code has support for 3 environments

Dev
- Test new features and bugfixes during the development
Stage
- Quality assurance
- Test upcoming releases
- Mimics the production environment
Prod
- The production environment
- Makes the application available to its consumers

These environments are just examples, the environment names as well as their count can be changed according to the project's needs.

CDK Application Structure

cdk contains the infrastructure code and tests
- main.ts entry point of the CDK application
- app.ts defines the configurations for all environments
  - Multiple stacks might be deployed per environment (e.g. to cover multiple regions)
events used store generated or manually created events for local and E2E testing
shared contains the shared code which is used by the infrastructure and runtime code
src contains the runtime code and tests (e.g. Lambda function handlers)
- example-api-handler.ts* entry point of the example API Lambda function
- example-handler.ts* entry point of the example Lambda function
.env defines the environment variables for the application commands
- Used to enable the CDK debug mode
- Used to define the AWS accounts and regions for the deployment
- The environment variables can be overridden if needed
.env.test used to activate the debug mode for the Jest testing framework
.eslintrc.json ESLint configuration
.gitignore defines the files that are excluded from version control
cdk.json AWS CDK configuration
jest.config.ts Jest testing framework configuration
project.json Nx application configuration
samconfig.toml* AWS SAM configuration
start-cdk.mjs ignore this script, it is used to make the debugging of CDK applications possible
tsconfig.cdk.json TypeScript infrastructure code configuration
tsconfig.json common TypeScript CDK application configuration
tsconfig.spec.json TypeScript test code configuration
tsconfig.src.json TypeScript runtime code configuration

*Is created for serverless CDK applications

Format the CDK Application

The projects (applications and libraries) that have been changed since the last commit can be formatted with the help of nx format.

nx format

To format all projects execute

nx format --all

To format only the application execute

nx format --projects <AppName>

Lint the CDK Application

To lint the application execute

nx lint <AppName>

nx run <AppName>:lint

Test the CDK Application (with Code Coverage)

To test the application execute

nx test <AppName>

nx run <AppName>:test

Add the --codeCoverage option to enable code coverage.

nx run <AppName>:test --codeCoverage

Watch

To automatically rerun the application tests after a file has been changed, execute

nx run <AppName>:test --watch

Debug

Add the debugger; statement to the code at the location where the debugging session should start.

In the .env.test file uncomment the NODE_OPTIONS variable.

Execute the test command with the --runInBand option

nx run <AppName>:test --runInBand

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Synthesize CloudFormation Stacks

To synthesize all Dev environment stacks execute

nx run <AppName>:cdk synth "Dev/*" --profile <AwsCliDevEnvironmentProfile>

or use the shorthand command

nx run <AppName>:synth -c dev --profile <AwsCliDevEnvironmentProfile>

nx run <AppName>:synth:dev --profile <AwsCliDevEnvironmentProfile>

Use the .env file to define the AWS accounts and regions for the environments. If the environment variables aren't defined, the account and region are retrieved from the AWS CLI profile. Please note that the AWS CLI profile values might vary per user.

The synthesized CloudFormation stacks are stored in cdk.out.

Note: If SSO is used to authenticate, then it is required to log in before executing this command.

Debug

Add the debugger; statement to the infrastructure code at the location where the debugging session should start.

In the .env file set CDK_DEBUG to true.

Synthesize all Dev environment stacks.

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Invoke a Lambda Function Locally

Synthesize all Dev environment stacks.

Open the cdk.out directory and search for the Dev environment CloudFormation template, which should have a file name similar to DevAdventialsE766A003.template.json. Copy the file name.

To invoke the example Lambda function locally with the test event stored in events/sum/sum7.json execute

nx run <AppName>:invoke ExampleFunction -t cdk.out/<DevTemplateJson> -e "events/sum/sum7.json"

The Lambda function result {"sum": 7} is printed out to the console. If this command is executed for the first time, it might take a while since the Lambda Docker image has to be pulled first.

Debug

Add the debugger; statement to the runtime code at the location where the debugging session should start.

Synthesize all Dev environment stacks.

In the samconfig.toml file uncomment the debug_port variable of the [default.local_invoke.parameters] section.

Invoke a Lambda function locally.

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Start all Lambda Functions Locally

Synthesize all Dev environment stacks.

Open the cdk.out directory and search for the Dev environment CloudFormation template, which should have a file name similar to DevAdventialsE766A003.template.json. Copy the file name.

To start all Lambda functions locally execute

nx run <AppName>:start-lambda -t cdk.out/<DevTemplateJson>

If this command is executed for the first time, it might take a while since the Lambda Docker image has to be pulled first. The following message is printed out to the console

 * Running on http://127.0.0.1:3001

Find the example function resource name in the cdk.out/<DevTemplateJson>, which should be similar to ExampleFunctionB28997EC.

To invoke the example Lambda function execute

aws lambda invoke response.json --function-name <ExampleFunctionResourceName> --endpoint-url "http://127.0.0.1:3001" --payload "fileb://<AppName>/events/sum/sum7.json" --region <DevRegion> --profile <DevProfile>

The Lambda function result {"sum": 7} is stored in the <WorkspaceRoot>/response.json file.

The @aws-sdk/client-lambda package can also be used to invoke a Lambda function

import { InvocationType, InvokeCommand, LambdaClient, LogType } from '@aws-sdk/client-lambda';
import { fromSSO } from '@aws-sdk/credential-providers';
import { readFile } from 'node:fs/promises';
import { join, resolve } from 'node:path';

const lambdaClient = new LambdaClient({
  credentials: fromSSO({
    profile: '<DevProfile>',
  }),
  region: '<DevRegion>',
  endpoint: 'http://127.0.0.1:3001',
  maxAttempts: 3,
});

const payload = await readFile(resolve(join('<WorkspaceRoot>', '<AppName>', 'events/sum/sum7.json')), { encoding: 'utf-8' });

const response = await lambdaClient.send(
  new InvokeCommand({
    FunctionName: '<ExampleFunctionResourceName>',
    InvocationType: InvocationType.RequestResponse,
    LogType: LogType.None,
    Payload: payload,
  }),
);

Debug

Add the debugger; statement to the runtime code at the location where the debugging session should start.

Synthesize all Dev environment stacks.

In the samconfig.toml file uncomment the debug_port variable of the [default.local_start_lambda.parameters] section.

Start all Lambda functions and invoke an individual Lambda function locally.

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Start an API Gateway Locally

Synthesize all Dev environment stacks.

Open the cdk.out directory and search for the Dev environment CloudFormation template, which should have a file name similar to DevAdventialsE766A003.template.json. Copy the file name.

To start an API Gateway locally execute

nx run <AppName>:start-api -t cdk.out/<DevTemplateJson>

If this command is executed for the first time, it might take a while since the Lambda Docker image has to be pulled first. The following message is printed out to the console

 * Running on http://127.0.0.1:3000

To call the endpoint product execute

curl -i "http://127.0.0.1:3000/product?a=5&b=7"

The result {"product":35} is printed out to the console.

Debug

Add the debugger; statement to the runtime code at the location where the debugging session should start.

Synthesize all Dev environment stacks.

In the samconfig.toml file uncomment the debug_port variable of the [default.local_start_api.parameters] section.

Start an API Gateway locally and call an endpoint.

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Deploy the CDK Application

Bootstrap

The AWS CDK bootstraps an account and region combination by deploying a predefined bootstrap CloudFormation stack to it.

The bootstrap stack has to be deployed only once before multiple deployments can take place. If no bootstrap resources are required, an account and region combination doesn't have to be bootstrapped.

Execute the following command for every account and region combination that should be bootstrapped

nx run <AppName>:cdk bootstrap "<AwsAccountNumber>/<AwsRegion>" --profile <AwsCliEnvironmentProfile>

Re-run this command to update the bootstrap CloudFormation stack in place.

Deploy

To deploy all Dev environment stacks execute

nx run <AppName>:cdk deploy "Dev/*" --profile <AwsCliDevEnvironmentProfile>

or use the shorthand command

nx run <AppName>:deploy -c dev --profile <AwsCliDevEnvironmentProfile>

nx run <AppName>:deploy:dev --profile <AwsCliDevEnvironmentProfile>

To deploy all Stage environment stacks execute

nx run <AppName>:deploy:stage --profile <AwsCliStageEnvironmentProfile>

To deploy all Prod environment stacks execute

nx run <AppName>:deploy:prod --profile <AwsCliProdEnvironmentProfile>

Note: If SSO is used to authenticate, then it is required to log in before executing this command.

Watch

To automatically rerun the deployment after a file has been changed, execute

nx run <AppName>:watch:dev --profile <AwsCliDevEnvironmentProfile>

The AWS CDK CLI will try to directly update the affected services (hotswap). By appending the --hotswap-fallback option, a CloudFormation deployment will be performed if a direct service update isn't feasible.

nx run <AppName>:watch:dev --profile <AwsCliDevEnvironmentProfile> --hotswap-fallback

Note: The AWS CDK watch mode is meant for development deployments and shouldn't be used to deploy production resources.

Deploy the CDK Application and its Dependencies

The situation might arise that a cloud resource is needed by multiple CloudFormation stacks of the same application. In this case, the cloud resource could be easily shared between the stacks by introducing a shared stack.

If the cloud resource is needed by multiple CDK applications, then it makes sense to introduce a shared application. The shared application should be deployed before the applications that depend on it.

If multiple applications depend on a shared application, then they have to declare this dependency explicitly. Every application that depends on the shared application has to set the following property in their project.json file

{
  ...
  "implicitDependencies": ["<SharedAppName>"],
  ...
}

The dependencies between applications and libraries can be checked via the following command

nx graph

If an application and all the applications it depends on should be deployed to the Dev environment, then the following command can be executed

nx run <AppName>:deploy-all:dev --profile <AwsCliDevEnvironmentProfile> --verbose

A similar command could be executed for the Stage and Prod environment. This command uses the Nx dependency graph to determine the deployment order. The given command-line arguments are used for every application deployment in the dependency chain.

The following command could be used in a CI/CD pipeline to deploy all applications that have been changed and the applications they depend on

nx affected -t deploy-all -c dev --profile Dev --verbose --require-approval never --ci

Nx determines if an application has changed by a given git commit range. Please consult the Nx documentation for further details.

Note: If SSO is used to authenticate, then it is required to log in before executing this command.

E2E Testing

Testing in the Cloud

Testing serverless applications in the cloud is the testing technique that is preferred by AWS. It offers the following benefits

You can test every available service.
You are always using the most recent service APIs and return values.
A cloud test environment closely resembles your production environment.
Tests can cover security policies, service quotas, configurations and infrastructure-specific parameters.
Every developer can quickly create one or more testing environments in the cloud.
Cloud tests increase confidence your code will run correctly in production.

The AWS CDK supports this testing technique with its watch mode. The AWS CDK watch mode offers direct AWS resource updates and as a fallback CloudFormation deployments without rollback. These features significantly speed up the deployment of incremental changes during the development.

Note: The AWS CDK watch mode is meant for development deployments and shouldn't be used to deploy production resources.

Execute the E2E Tests

This plugin supports testing in the cloud by creating an E2E application for every CDK application. The E2E tests are used to ensure that the cloud application works as expected.

Please set the environment-specific profile and region in the .env.e2e file of the E2E application. Use the E2E_ENVIRONMENT environment variable to specify the environment that should be tested.

Deploy the application into the specified environment.

To run the E2E tests against the specified environment execute

nx run <AppName>-e2e:e2e

Add the --codeCoverage option to enable code coverage.

nx run <AppName>-e2e:e2e --codeCoverage

Watch

To automatically rerun the E2E tests after a file has been changed, execute

nx run <AppName>-e2e:e2e --watch

Debug

Add the debugger; statement to the code at the location where the debugging session should start.

In the .env.e2e file uncomment the NODE_OPTIONS variable.

Execute the E2E test command with the --runInBand option

nx run <AppName>-e2e:e2e --runInBand

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Generate an Event

Lambda functions are invoked with events. These events are either AWS service-specific events or custom events.

Mock events are regularly needed for local and E2E testing. They can be stored inside the events directory of the CDK application or E2E application.

The generate-event command can be used to create AWS service-specific mock events. In the following example, a mock event is created for a Lambda function that is invoked on a regular schedule

nx run <AppName>:generate-event cloudwatch scheduled-event --region eu-central-1

The following command has to be executed for the E2E application

nx run <AppName>-e2e:generate-event cloudwatch scheduled-event --region eu-central-1

The generated event is printed out to the console. It can be copied and stored in a new file inside the events directory.

CDK Application Commands Reference

lint

nx run <AppName>:lint [Options]

The lint command is used to lint the application with ESLint (see Lint the CDK Application).

Options:

--help
- Displays the command options

test

nx run <AppName>:test [Options]

The test command is used to execute the test cases with Jest (see Test the CDK Application (with Code Coverage)).

Options:

--help
- Displays the command options

cdk

nx run <AppName>:cdk [Options]

The cdk command is used to interact with the AWS CDK.

Options:

-h
- Displays the command options

Configuration Options:

predefinedArguments
- Used to predefine arguments that are put at the beginning of the command

deploy

nx run <AppName>:deploy:<EnvironmentConfiguration> [Options]

Shorthand command for cdk deploy. Deploys one or more specified stacks (see Deploy the CDK Application).

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

deploy-all

nx run <AppName>:deploy-all:<EnvironmentConfiguration> --verbose [Options]

Shorthand command for cdk deploy. Deploys one or more specified stacks.

The command is executed for the application and every application in the application's dependency tree. The individual commands are executed in dependency order starting with the leaves of the dependency tree (see Deploy the CDK Application and its Dependencies).

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

destroy

nx run <AppName>:destroy:<EnvironmentConfiguration> [Options]

Shorthand command for cdk destroy. Destroys one or more specified stacks.

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

diff

nx run <AppName>:diff:<EnvironmentConfiguration> [Options]

Shorthand command for cdk diff. Compares the specified stacks and its dependencies with the deployed stacks.

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

ls

nx run <AppName>:ls:<EnvironmentConfiguration> [Options]

Shorthand command for cdk ls. Lists the IDs of the specified stacks.

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

synth

nx run <AppName>:synth:<EnvironmentConfiguration> [Options]

Shorthand command for cdk synth. Synthesizes the specified stacks into CloudFormation templates (see Synthesize CloudFormation Stacks).

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

watch

nx run <AppName>:watch:<EnvironmentConfiguration> [Options]

Shorthand command for cdk watch. Continuously monitors the application's source files and assets for changes. It immediately performs a deployment of the specified stacks when a change is detected.

The environment configuration is dev, stage or prod (can be adjusted).

Options:

-h
- Displays the command options

generate-event

nx run <AppName>:generate-event [Options]

The generate-event command is used to generate AWS service-specific mock events (see Generate an Event).

Options:

-h
- Displays the command options

Configuration Options:

predefinedArguments
- Used to predefine arguments that are put at the beginning of the command

invoke

nx run <AppName>:invoke [Options]

The invoke command is used to invoke a Lambda function locally (see Invoke a Lambda Function Locally).

Options:

-h
- Displays the command options

Configuration Options:

predefinedArguments
- Used to predefine arguments that are put at the beginning of the command

start-api

nx run <AppName>:start-api [Options]

The start-api command is used to start an API Gateway locally (see Start an API Gateway Locally).

Options:

-h
- Displays the command options

Configuration Options:

predefinedArguments
- Used to predefine arguments that are put at the beginning of the command

start-lambda

nx run <AppName>:start-lambda [Options]

The start-lambda command is used to start all Lambda functions locally (see Start all Lambda Functions Locally).

Options:

-h
- Displays the command options

Configuration Options:

predefinedArguments
- Used to predefine arguments that are put at the beginning of the command

E2E Application Commands Reference

lint

nx run <AppName>-e2e:lint [Options]

The lint command is used to lint the application with ESLint.

Options:

--help
- Displays the command options

e2e

nx run <AppName>-e2e:e2e [Options]

The e2e command is used to execute the E2E tests with Jest (see E2E Testing).

Options:

--help
- Displays the command options

generate-event

nx run <AppName>-e2e:generate-event [Options]

The generate-event command is used to generate AWS service-specific mock events (see Generate an Event).

Options:

-h
- Displays the command options

Configuration Options:

predefinedArguments
- Used to predefine arguments that are put at the beginning of the command

Construct Library

Constructs can be composed of self-written or third-party constructs. The AWS Construct Library contains the constructs for AWS resources. Its constructs can be categorized into 3 levels

L1 constructs
- Represent CloudFormation resources
- Are automatically generated
L2 constructs
- Represent AWS resources
- Intent-based API
L3 constructs
- Patterns
- Often involve multiple resources

A vast collection of third-party open-source construct libraries can be found on Construct Hub.

Constructs are a great way to define organization or project standards. They can be grouped in a construct library and shared between multiple CDK applications.

Create a Construct Library

To create a construct library run the following command inside the Nx workspace

nx g nx-serverless-cdk:cdk-lib <LibName> --importPath <LibPackageName>

The --importPath option defines the construct library's package name. The construct library can be imported into other construct libraries or CDK applications inside the Nx monorepo.

To use the construct library outside the monorepo, it can be published to an npm repository. Execute the following command to create a publishable construct library that uses the value of --importPath as the npm package name

nx g nx-serverless-cdk:cdk-lib <LibName> --importPath <LibPackageName> --publishable

These commands will create an <LibName> directory in the root of the Nx workspace. Use the --directory option to define another directory for the construct library. Please note that the created directory is relative to the current working directory.

Note: Use npx nx, if the nx command isn't found or install the nx package globally.

Construct Library Structure

cdk contains the infrastructure code and tests
- index.ts entry point of the construct library
.env.test used to activate the debug mode for the Jest testing framework
.eslintrc.json ESLint configuration
jest.config.ts Jest testing framework configuration
package.json npm package configuration
- Used to configure the construct library's npm package that is published to an npm repository
- To install dependencies that are used inside the monorepo, use the workspace package.json file instead
project.json Nx library configuration
README.md construct library documentation
tsconfig.cdk.dts.json TypeScript infrastructure declarations configuration
tsconfig.cdk.json TypeScript infrastructure code configuration
tsconfig.json common TypeScript construct library configuration
tsconfig.spec.json TypeScript test code configuration

Format the Construct Library

The projects (applications and libraries) that have been changed since the last commit can be formatted with the help of nx format.

nx format

To format all projects execute

nx format --all

To format only the construct library execute

nx format --projects <LibName>

Lint the Construct Library

To lint the construct library execute

nx lint <LibName>

nx run <LibName>:lint

Test the Construct Library (with Code Coverage)

To test the construct library execute

nx test <LibName>

nx run <LibName>:test

Add the --codeCoverage option to enable code coverage.

nx run <LibName>:test --codeCoverage

Watch

To automatically rerun the construct library tests after a file has been changed, execute

nx run <LibName>:test --watch

Debug

Add the debugger; statement to the code at the location where the debugging session should start.

In the .env.test file uncomment the NODE_OPTIONS variable.

Execute the test command with the --runInBand option

nx run <LibName>:test --runInBand

A message is printed out to the console similar to the one below

Debugger listening on ws://127.0.0.1:9229/15755f9f-6e5d-4c5e-917b-d2b8e9dec5d2

Any Node.js debugger can be used for debugging. In this example, the Chrome browser will be used.

Use the Construct Library

The construct library can be imported into other construct libraries or CDK applications. Use the following code snippet to import the ExampleConstruct

import { ExampleConstruct } from '<LibPackageName>';

Please note that the construct library doesn't have to be built to be imported by its consumers.

Build the Construct Library

To build the construct library execute

nx run <LibName>:build

The build output is written to <WorkspaceRoot>/dist/<LibName>.

Publish to npm

To publish the construct library to npm execute

nx run <LibName>:publish --ver <LibVersion> --tag <LibVersionTag>

Construct Library Commands Reference

lint

nx run <LibName>:lint [Options]

The lint command is used to lint the construct library with ESLint (see Lint the Construct Library).

Options:

--help
- Displays the command options

test

nx run <LibName>:test [Options]

The test command is used to execute the test cases with Jest (see Test the Construct Library (with Code Coverage)).

Options:

--help
- Displays the command options

build

nx run <LibName>:build [Options]

The build command is used to build the construct library with esbuild (see Build the Construct Library). The build-declarations command is always executed before the build command.

Options:

--help
- Displays the command options

build-declarations

nx run <LibName>:build-declarations [Options]

The build-declarations command is used to create the construct library's TypeScript declarations with the TypeScript compiler (see Build the Construct Library).

Options:

--help
- Displays the command options

publish

nx run <LibName>:publish [Options]

The publish command is used to publish the construct library to an npm repository (see Publish to npm).

Options:

--ver
- Construct library version
--tag
- Tag of the version (e.g. latest)

TypeScript Library

A pure TypeScript library can be created with Nx and shared between construct libraries and CDK applications.

Create a TypeScript Library

To create a TypeScript library run the following command inside the Nx workspace

nx g @nx/js:library <LibName> --importPath <LibPackageName> --bundler tsc --unitTestRunner jest

The --importPath option defines the TypeScript library's package name. The TypeScript library can be imported into construct libraries or CDK applications inside the Nx monorepo.

To use the TypeScript library outside the monorepo, it can be published to an npm repository. Execute the following command to create a publishable TypeScript library that uses the value of --importPath as the npm package name

nx g @nx/js:library <LibName> --importPath <LibPackageName> --publishable --bundler tsc --unitTestRunner jest

These commands will create an <LibName> directory in the root of the Nx workspace. Use the --directory option to define another directory for the TypeScript library. Please note that the created directory is relative to the current working directory.

Adjust the TypeScript configurations (tsconfig*.json) according to the project standards.

Note: Use npx nx, if the nx command isn't found or install the nx package globally.

Use the TypeScript Library

The TypeScript library can be imported into construct libraries or CDK applications. Use the following code snippet to import it

import { ... } from '<LibPackageName>';

Please note that the TypeScript library doesn't have to be built to be imported by its consumers.

Debug in Chrome

Open a new tab in the Chrome browser and navigate to chrome://inspect.

Click on Open dedicated DevTools for Node and navigate in the new window to the Sources tab.

Wait for the source code to appear and then click on the play button (Resume script execution) in the right panel.

The debugger jumps to the debugger; statement that has been added to the source code. Move from this point onward by using the debugger step commands and additional breakpoints.

Generators Reference

cdk-app

nx g nx-serverless-cdk:cdk-app <AppName> --type <AppType>

The cdk-app generator is used to create an AWS CDK application (see Create a CDK Application).

Options:

--name (required)
- CDK application name
--directory
- The CDK application's directory path relative to the current working directory
--type (required)
- The CDK application type can be generic or lambda
- Choose the type generic for general-purpose applications
- Choose the type lambda for serverless applications
--skipFormat (default: false)
- Skips the formatting after the CDK application has been created

cdk-lib

nx g nx-serverless-cdk:cdk-lib <LibName> --importPath <LibPackageName>

The cdk-lib generator is used to create an AWS CDK construct library (see Create a Construct Library).

Options:

--name (required)
- Construct library name
--directory
- The construct library's directory path relative to the current working directory
--importPath
- Defines the npm package name (e.g. example-lib or @example-org/example-lib)
--publishable
- Creates a construct library that can be published to an npm repository
--skipFormat (default: false)
- Skips the formatting after the construct library has been created