Reduce AWS SDK v3 Bundle Size and Cold Starts in Lambda

Photo by Mohammad Rahmani on Unsplash

Most advice on the aws sdk v3 lambda bundle size is a list of settings with no numbers. This guide is for Node.js and TypeScript developers deploying Lambda functions who want to know which settings actually matter. You’ll get the handler and the esbuild script we used, the sizes we measured for each variant, a runtime error you’ll hit with ESM output and its fix, and a CloudWatch Logs Insights query to track cold starts in your own account.

All numbers below were measured on 28 September 2026 with @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb 3.1141.0, esbuild 0.28.2 and Node.js 24.15.0. Every bundle was run end to end against a local fake DynamoDB endpoint to confirm it works. They weren’t measured inside Lambda, so treat the load-time figures as a relative guide.

Should you use the SDK in the Lambda runtime or bundle your own?

Every supported Lambda Node.js runtime (nodejs22.x, nodejs24.x and nodejs26.x as of September 2026) includes a specific minor version of AWS SDK for JavaScript v3, which depends on the runtime version and Region. You can mark @aws-sdk/* as external and ship almost nothing:

The Lambda Node.js handler docs strongly recommend including the SDK clients you need in the deployment package, for compatibility with future runtime updates, and relying on the runtime copy only when you can’t add packages. We follow that here. If you still ship aws-sdk v2, start with migrating a Node.js app from AWS SDK v2 to v3; no supported Node.js runtime includes v2.

Prerequisites

• Node.js 18 or later locally, and a function on nodejs22.x or later with the handler set to index.handler.
• esbuild, typescript and @types/node as dev dependencies, and the SDK clients your handler imports as dependencies.
• Handlers already written against SDK v3 commands. For v2 files, the free AWS SDK JavaScript v2 to v3 converter produces a first draft to review.

How to cut your AWS SDK v3 Lambda bundle size, step by step

1. Import clients, not the whole SDKInstall one @aws-sdk/client-* package per service and import the client class and the commands you send.
2. Bundle with esbuildSet bundle: true, platform: "node", a target that matches your runtime and format: "esm".
3. Prefer the ES module buildsSet mainFields: ["module", "main"]. For platform: "node" esbuild’s default is main,module, which picks the CommonJS builds that tree-shake poorly.
4. Minifyminify: true shrinks identifiers and whitespace.
5. Add a require shim to ESM outputA one-line banner that defines require with createRequire, explained below.
6. Check what went inWrite the metafile and print analyzeMetafile to see the largest inputs.
7. Measure Init DurationCompare the REPORT lines before and after you deploy.

Example: the handler and the esbuild build script

The test handler reads one item with the DynamoDB document client, the same pattern as in querying DynamoDB with AWS SDK v3:

// src/handler.ts: reads one order from DynamoDB by id.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

// Created once per execution environment, during Init, and reused by every invocation.
const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = process.env.TABLE_NAME ?? "orders";

interface OrderEvent {
  orderId: string;
}

export const handler = async (event: OrderEvent): Promise<{ statusCode: number; body: string }> => {
  const { Item } = await ddb.send(new GetCommand({ TableName: TABLE, Key: { pk: event.orderId } }));
  return Item
    ? { statusCode: 200, body: JSON.stringify(Item) }
    : { statusCode: 404, body: JSON.stringify({ message: "not found" }) };
};

// build.mjs: bundle a Lambda handler with esbuild and report what went into it.
// Usage: node build.mjs [--external-sdk]
import { build, analyzeMetafile } from "esbuild";
import { writeFileSync } from "node:fs";

const externalSdk = process.argv.includes("--external-sdk");

const result = await build({
  entryPoints: ["src/handler.ts"],
  outfile: "dist/index.mjs",
  bundle: true,
  minify: true,
  sourcemap: "linked",
  platform: "node",
  target: "node22",
  format: "esm",
  // Prefer each package's ES module build, which esbuild can tree-shake.
  mainFields: ["module", "main"],
  // Leave the SDK out and use the copy in the Lambda runtime, if you choose to.
  external: externalSdk ? ["@aws-sdk/*"] : [],
  // Some bundled CommonJS code calls require("node:https"); give ESM output a real require.
  banner: { js: "import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);" },
  metafile: true,
  logLevel: "info",
});

writeFileSync("dist/meta.json", JSON.stringify(result.metafile));
console.log(await analyzeMetafile(result.metafile, { verbose: false }));

npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm install --save-dev esbuild typescript @types/node

# Bundle, then zip only the output (no node_modules)
node build.mjs
cd dist && zip -q ../function.zip index.mjs && cd ..

# Deploy: runtime nodejs22.x or later, handler "index.handler"
aws lambda update-function-code --function-name orders-get --zip-file fileb://function.zip

The esbuild API documentation describes mainFields, external wildcards and the metafile in detail.

What did each setting change? Our measurements

Sizes of the single output file, and of that file zipped with deflate, for the same handler unless noted:

Three results stood out. The mainFields setting mattered most, cutting 37% on its own. With the ES module builds, the command style finally pays: the aggregated classes added 40 to 47 KiB, while with the default mainFields the aggregated and command styles came out within a few dozen bytes of each other. And a v2 single-client import was only about 16% larger than our best v3 DynamoDB bundle, so the big gap is against the whole v2 SDK, not against a careful v2 import.

The metafile shows where the rest goes. In our 321.2 KiB bundle, @smithy/core contributed 108.7 KiB, @aws-sdk/nested-clients (the STS and SSO clients the credential providers use) 53.9 KiB, @aws-sdk/core 48.8 KiB and @aws-sdk/client-dynamodb itself only 26.1 KiB. That shared core is why a second client costs less than the first: adding S3 to the DynamoDB handler added 124.2 KiB, not the 394.4 KiB an S3-only bundle weighs.

Why does an ESM bundle fail with “Dynamic require is not supported”?

Parts of the SDK dependency tree are CommonJS and call require() for Node.js built-ins. esbuild keeps those calls, but an ES module has no require. Without the banner, importing our bundle from an ES module threw during initialization:

Error: Dynamic require of "node:https" is not supported

The banner defines require at the top of the file with Node.js module.createRequire, which fixes it. A quick node -e "import('./dist/index.mjs')" check didn’t show the problem, because node -e provides a global require; only loading it from a real .mjs file did. Invoke every bundle once from an ES module before you ship it. Alternatively, emit format: "cjs" to an index.js file and skip the banner.

How do you measure cold starts in Lambda?

Every invocation writes a REPORT line to the function’s log group, the same one you read to investigate Lambda errors with CloudWatch. On the first request an execution environment serves, it includes Init Duration: the time the runtime took to load the function and run code outside the handler. That’s the number bundle size affects. With the default text log format, this Logs Insights query summarizes it per day:

filter @type = "REPORT"
| parse @message /Init Duration: (?<initMs>[\d.]+) ms/
| stats count(*) as invocations, count(initMs) as coldStarts, avg(initMs) as avgInitMs, pct(initMs, 95) as p95InitMs, max(initMs) as maxInitMs by bin(1d)

Run it for a week before and after the change, from the console or with the helper in running CloudWatch Logs Insights queries with AWS SDK v3. With the JSON log format, the report arrives as a structured platform event rather than a text line, so adjust the filter and field names.

As a local proxy, we timed a cold import() of each variant in a fresh Node.js 24.15.0 process on a Windows 11 laptop, 25 runs each. Medians: 34.8 ms for the module,main bundle, 40.7 ms for the default-mainFields bundle and 52.3 ms for the unbundled handler loading from node_modules (an empty module took 1.9 ms). Lambda’s numbers will differ; the ordering is what to expect, and Init Duration in your own logs is the number to trust.

What else lowers Init Duration?

• Create clients outside the handler. The Lambda docs recommend it: the client is built once during Init and reused by later invocations in the same environment. Creating clients inside the handler repeats that work on every request.
• Don’t disable keep-alive. It’s on by default in all supported Node.js runtimes, which saves a new TCP and TLS connection per SDK call. Set sensible timeouts too, as in AWS SDK v3 retries and timeouts in Lambda.
• Defer rarely used clients. A dynamic import() inside the branch that needs a client delays running its module code until that branch. Without code splitting, esbuild still puts that code in the same file, so check the metafile.
• Revisit memory. Lambda allocates CPU in proportion to memory, which can change Init time too. Finding Lambda functions with too much memory shows the other side of that trade-off, and finding functions not yet on arm64 covers the architecture switch; a pure JavaScript bundle like this one runs unchanged on both.

Common mistakes and how to fix them

• Bundling but still zipping node_modules. The bundle already contains the SDK. Zip only dist/index.mjs.
• Marking @aws-sdk/* external without meaning to. Some build tools do this by default for newer runtimes; check your config. Your code then runs against the runtime’s SDK version, not the one you tested.
• Handler not found after switching to ESM. The file must be index.mjs, or index.js with "type": "module" in a package.json shipped alongside it.
• A target newer than the runtime. Keep esbuild’s target at or below the runtime’s Node.js version. Upgrade old functions first; find Lambda functions on deprecated runtimes lists them.
• Unit tests that import the bundle. Test the source instead and mock AWS SDK v3 clients in Jest or Vitest; mocks patch the SDK in node_modules, not the copy inside a bundle.

Limits of bundle size tuning

• Our numbers are for one small handler and one SDK version. Your bundle will differ; measure it with the metafile.
• A smaller bundle shortens loading, not your own initialization work such as fetching secrets or opening database connections.
• Cold starts only affect requests that land on a new execution environment. For latency-critical paths, provisioned concurrency removes them at a price. The script to find unused Lambda provisioned concurrency shows when that price stops paying off.
• Bundling doesn’t reduce IAM or runtime risks. Old function versions still count toward your code storage, so delete old and unused Lambda function versions after you redeploy.

To check how your functions are configured today without writing a script, ChatWithCloud answers questions such as “Which Lambda functions run nodejs22.x and how much memory do they have?” from your terminal; how ChatWithCloud runs read-only AWS SDK queries explains what it sends and where the code runs.

Frequently asked questions

Related guides

• Migrate a Node.js app from SDK v2 to v3The first step before any bundling.
• AWS SDK v3 retries and timeoutsSettings that belong next to keep-alive in Lambda.
• Find Lambda functions with too much memoryBalance memory, CPU and cost.
• Run Logs Insights queries with SDK v3Track Init Duration from code.
• Find Lambda functions not on arm64A cheaper architecture for the same bundle.
• Mock AWS SDK v3 in unit testsTest handlers before you bundle them.