DEV Community: Ajeet Chaulagain

Inside a 3-app Turborepo monorepo: parallelism, caching, and CI that stays fast

Ajeet Chaulagain — Wed, 13 May 2026 01:53:40 +0000

Originally published on ajeetchaulagain.com on May 13, 2026.

I've been building ShipWindow for a few months now — deliberately slowly, with a production mindset from day one. No users yet, but real architecture, real CI, infrastructure-as-code.

"Ship fast, refactor later" might be the usual call for a side project like this. But I wanted to try balancing it with a production mindset as I went — still shipping, but thinking a bit further ahead while I did.

The result has been a mix. Some of the production-minded choices have paid off — the CI work I'm about to walk through is one of them. This post is mostly about the part that paid off.

CI is where that mindset showed up early. When the project was in its early phase, I had a minimal workflow validating each PR — lint, type-check, and tests running one after another, sequentially. It was fine for the time. But as the project grew, so did the workflow. As of writing this, the same CI runs across 3 apps and 4 packages in around 2 minutes 30 seconds on most pushes — and it's set up to scale with the project rather than slow down as more code lands.

Three apps, a few shared packages, every push rebuilding everything. You'd expect CI to be slow on a setup like this — that was certainly my starting point. It turned out it doesn't have to be, and the confidence that gives me when merging changes across stacks is honestly the bigger win. I'll walk through how it works, and the decisions that got it there.

The shape of the repo

The high-level structure of the repo looks like this:

shipwindow/
├── apps/
│   ├── web/          # Next.js 16 — authenticated dashboard
│   ├── site/         # Next.js 16 — landing page
│   └── api/          # NestJS — webhook ingestion + auth
├── packages/
│   ├── ui/           # Shared component library (Tailwind v4)
│   ├── shared-types/ # Types shared web ↔ api
│   ├── eslint-config/
│   └── typescript-config/
├── infra/            # AWS CDK stacks
├── turbo.json        # Task graph + cache config
└── package.json      # Yarn workspaces declaration

Three apps live under apps/ — each one is something that gets deployed independently. Four shared packages live under packages/ — these are libraries the apps import from, but nothing ships them on their own. Infrastructure lives in infra/ (stacks written with AWS CDK), kept separate from the application code because it has its own lifecycle and tooling.

Yarn workspaces stitch the whole thing together as one repo — when apps/web imports @shipwindow/ui, it resolves to the local source directly, no publish step in between. Turborepo sits on top of workspaces and orchestrates the task running — knowing what to build in what order, what to cache, and what to skip.

Why a monorepo

When I started thinking about ShipWindow's setup, my first instinct was actually to split into multiple repos. It felt safer — less tooling to figure out, less to think about on day one. I'd worked in a monorepo before and knew the upfront cost: the first few weeks of "what goes where" decisions, the conventions to enforce on a project.

But eventually I was willing to invest that time upfront, knowing it would pay off as the project grew. A few things pushed me in that direction.

Past experience. I'd worked in a monorepo on a previous project and it had served me well. I also remembered the alternative — publish a package, bump the version, install, redeploy, every time anything shared changed. Not something I wanted to live through again on a side project where I wanted to move fast without the overhead of versioning and publishing.

Atomic refactors. Shipping solo, I wanted to move quickly without juggling contracts across repos. When I add a new field to a type in packages/shared-types, both apps/web and apps/api get the change in the same PR. No version bump, no broken contracts in production. One PR, done.

One review, one diff. Every change shows up against the full picture. If a frontend change needs an API endpoint, both land in the same PR — the contract is visible in one diff, not split across two repos with two CI runs.

Shared design tokens stay in sync. packages/ui exports brand colors, components, and CSS tokens. The day I rebrand and edit brand.css, every app updates on the next build. No copy-paste, no drift.

Working in a monorepo, the honest cost is discipline. Without it, everything starts depending on everything, and you stop knowing what's safe to change. I've worked on a monorepo project before, and it's a pattern I've seen play out — especially if you haven't worked in one before and are still getting your head around it. The discipline lives in being deliberate about what belongs in a shared package versus what stays in an app, and honest about what each package is actually responsible for.

