# BundlingOptions

Bundling options.

Extends: BundlingOptions
Extends: DockerRunOptions

- Source: [`aws-lambda-nodejs/lib/types.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-lambda-nodejs/lib/types.ts#L6)
- Type last changed: v2.275.0 · 26 Oct 2026

## Example

```ts
new nodejs.NodejsFunction(this, 'my-handler', {
  bundling: {
    dockerImage: DockerImage.fromBuild('/path/to/Dockerfile'),
  },
});
```

## Properties

- `assetHash`: string — Specify a custom hash for this asset.

  **Default:** asset hash is calculated based on the bundled output

  For consistency, this custom hash will
  be SHA256 hashed and encoded as hex. The resulting hash will be the asset
  hash.

  NOTE: the hash is used in order to identify a specific revision of the asset, and
  used for optimizing and caching deployment activities related to this asset such as
  packaging, uploading to Amazon S3, etc. If you chose to customize the hash, you will
  need to make sure it is updated every time the asset changes, or otherwise it is
  possible that some deployments will not be invalidated.

- `banner`: string — Use this to insert an arbitrary string at the beginning of generated JavaScript files.

  **Default:** no comments are passed

  This is similar to footer which inserts at the end instead of the beginning.

  This is commonly used to insert comments:

- `buildArgs`: { [key: string]: string } — Build arguments to pass when building the bundling image.

  **Default:** no build arguments are passed

- `bundleAwsSDK`: boolean — Includes AWS SDK in the bundle asset.

  **Default:** false if `true` the `aws-sdk` will be included in the asset bundle and not be resolved to the Lambda provided sdk.

- `bundlingFileAccess`: [BundlingFileAccess](/cdk/api/v2/docs/aws-cdk-lib.BundlingFileAccess.html) = BundlingFileAccess.BIND_MOUNT — Which option to use to copy the source files to the docker container and output files back.

- `charset`: [Charset](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.Charset.html) = Charset.ASCII — The charset to use for esbuild's output.

  By default esbuild's output is ASCII-only. Any non-ASCII characters are escaped
  using backslash escape sequences. Using escape sequences makes the generated output
  slightly bigger, and also makes it harder to read. If you would like for esbuild to print
  the original characters without using escape sequences, use `Charset.UTF8`.

- `command`: string[] — The command to run in the container.

  **Default:** run the command defined in the image

- `commandHooks`: [ICommandHooks](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.ICommandHooks.html) — Command hooks.

  **Default:** do not run additional commands

- `define`: { [key: string]: string } — Replace global identifiers with constant expressions.

  **Default:** no replacements are made

  For example, `{ 'process.env.DEBUG': 'true' }`.

  Another example, `{ 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }`.

- `dockerImage`: [DockerImage](/cdk/api/v2/docs/aws-cdk-lib.DockerImage.html) — A custom bundling Docker image.

  **Default:** use the Docker image provided by aws-cdk-lib/aws-lambda-nodejs

  This image should have esbuild installed globally. If you plan to use `nodeModules`
  it should also have `npm`, `yarn`, `bun` or `pnpm` depending on the lock file you're using.

  See https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-lambda-nodejs/lib/Dockerfile
  for the default image provided by aws-cdk-lib/aws-lambda-nodejs.

- `entrypoint`: string[] — The entrypoint to run in the container.

  **Default:** run the entrypoint defined in the image

- `environment`: { [key: string]: string } — The environment variables to pass to the container.

  **Default:** no environment variables.

- `esbuildArgs`: { [key: string]: string | boolean | string[] } — Build arguments to pass into esbuild.

  **Default:** no additional esbuild arguments are passed

  Use an array of strings for options that esbuild supports repeating, for example
  `{ "--alias": ["first=./first", "second=./second"] }`. Each array item
  uses `--flag:value` syntax. An empty array omits the option. Single-value
  options must use a string or boolean instead.

  For example, to add the [--log-limit](https://esbuild.github.io/api/#log-limit) flag:

  ```text
  new NodejsFunction(scope, id, {
    ...
    bundling: {
      esbuildArgs: {
        "--log-limit": "0",
      }
    }
  });
  ```

- `esbuildVersion`: string — The version of esbuild to use when running in a Docker container.

  **Default:** latest v0

- `externalModules`: string[] — A list of modules that should be considered as externals (already available in the runtime).

  **Default:** no replacements are made

- `footer`: string — Use this to insert an arbitrary string at the end of generated JavaScript files.

  **Default:** no comments are passed

  This is similar to banner which inserts at the beginning instead of the end.

  This is commonly used to insert comments

- `forceDockerBundling`: boolean = false — Force bundling in a Docker container even if local bundling is possible.

  This is useful if your function relies on node modules
  that should be installed (`nodeModules`) in a Lambda compatible
  environment.

- `format`: [OutputFormat](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.OutputFormat.html) = OutputFormat.CJS — Output format for the generated JavaScript files.

- `inject`: string[] — This option allows you to automatically replace a global variable with an import from another file.

  **Default:** no code is injected

- `keepNames`: boolean = false — Whether to preserve the original `name` values even in minified code.

  In JavaScript the `name` property on functions and classes defaults to a
  nearby identifier in the source code.

  However, minification renames symbols to reduce code size and bundling
  sometimes need to rename symbols to avoid collisions. That changes value of
  the `name` property for many of these cases. This is usually fine because
  the `name` property is normally only used for debugging. However, some
  frameworks rely on the `name` property for registration and binding purposes.
  If this is the case, you can enable this option to preserve the original
  `name` values even in minified code.

- `loader`: { [key: string]: string } — Use loaders to change how a given input file is interpreted.

  **Default:** use esbuild default loaders

  Configuring a loader for a given file type lets you load that file type with
  an `import` statement or a `require` call.

  For example, `{ '.png': 'dataurl' }`.

- `logLevel`: [LogLevel](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.LogLevel.html) = LogLevel.WARNING — Log level for esbuild.

  This is also propagated to the package manager and
  applies to its specific install command.

- `mainFields`: string[] = [] — How to determine the entry point for modules.

  Try ['module', 'main'] to default to ES module versions.

- `metafile`: boolean = false — This option tells esbuild to write out a JSON file relative to output directory with metadata about the build.

  The metadata in this JSON file follows this schema (specified using TypeScript syntax):

  ```text
  {
    outputs: {
      [path: string]: {
        bytes: number
        inputs: {
          [path: string]: { bytesInOutput: number }
        }
        imports: { path: string }[]
        exports: string[]
      }
    }
  }
  ```
  This data can then be analyzed by other tools. For example,
  bundle buddy can consume esbuild's metadata format and generates a treemap visualization
  of the modules in your bundle and how much space each one takes up.

- `minify`: boolean = false — Whether to minify files when bundling.

- `network`: string — Docker [Networking options](https://docs.docker.com/engine/reference/commandline/run/#connect-a-container-to-a-network---network).

  **Default:** no networking options

- `nodeModules`: string[] — A list of modules that should be installed instead of bundled.

  **Default:** all modules are bundled

  Modules are
  installed in a Lambda compatible environment only when bundling runs in
  Docker.

- `platform`: string — Set platform if server is multi-platform capable. _Requires Docker Engine API v1.38+_.

  **Default:** no platform specified

  Example value: `linux/amd64`

- `preCompilation`: boolean = false — Run compilation using tsc before running file through bundling step.

  This usually is not required unless you are using new experimental features that
  are only supported by typescript's `tsc` compiler.
  One example of such feature is `emitDecoratorMetadata`.

- `securityOpt`: string — [Security configuration](https://docs.docker.com/engine/reference/run/#security-configuration) when running the docker container.

  **Default:** no security options

- `sourceMap`: boolean = false — Whether to include source maps when bundling.

- `sourceMapMode`: [SourceMapMode](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.SourceMapMode.html) = SourceMapMode.DEFAULT — Source map mode to be used when bundling.

- `sourcesContent`: boolean = true — Whether to include original source code in source maps when bundling.

- `target`: string — Target environment for the generated JavaScript code.

  **Default:** the node version of the runtime

- `tsconfig`: string — Normally the esbuild automatically discovers `tsconfig.json` files and reads their contents during a build.

  **Default:** automatically discovered by `esbuild`

  However, you can also configure a custom `tsconfig.json` file to use instead.

  This is similar to entry path, you need to provide path to your custom `tsconfig.json`.

  This can be useful if you need to do multiple builds of the same code with different settings.

  For example, `{ 'tsconfig': 'path/custom.tsconfig.json' }`.

- `user`: string — The user to use when running the container.

  **Default:** root or image default

- `volumes`: [DockerVolume](/cdk/api/v2/docs/aws-cdk-lib.DockerVolume.html)[] — Docker volumes to mount.

  **Default:** no volumes are mounted

- `volumesFrom`: string[] — Where to mount the specified volumes from.

  **Default:** no containers are specified to mount volumes from

- `workingDirectory`: string — Working directory inside the container.

  **Default:** image default