Lerna Monorepo CDK example

FIRST THINGS FIRST

install lerna globally
install cdk globally

PROJECT STRUCTURE

packages/cdk-app contains normal cdk package which depends on our lambda packages
packages/lambda-a is a normal typescript lambda
packages/lambda-b is a normal typescript lambda
packages/common-lambda-lib is a common nodejs package used in both lambdas

TYPESCRIPT CONFIGURATION

there are 3 tsconfig files in the root of the project.

tsconfig.build.json - this is our base tsconfig file that all nested packages extend so we dont have to duplicate all the configs in this one. This tsconfig is used / called whenever we run yarn run build
tsconfig.json - this extends the above tsconfig. We have one for the entire project and this is configured to give us nice intellisense in VSCODE
tsconfig.test.json - this config is used by jest in our jest testing environment

WEBPACK CONFIGURATION

we use webpack to build of our lambdas (not common libraries used in the lambdas, these are built using typescript compiler only)
we have a root webpack.config.build.json which all common lambdas extend so we dont have to repeat ourselves.
in the root webpack.config, when we build our lambda code, we have to rename the package name of the compiled lambdas in the cdk.out directory and dist folder. This is to avoid naming conflicts when we use lambda as no 2 packages can have the same name.

Lambda CONFIGURATION

lambdas use webpack to be built

COMMON LIBRARY CONFIGURATION

common library uses typescript compiler to be built

MONOREPO CONFIGURATION

we use yarn workspaces. you cant use NPM on this project unless you reconfigure lerna and update the package.json to do so
all node packages go in /packages directory

JEST CONFIGURATION

we use jest for testing
see jest.config.js
we need to use ts-jest so that type script plays nicely / gets compiled in our testing environment
we configure our tsconfig.build to ignore our test files when we build all of our lambdas to reduce package size and allows us to keep our testing files next to our development files which I like to do to quickly see project coverage.
run yarn run test or yarn run test:watch in root project

RUNNING CDK COMMANDS

to run any cdk commands, you need to first run cd packages/cdk-app and run the commands as per usual from there
before deploying or synthesizing your final cdk project, you need to build all of your lambdas and other packages. As a convenience method to do this, all packages have a build command in their package.json. You can run lerna run build once from the command line to build all these packages, then run cdk synth or cdk deploy as per usual

GETTING STARTED

clone repo
run yarn install in project root to install all node dependencies for both root and nested project
run lerna run build to build all typescript code
run cd packages/cdk-app
run cdk deploy to deploy or cdk bootstrap or whatever cdk command you like.

Development cycle

run yarn run start to start a local lambda server see utils folder for how to add / remove lambdas from the server read https://steveholgado.com/aws-lambda-local-development/ for more information

Adding a lambda to cdk

create your new lambda in packages directory
run lerna add {new lambda package name} --scope @simonverhoeven/cdk-app this will add the new lambda to your cdk project. This isnt required but it make referencing the lambda folder directory easier in the following step
add your lambda to your cdk stack as per usual, the important part to change is where to reference the lambda code:

new lambda.Function(this, 'lambda-a', {
	functionName: 'lambda-a',
	memorySize: 256,
	runtime: lambda.Runtime.NODEJS_12_X,
	handler: 'index.handler',
	code: lambda.Code.fromAsset(
		path.join(
			require.resolve('@simonverhoeven/lambda-a'),
			'..'
		)
	),

})

FIRST DEPLOY

yarn install
lerna run build
cd packages/cdk-app
cdk bootstrap
cdk deploy

Useful commands

lerna run build --scope @simonverhoeven/lambda-a can run this anywhere inside of project to build only one lambda, useful if only building and deploying an update to one lambda so that you dont have to build all other lambdas before dpeloy as project grows

lerna add @simonverhoeven/common-lambda-lib --scope @simonverhoeven/lambda-a - if you need to ever add one of your local packages (common-lambda-lib) to another local package (lambda-a), this will do the trick and update lambda-a's package.json to add the dependency

Gotcha's

its important to always reference the /dist/ directory when importing files from common libraries...
if you make an edit to your common lambda library, you will have to rebuild all the packages that use this dependency... best to run lerna run build in this use case
sometimes the typescript compiler caches builds which can lead to unexpected results, especially if you change your tsconfig. To remedy this, run lerna run clean:light to delete the cache file and then lerna run build to rebuild
when adding devDependencies to the project, in most cases you will want to add them to the root project instead of the newsted packages... read up on lerna about this, specifically dev dependencies that have command line binaries

ziggy6792/cdk-monorepo-example-frontend