Why Turborepo

Once I'd decided on a monorepo, the next question was how to actually run things across it. Yarn workspaces handles the dependency graph — when apps/web imports @shipwindow/ui, it resolves to the local source without any publish step. That part is solved.

But workspaces alone doesn't handle task orchestration — what to build first, what to cache, what to skip. For that, build tools like Lerna, Nx, or Turborepo are generally used. They sit on top of workspaces, not in place of them — you use both.

Turborepo describes itself as "the build system for JavaScript and TypeScript codebases" — and it's maintained by Vercel, which matters here because their free remote cache is one of the reasons I picked it. It's written in Rust, configured through a single turbo.json file, and built around the task graph and caching model that most monorepo tools have converged on.

On a previous project, I worked in a monorepo that used Lerna. I didn't pick it — the project had been set up before I joined — but I lived with it long enough to get a feel for it. Lerna was widely used for JS monorepos at the time.

Turborepo is newer and its ecosystem is still growing, but its focus is squarely on builds and caching — which, for a side project where I don't publish anything externally but care a lot about CI speed, lined up better with what I needed.

Worth flagging: Turborepo's Crafting your repository docs cover structuring a monorepo, managing dependencies, configuring tasks, caching, and more — in real depth. Start there if you're setting up your first one.

The apps and packages

apps/web — authenticated dashboard, Next.js 16 App Router
apps/site — landing page, statically rendered except for one server action
apps/api — NestJS backend, ingests GitHub webhooks, hosts auth endpoints
Each app runs on a different port in dev, deploys to a different platform, and has its own scaling profile.
packages/ui — shared component library built with Tailwind v4, consumed directly from source by both Next.js apps
packages/shared-types — single source of truth for the wire shape between web and api: WebhookEvent, PullRequest, Review, etc.
packages/eslint-config and packages/typescript-config — shared lint and TS configs; apps extend these so the rules stay consistent
None of the packages have a publish step. They're consumed through the workspace graph at build time — which is the whole point of using workspaces in the first place.

How Turborepo orchestrates everything

Turborepo's job is to figure out what work needs doing, in what order, and what can be skipped. It does all of that based on a single config file at the root of your repo: turbo.json.

