Right, let’s talk about assets. You’ve written a beautiful Lambda function, it uses a few external libraries, and you’re ready to deploy it with your shiny CDK stack. You run cdk deploy and… it works. Magic. But what actually just happened? Did CDK teleport your code to AWS? Not quite. It created an asset, and understanding assets is the key to going from a CDK novice to someone who can actually debug this stuff when it, inevitably, goes sideways.

Think of an asset as a piece of local file or directory that CDK needs to physically upload to AWS on your behalf before it can build your infrastructure. For Lambda functions, this is your precious code. For ECS, it might be a Docker image. CDK doesn’t just trust you to upload it later; it needs to package it up and hand it off to AWS at deployment time. The magic, and sometimes the pain, lies in how it does this “packaging.”

The Default Behavior: It’s Fine, Until It’s Not

By default, when you point a Lambda function construct at a directory, the CDK does something deceptively simple. It zips up that directory on your local machine and uploads it. Let’s look at the classic example:

import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';

// This is the common, "hello world" way of doing it.
const myFunction = new lambda.Function(this, 'MyFunction', {
  runtime: lambda.Runtime.NODEJS_18_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda')), // Points to ./lambda
});

When you run cdk deploy, the CDK takes the ./lambda directory, zips it, and uploads it to the AWS CloudFormation-controlled S3 bucket it created for you in your CDK bootstrap stack. It then updates your CloudFormation template to say, “Hey, use the Lambda code from this specific S3 object.”

This is perfectly fine for simple functions with no external dependencies. But what if your function needs axios, or sharp, or any other npm module that isn’t built into the Lambda runtime? You’re a good developer, so you have a package.json in your ./lambda directory. But wait… did you remember to run npm install in that directory before running cdk deploy? If you didn’t, your zip file contains your index.js and a package.json, but no node_modules. Your function will crash faster than a comedian at a funeral.

This is the first pitfall. The CDK isn’t building your code; it’s just blindly zipping a folder. You, the human, are responsible for ensuring that folder contains a ready-to-run artifact.

Enter Bundling: Making the Machine Do the Work

This “zip-it-yourself” approach is tedious and error-prone. This is where CDK’s bundling feature shines. It lets you tell the CDK: “Hey, before you zip this folder, run a command inside it to build it properly.”

The most common use case is for Lambda functions. You can define a Docker command to run, and the CDK will temporarily spin up a Docker container that mirrors the Lambda runtime environment, execute your build command (like npm install), and then zip up the result.

const myBundledFunction = new lambda.Function(this, 'MyBundledFunction', {
  runtime: lambda.Runtime.NODEJS_18_X,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda'), {
    bundling: {
      image: lambda.Runtime.NODEJS_18_X.bundlingImage, // Use the official Lambda-like image
      command: [
        'bash', '-c', `
          npm install &&
          cp -r /asset-input/* /asset-output/ &&
          cp -r /asset-input/. /asset-output/ 2>/dev/null || true
        `,
      ],
    },
  }),
});

Let’s demystify this. The CDK mounts your local ./lambda directory (the “asset-input”) into the container. It also creates an empty directory ("/asset-output"). Your job in the command is to take the input, do whatever build voodoo you need (npm install), and place the final, ready-to-run code into /asset-output. The CDK then takes the contents of /asset-output, zips it, and uploads it.

The beauty here is consistency. It will build the exact same way on your machine, your colleague’s machine, and in a CI/CD pipeline because it’s all happening inside a controlled Docker environment. No more “but it worked on my machine!”

The Dark Side of Bundling: It’s Slow

Here’s the honest truth the cheerful tutorials often skip: Docker-based bundling is slow. Spinning up a container, installing dependencies (especially if you have a lot of them), and then tearing it down adds significant overhead to your cdk synth and cdk deploy commands. It can turn a 10-second deploy into a 90-second one.

You have two main weapons against this:

  1. Use the build option for esbuild (if you’re using Node.js): The CDK team knows Docker is heavy, so they provide a integration with the incredibly fast esbuild tool. You can use it without Docker if you have it installed locally.

    // Install 'esbuild' in your project: npm install esbuild
const myEsbuildFunction = new lambda.NodejsFunction(this, 'MyEsbuildFunction', {
  entry: path.join(__dirname, 'lambda', 'index.ts'), // It even handles TypeScript!
  handler: 'handler',
  bundling: {
    minify: true, // Minify the code
    sourceMap: true, // Generate source maps for debugging
  },
});

    This approach is blazingly fast and handles transpilation, bundling, and minification. It’s almost always the better choice for Node.js functions unless you have a truly exotic build process.

  2. Be Smart with Caching: For Docker bundling, you can use volume mounts to cache things like your node_modules directory between builds. This is a more advanced setup but can drastically reduce rebuild times. You’re essentially telling Docker to use a folder on your host machine to persist the node_modules so it doesn’t have to download them from the internet every single time.

The Nuclear Option: DIY Docker Images

Sometimes, your Lambda function is a monstrous beast with native dependencies, custom binaries, or a build process so complex it makes a Rube Goldberg machine look straightforward. For these, you might want to build a full Docker image and deploy it to ECR. The CDK has you covered here, too.

import * as ecr from 'aws-cdk-lib/aws-ecr';
import * as lambda from 'aws-cdk-lib/aws-lambda';

// First, build your image locally using your Dockerfile
// docker build -t my-lambda-image ./my-docker-lambda

const repo = new ecr.Repository(this, 'EcrRepo');
// This construct will upload your locally built image to ECR for you
const imageCode = lambda.DockerImageCode.fromImageAsset('./my-docker-lambda', {
    repositoryName: repo.repositoryName,
});
new lambda.DockerImageFunction(this, 'MyDockerFunction', {
    code: imageCode,
});

The fromImageAsset method is the hero here. It builds your Dockerfile, pushes the image to ECR, and gives the resulting image URI to your Lambda function construct. It seamlessly bridges the gap between your local development and the AWS ecosystem.

The final word on assets is this: they are the bridge between your local world and the cloud. Start with the simple fromAsset, graduate to NodejsFunction for speed, and break out the Docker bundling or image assets when your needs get complex. Just always be aware of what’s being packaged—because if you don’t, Lambda execution time will be happy to show you what you missed.