turbo.json is where you describe the task graph — what tasks exist, what they depend on, what their inputs and outputs are. Here's a trimmed version of mine:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**", "generated/**"],
      "env": ["DATABASE_URL", "NEXT_PUBLIC_BACKEND_URL"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "env": ["CI", "RESEND_API_KEY", "VERCEL_ENV"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

A few things in here are doing most of the work:

dependsOn: ["^build"] — the caret means "build all upstream packages first." So when I run turbo run build in apps/web, Turbo first builds packages/ui and packages/shared-types, then apps/web itself. I never order tasks manually. Turbo walks the workspace graph for me.

The env array — this is the easy one to get wrong. Any environment variable a task reads but doesn't declare here gets silently ignored when Turbo computes the cache key.

This env array was something that troubled me initially. The cache had quietly lied to me more than once before I understood what was happening — CI coming back green when it shouldn't have, stale results being served without anything flagging it.

The fix: list every env var your task actually reads to make a cache reliable and predictable.

Running apps locally

To run every app, it's one command:

yarn dev                # all apps in parallel
yarn dev --filter=web   # just one

The hot reload across packages is what makes the monorepo feel worth it day to day. Change a button in packages/ui, and the apps using it update immediately — no build step, no npm link, no publish. It just works.

Under the hood, Yarn workspaces points each app at the package's actual folder on disk rather than a copy. So edits in packages/ui count the same as edits inside the app — the dev server picks them up like any other file change.

If you've worked in a multi-repo setup before, this is the part that quietly justifies the rest of the complexity.

What this looks like in CI: parallelism and caching

Three apps, four packages, lint and type-check and tests on every push. Initially, my CI ran these sequentially — that's just how I'd set it up. While I was just starting out and in the early phase of adding features, it didn't matter much. The project was small, and sequential was simpler to reason about.

The shift to parallel jobs wasn't really about speed. Sequential CI was still fast enough at three apps and a handful of tests. The real reason was headroom for later: as features and tests grow, sequential adds up. Splitting tasks into parallel jobs also keeps the workflow predictable, and lets Turborepo handle the actual task ordering inside each one. That's cleaner than chaining steps in YAML and hoping the order holds.

In practice, that means lint, type-check, tests, and cdk synth are each their own GitHub Actions job, depending on a shared install step. Once install finishes, all four run in parallel.

The four jobs after install all run side by side, so the pipeline finishes in roughly the time of the longest job, not the sum.

Inside each of those jobs is where Turborepo does its work. In my setup, lint, type-check, and tests all dependsOn: ["^build"] — meaning each of them needs the upstream packages built before it can run. I don't have to think about that. Turborepo walks the task graph, builds whatever's needed (or pulls it from the cache if it's already built), then runs lint, type-check, and tests on top. It figures out the right order so I don't have to script it.

On the caching side, that's where the actual savings come from. Turborepo tracks each task's inputs — source files, env vars, dependencies — and skips work it's seen before with identical inputs. The Vercel Remote Cache makes this work across CI. Setup is two environment variables in your workflow: TURBO_TOKEN (a Vercel access token) and TURBO_TEAM (your team slug). When npx turbo run <task> runs, Turbo reads those env vars from the environment and connects to the remote cache automatically. No other config needed.

Here's what one of the parallel jobs looks like in my workflow — the lint job, for example:

# .github/workflows/pr-validate.yml

# ... yarn install job...

lint:
  name: Lint
  needs: install
  runs-on: ubuntu-latest
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}
  steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: 24

    - run: npx turbo run lint

# ... type-check, test and cdk-synth jobs ...

The structure is the same for each parallel job — needs: install, then run a single Turbo task. The TURBO_TOKEN and TURBO_TEAM env vars are what let Turbo talk to the remote cache; without them, the job would run everything from scratch.

For a typical PR in ShipWindow — say I add a new type GitHubEvent in packages/shared-types and update apps/web to render it — Turborepo realizes apps/site isn't affected. Its build is already cached, its lint result is already cached, its tests haven't changed. So those get pulled from the cache instead of being rerun. Only the work that actually changed runs.

For a solo project, the cache is already paying off — I can see most PRs hitting at least some cached tasks. With more contributors, the win gets bigger: builds run for one person's PR can be reused on someone else's, so the same work doesn't happen twice. Turborepo's job is to skip work that doesn't need redoing and to handle task order. GitHub Actions runs the jobs in parallel. Together, the CI stays relatively quick.

What I'd improve

One thing on the list for later: affected-only builds with --filter. Turborepo supports running tasks only for the workspaces affected by changed files — turbo run build --filter=...^... skips unaffected workspaces entirely instead of having Turbo do a cache lookup on each one.

I'd be happy to explore it as the project grows. For now, caching is doing the heavy lifting and the savings would be marginal — it earns its place once the workspace is big enough that even the lookups start to add up.

What I learned

Most of what I've described here is roughly what I believe most Turborepo projects converge on. The patterns aren't novel — they just take a while to feel obvious.

The bigger thing I'm taking from a few months of this: the engineering decisions that matter on a side project aren't really about being objectively right. They're about giving yourself room to keep going — and to keep improving as you do. Monorepo over multi-repo, Turborepo over rolling my own scripts, caching over hoping CI stays fast — none of these are universal answers. They were the ones that kept me building features instead of fighting tooling.

If you're curious what I'm building, take a look at ShipWindow. Still pre-launch, waitlist's open if you want to be one of the first to try it.

If you found this useful, more posts at ajeetchaulagain.com on side projects and software.

How to Deploy NestJS to AWS Lambda Using CDK and GitHub Actions

Ajeet Chaulagain — Fri, 08 May 2026 01:31:00 +0000

Originally published on ajeetchaulagain.com on March 30, 2026.

Deploying a NestJS application to AWS Lambda behind API Gateway sounds straightforward — until you start wiring things together.

Between adapting NestJS to a serverless runtime, configuring API Gateway, and setting up infrastructure with AWS CDK, there are several moving parts that can quickly become messy. While working on a personal side project, I ran into these challenges firsthand — particularly around adapting NestJS to Lambda's execution model.

By the end of this guide, you'll have:

A NestJS app adapted for Lambda's execution model using @codegenie/serverless-express
Infrastructure defined as code: a Lambda function and HTTP API Gateway, provisioned with AWS CDK
A GitHub Actions workflow that builds and deploys your stack automatically on every push to main

The complete source code is available on GitHub.

Prerequisites

To follow along, you'll need:

An AWS account
Basic familiarity with Node.js and NestJS
Basic familiarity with AWS services and tools (AWS CLI, IAM, Lambda, API Gateway, CloudFormation)
A GitHub account (for setting up a repository and GitHub Actions)

You don't need to be an AWS expert to follow along, but having a rough idea of how Lambda and API Gateway fit together will make things easier.

Set up a new NestJS project

Start by creating a new NestJS application using the Nest CLI:

npm i -g @nestjs/cli
nest new nestjs-serverless-aws-cdk

This scaffolds a standard NestJS project with all the necessary boilerplate.

For a deeper understanding of NestJS concepts and architecture, I highly recommend checking out the NestJS official documentation.

Now, start the application:

cd nestjs-serverless-aws-cdk
npm run start

You should see the application running at http://localhost:3000/. The default port is configured in src/main.ts:

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

The scaffolded project already includes:

A controller (app.controller.ts)
A service (app.service.ts)
A module (app.module.ts)

Since the focus of this guide is deployment, we'll reuse the default endpoint instead of creating new ones.

Adapting NestJS for AWS Lambda

By default, a NestJS application runs on a long-lived HTTP server. It bootstraps once, initializes its dependencies, and continues handling incoming requests.

AWS Lambda, on the other hand, follows an event-driven model where code is executed per request in short-lived, stateless environments (with occasional cold starts).

Because of this difference, NestJS cannot run directly in Lambda without some adaptation. To bridge this gap, we use @codegenie/serverless-express, which allows a NestJS application to run inside AWS Lambda.

Under the hood, it:

Converts the incoming Lambda event into an HTTP request
Passes it to your NestJS application
Transforms the response back into a Lambda-compatible format

In simple terms, it makes Lambda behave like an HTTP server so NestJS can run without major changes.

Now that we understand the need for additional configuration, let's install the required packages:

npm install @codegenie/serverless-express @types/aws-lambda

Note: @types/aws-lambda provides the TypeScript types used in the handler.

Next, create a new file called lambda.ts inside the src/ directory (alongside main.ts). This will act as the entry point for your Lambda function.

// src/lambda.ts
import { NestFactory } from '@nestjs/core';
import { ExpressAdapter } from '@nestjs/platform-express';
import serverlessExpress from '@codegenie/serverless-express';
import {
  APIGatewayProxyEvent,
  APIGatewayProxyResult,
  Context,
} from 'aws-lambda';
import express from 'express';
import { AppModule } from './app.module';

type AsyncHandler = (
  event: APIGatewayProxyEvent,
  context: Context,
) => Promise<APIGatewayProxyResult>;

let serverlessExpressInstance: AsyncHandler | undefined;

async function setup(
  event: APIGatewayProxyEvent,
  context: Context,
): Promise<APIGatewayProxyResult> {
  const expressApp = express();
  const nestApp = await NestFactory.create(
    AppModule,
    new ExpressAdapter(expressApp),
  );

  nestApp.enableCors();
  await nestApp.init();

  serverlessExpressInstance = serverlessExpress({
    app: expressApp,
  }) as unknown as AsyncHandler;

  return serverlessExpressInstance(event, context);
}

export function handler(
  event: APIGatewayProxyEvent,
  context: Context,
): Promise<APIGatewayProxyResult> {
  if (serverlessExpressInstance) {
    return serverlessExpressInstance(event, context);
  }

  return setup(event, context);
}

A few key things worth calling out in the code above:

serverlessExpressInstance is declared outside the handler and only populated on the first invocation. On subsequent invocations within the same Lambda container, the if (serverlessExpressInstance) check skips the full NestJS bootstrap and reuses the existing instance. This is the standard pattern for reducing cold start overhead in Lambda.
The setup function is where NestJS bootstraps. It creates an Express app, wraps it with the NestJS ExpressAdapter, and passes it to serverlessExpress. The resulting instance is a function that accepts Lambda events and returns Lambda-compatible responses.

This handler follows the standard async/await pattern and works with modern AWS Lambda Node.js runtimes (including Node.js 20 and 24).

The AWS Lambda Node.js 24 runtime dropped support for the callback-style handler (callback(null, response)) — using it will cause the function to hang until timeout. See the AWS Lambda Node.js runtime docs for details.

Setting up infrastructure using AWS CDK

Now that we have the Lambda handler ready to serve our NestJS application, let's set up the infrastructure using AWS CDK. AWS Cloud Development Kit (CDK) is an Infrastructure as Code (IaC) framework that allows you to define AWS resources using programming languages such as TypeScript, Python, Java, and more. Think of it like this: instead of writing raw CloudFormation templates, you write code that is synthesized into CloudFormation, which is then used to deploy resources to AWS.

The high-level CDK flow looks something like this:

👨‍💻 Write CDK Code
        ↓
🧪 cdk synth
        ↓
📄 CloudFormation Template
        ↓
🚀 cdk deploy
        ↓
☁️ AWS Resources

In practice, CDK makes infrastructure easier to reason about and maintain compared to raw templates.

CDK mental model (quick overview)

Before we define our infrastructure, it helps to understand a few core CDK concepts:

App → The root container for your CDK application
Stack → A unit of deployment (maps to a CloudFormation stack)
Construct → Building blocks used to define AWS resources

In this guide, we'll define a single stack that provisions our Lambda function, API Gateway, and related resources.

Initializing CDK in the project

Now that you've understood the basics of AWS CDK, let's initialize it in our project. To keep the infrastructure code separate from the NestJS source code, you'll initialize the CDK project into a separate subdirectory, infra/.

Run the following command from the project root:

mkdir infra && cd infra
npx cdk init app --language typescript

This generates the basic CDK project structure:

.
├── bin/
├── lib/
├── cdk.json
├── package.json
└── tsconfig.json

Where:

bin/ contains the entry point of your CDK app
lib/ contains the stack definition for your infrastructure
cdk.json contains configuration for the CDK CLI

Configuring AWS credentials (step by step)

Before running any AWS CDK commands, you need to configure AWS credentials on your local machine.

This allows AWS to authenticate your requests and perform actions on your behalf — such as deploying CloudFormation stacks and uploading assets.

For example, when you run:

npx cdk bootstrap

Your IAM identity needs permissions to create foundational resources like:

CloudFormation stacks
S3 buckets (for storing assets)
IAM roles and policies

In production environments, it's best to follow the principle of least privilege, granting only the permissions required for a specific task.

However, to keep this guide simple and focused, we'll use an IAM user with the AdministratorAccess policy attached.

Follow these steps to configure AWS credentials:

1. Install AWS CLI

Make sure AWS CLI is installed on your machine. Follow the official installation guide.

2. Create an IAM user

Create an IAM user with the AdministratorAccess policy and generate an access key for it.

Log in to your AWS console
Navigate to IAM → Users → Create User
Create a user (e.g., cdk-bootstrap-admin)
- Attach the AdministratorAccess policy
- Generate an access key

Make sure to download the secret key for use later — you won't be able to view it again.

3. Run AWS Configure

Run aws configure to set up credentials for the AWS CLI so it can authenticate your requests:

aws configure

You'll be prompted to enter:

AWS Access Key ID:
AWS Secret Access Key:
Default region name: us-east-1
Default output format: json

Paste the access keys you generated in the previous step.

4. Verify credentials configuration

To confirm AWS credentials are configured correctly, run the following AWS CLI command, which will show the details of your AWS account and IAM user:

aws sts get-caller-identity

Output:

{
  "UserId": "UserId",
  "Account": "AccountNumber",
  "Arn": "arn:aws:iam::<AccountNumber>:user/cdk-bootstrap-admin"
}

Bootstrapping the CDK project

Now that your AWS credentials are configured locally, you're ready to bootstrap your AWS environment for CDK.

Bootstrapping prepares your AWS account so that AWS CDK can deploy resources on your behalf.

Run the following command in your infra/ directory:

npx cdk bootstrap

This command creates a foundational one-time CloudFormation stack (called CDKToolkit) in your AWS account, which sets up required resources such as IAM roles and an S3 bucket to upload CloudFormation templates. These resources are needed for future CDK deployments.

You only need to run cdk bootstrap once per account and region.

Writing the CDK stack

Now that you've bootstrapped your environment, you're ready to define your infrastructure using AWS CDK. In this section, you'll create a stack that provisions a Lambda function for your application.

I'm also using a Lambda layer to bundle production dependencies. Separating node_modules from the application code helps reduce the size of the deployment package and allows the same layer to be reused across multiple Lambda functions.

Navigate to the infra/lib directory, where you'll find a file named infra-stack.ts. This file was generated during CDK project initialization. You can rename the stack if needed, but for this guide, we'll keep it as is.

Add the following stack definition code to infra/lib/infra-stack.ts:

// infra/lib/infra-stack.ts
import * as cdk from 'aws-cdk-lib/core';
import { Construct } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
import * as integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import * as path from 'path';

export class InfraStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const nodeModulesLayer = new lambda.LayerVersion(this, 'NodeModulesLayer', {
      code: lambda.Code.fromAsset(path.join(__dirname, '../../layer')),
      compatibleRuntimes: [lambda.Runtime.NODEJS_24_X],
      description: 'Production node_modules for NestJS Lambda',
    });

    const nestApiLambda = new lambda.Function(this, 'NestApiLambdaFunction', {
      runtime: lambda.Runtime.NODEJS_24_X,
      handler: 'src/lambda.handler',
      code: lambda.Code.fromAsset(path.join(__dirname, '../../dist'), {
        exclude: ['infra', 'tsconfig*'],
      }),
      memorySize: 512,
      layers: [nodeModulesLayer],
    });

    const httpApi = new apigwv2.HttpApi(this, 'HttpApi', {
      defaultIntegration: new integrations.HttpLambdaIntegration(
        'LambdaIntegration',
        nestApiLambda,
      ),
    });

    new cdk.CfnOutput(this, 'HttpApiUrl', {
      value: httpApi.url!,
    });
  }
}

In this setup, you're using a few core CDK constructs to define your infrastructure:

lambda.Function
lambda.LayerVersion
apigwv2.HttpApi

In CDK, constructs are the basic building blocks used to model infrastructure. If you haven't come across constructs before, the official docs are worth a quick read: AWS CDK Constructs.

Now let's go through the different configuration parts in the code above.

Lambda layer configuration

const nodeModulesLayer = new lambda.LayerVersion(this, 'NodeModulesLayer', {
  code: lambda.Code.fromAsset(path.join(__dirname, '../../layer')),
  compatibleRuntimes: [lambda.Runtime.NODEJS_24_X],
  description: 'Production node_modules for NestJS Lambda',
});

This code defines a Lambda layer using the LayerVersion construct, where the code is loaded from a layer/ directory, which doesn't exist yet.

To create it, add the following script to your root package.json:

"build:lambda-layer": "mkdir -p layer/nodejs && cp package.json package-lock.json layer/nodejs/ && npm ci --prefix layer/nodejs --omit=dev && rm layer/nodejs/package.json layer/nodejs/package-lock.json"

Since we don't need dev dependencies for our Lambda runtime, this script installs only production dependencies into layer/nodejs/. In short, it copies the existing package.json and lock file into layer/nodejs/ temporarily and installs production dependencies (npm ci --omit=dev) that our application needs.

Now, run that script from the project root to create a /layer directory (we'll need this before deploying):

npm run build:lambda-layer

Also add /layer/nodejs/node_modules to your .gitignore. This directory should be generated during builds, not committed.

Lambda function configuration

const nestApiLambda = new lambda.Function(this, 'NestApiLambdaFunction', {
  runtime: lambda.Runtime.NODEJS_24_X,
  handler: 'src/lambda.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, '../../dist'), {
    exclude: ['infra', 'tsconfig*'],
  }),
  memorySize: 512,
  layers: [nodeModulesLayer],
});

This code defines our Lambda function along with some configuration. Here's a breakdown of the key settings:

runtime: lambda.Runtime.NODEJS_24_X — sets Node.js v24 as the runtime used by the Lambda function
handler: 'src/lambda.handler' — the entry point Lambda invokes. We created this handler previously in src/lambda.ts. Since the application is deployed from the dist directory which contains a src folder, the handler is defined as src/lambda.handler.
code: lambda.Code.fromAsset(…) — packages the compiled application (dist/) and uploads it as the deployment bundle
exclude: […] — skips unnecessary files from the bundle. I would strongly recommend being intentional here — smaller bundles lead to faster deployments. For example, I've excluded the infra directory and tsconfig* related files present in our dist directory. The only files needed for the NestJS runtime are in dist/src.
memorySize: 512 — allocates 512 MB of memory to our Lambda runtime. NestJS has a heavier bootstrap compared to minimal handlers, so this tends to give better performance out of the box. Without memorySize, it defaults to 128 MB.
layers — attaches the layer defined above. This layer is merged into the function's filesystem at runtime.

HTTP API Gateway configuration

const httpApi = new apigwv2.HttpApi(this, 'HttpApi', {
  defaultIntegration: new integrations.HttpLambdaIntegration(
    'LambdaIntegration',
    nestApiLambda,
  ),
});

Here you define an HTTP API using API Gateway v2. This guide uses HTTP API (v2), which is cheaper than REST API (v1), has lower latency, and is sufficient for NestJS since routing lives inside the application. See the official comparison if you need the advanced features REST API offers.

This uses HttpLambdaIntegration, which enables Lambda proxy integration. In simple terms, any incoming HTTP requests to API Gateway are forwarded to your Lambda as an event, and the response from Lambda is forwarded back to the client unchanged.

By setting this as the default integration, CDK creates a $default route — a catch-all that matches any HTTP method and any path. This is an important consideration for our NestJS application because we want the routing to happen inside the application itself, not at the API Gateway level.

CloudFormation outputs

new cdk.CfnOutput(this, 'HttpApiUrl', {
  value: httpApi.url!,
});

This prints the generated endpoint URL to the terminal after running cdk deploy. Something like this:

Outputs:
InfraStack.HttpApiUrl = https://abc123.execute-api.us-east-1.amazonaws.com/
Stack ARN:
arn:aws:cloudformation:us-east-1:<account-number>:stack/InfraStack/a0fb4130-2a7f-11f1-ab1d-12c493467933

Deploying the infrastructure

At this point, your infrastructure is defined. Now it's time to deploy it.

Deploying locally

Before running the cdk deploy command, let's first validate the CloudFormation stack by running cdk synth from the infra/ directory:

cd infra && npx cdk synth

This compiles your CDK code and generates the CloudFormation template in the infra/cdk.out/ directory. It's a quick way to catch configuration issues before running a full deployment.

Once synthesis succeeds, make sure your tsconfig.build.json excludes the infra/ directory and explicitly sets rootDir:

// tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "rootDir": "./"
  },
  "exclude": ["node_modules", "test", "dist", "infra", "**/*spec.ts"]
}

Two things are happening here:

Excluding infra/ — without this, nest build will try to compile your CDK code as part of the application. Since CDK dependencies like aws-cdk-lib are installed inside infra/node_modules (not at the project root), the build will fail with module resolution errors.
Setting rootDir — controls the output folder structure. Without it set explicitly, TypeScript figures it out from whichever files are included. Once infra/ is excluded, TypeScript only sees src/ and uses that as the root — so lambda.ts compiles to dist/lambda.js instead of dist/src/lambda.js, which no longer matches the handler path you defined in the stack.

Now build your application (dist/) and Lambda layer (layer/) from the project root:

npm run build
npm run build:lambda-layer

This ensures your compiled application and production dependencies are ready for deployment.

Now run the deploy command from the infra/ directory:

npx cdk deploy

This starts the CDK deployment process. You'll see a summary of IAM and resource changes before it proceeds.

Confirm the deployment when prompted. After a successful deploy, you'll see the API URL in the terminal output.

Hit this URL and you should see the "Hello World!" response from your app.controller.ts endpoint — your NestJS app is live on AWS Lambda!

Deploying with GitHub Actions

So far, you've been deploying locally using cdk deploy. That works well for development, but in a production-grade setup, you'll want deployments to run through CI.

A common approach is to trigger deployments automatically when changes are pushed to the main branch. In this section, we'll keep things simple and use GitHub Actions to automate deployments on every push to main. I won't walk through the workflow line by line — the goal here is to get a working setup in place.

If you're new to GitHub Actions, the official docs are a good place to start.

Add the following file .github/workflows/deploy.yml:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4.2.2

      - name: Set up Node.js
        uses: actions/setup-node@v4.4.0
        with:
          node-version: 24
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Build Lambda layer
        run: npm run build:lambda-layer

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4.1.0
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ vars.AWS_REGION }}

      - name: Install CDK dependencies
        run: npm ci
        working-directory: infra

      - name: Deploy CDK Stack
        run: npx cdk deploy --require-approval never
        working-directory: infra

At a high level, this workflow:

Installs dependencies
Builds the application (dist/) and Lambda layer (/layer)
Configures AWS credentials for CI
Deploys the CDK stack

AWS credentials for CI

If you look at the workflow code, you'll see it uses GitHub secrets and variables to authenticate with AWS:

AWS_ACCESS_KEY_ID — stored as a secret
AWS_SECRET_ACCESS_KEY — stored as a secret
AWS_REGION — stored as a variable

Make sure you add these in your repository settings. You can follow the official guides:

Note: GitHub masks secret values in logs, so outputs like your API URL (which includes the region) will also be masked and won't be directly clickable. Using vars for AWS_REGION keeps the output readable and ensures the endpoint URL is visible and usable, while sensitive values remain stored in secrets.

Once everything is in place, push your changes (including the workflow file) to the main branch. This will trigger the deployment automatically.

You can monitor the workflow from the Actions tab in your repository.

After the workflow completes, open the workflow run and check the Deploy CDK Stack step — the HttpApiUrl will be printed there without the region being masked.

Conclusion

That's the full setup. If you've made it this far, you have a production-ready baseline for running NestJS on AWS Lambda!

You adapted NestJS to fit Lambda's execution model, defined your infrastructure as code using CDK, exposed it through API Gateway, and automated deployments with GitHub Actions. None of these pieces are complex on their own — but together they give you a setup that's consistent, repeatable, and easy to extend.

A few things this setup gets right out of the box:

Infrastructure is version-controlled alongside your application code
Deployments are automated and consistent, and can be extended to support multiple environments
NestJS runs in Lambda without changes to your routing or application logic — the gateway proxies everything through and NestJS handles it internally

From here, you can layer in things like custom domains, environment-specific stacks, API Gateway authentication, or move to container-based Lambda deployments if your workloads grow.

Thanks for following along — enjoy the serverless!

If this saved you time, you can find more posts like this on my blog or follow me on LinkedIn.