aws-cdk-lib.aws_lambda_nodejs.BundlingOptions

interface BundlingOptions

LanguageType name
.NETAmazon.CDK.AWS.Lambda.Nodejs.BundlingOptions
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awslambdanodejs#BundlingOptions
Javasoftware.amazon.awscdk.services.lambda.nodejs.BundlingOptions
Pythonaws_cdk.aws_lambda_nodejs.BundlingOptions
TypeScript (source)aws-cdk-lib » aws_lambda_nodejs » BundlingOptions

Bundling options.

Example

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

Properties

NameTypeDescription
assetHash?stringSpecify a custom hash for this asset.
banner?stringUse this to insert an arbitrary string at the beginning of generated JavaScript files.
buildArgs?{ [string]: string }Build arguments to pass when building the bundling image.
bundlingFileAccess?BundlingFileAccessWhich option to use to copy the source files to the docker container and output files back.
charset?CharsetThe charset to use for esbuild's output.
command?string[]The command to run in the container.
commandHooks?ICommandHooksCommand hooks.
define?{ [string]: string }Replace global identifiers with constant expressions.
dockerImage?DockerImageA custom bundling Docker image.
entrypoint?string[]The entrypoint to run in the container.
environment?{ [string]: string }The environment variables to pass to the container.
esbuildArgs?{ [string]: string | boolean }Build arguments to pass into esbuild.
esbuildVersion?stringThe version of esbuild to use when running in a Docker container.
externalModules?string[]A list of modules that should be considered as externals (already available in the runtime).
footer?stringUse this to insert an arbitrary string at the end of generated JavaScript files.
forceDockerBundling?booleanForce bundling in a Docker container even if local bundling is possible.
format?OutputFormatOutput format for the generated JavaScript files.
inject?string[]This option allows you to automatically replace a global variable with an import from another file.
keepNames?booleanWhether to preserve the original name values even in minified code.
loader?{ [string]: string }Use loaders to change how a given input file is interpreted.
logLevel?LogLevelLog level for esbuild.
mainFields?string[]How to determine the entry point for modules.
metafile?booleanThis option tells esbuild to write out a JSON file relative to output directory with metadata about the build.
minify?booleanWhether to minify files when bundling.
network?stringDocker Networking options.
nodeModules?string[]A list of modules that should be installed instead of bundled.
preCompilation?booleanRun compilation using tsc before running file through bundling step.
securityOpt?stringSecurity configuration when running the docker container.
sourceMap?booleanWhether to include source maps when bundling.
sourceMapMode?SourceMapModeSource map mode to be used when bundling.
sourcesContent?booleanWhether to include original source code in source maps when bundling.
target?stringTarget environment for the generated JavaScript code.
tsconfig?stringNormally the esbuild automatically discovers tsconfig.json files and reads their contents during a build.
user?stringThe user to use when running the container.
volumes?DockerVolume[]Docker volumes to mount.
volumesFrom?string[]Where to mount the specified volumes from.
workingDirectory?stringWorking directory inside the container.

assetHash?

Type: string (optional, default: asset hash is calculated based on the bundled output)

Specify a custom hash for this asset.

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?

Type: string (optional, default: no comments are passed)

Use this to insert an arbitrary string at the beginning of generated JavaScript files.

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

This is commonly used to insert comments:


buildArgs?

Type: { [string]: string } (optional, default: no build arguments are passed)

Build arguments to pass when building the bundling image.


bundlingFileAccess?

Type: BundlingFileAccess (optional, default: BundlingFileAccess.BIND_MOUNT)

Which option to use to copy the source files to the docker container and output files back.


charset?

Type: Charset (optional, default: 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.

See also: https://esbuild.github.io/api/#charset


command?

Type: string[] (optional, default: run the command defined in the image)

The command to run in the container.


commandHooks?

Type: ICommandHooks (optional, default: do not run additional commands)

Command hooks.


define?

Type: { [string]: string } (optional, default: no replacements are made)

Replace global identifiers with constant expressions.

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

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


dockerImage?

Type: DockerImage (optional, default: use the Docker image provided by)

A custom bundling Docker image.

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

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


entrypoint?

Type: string[] (optional, default: run the entrypoint defined in the image)

The entrypoint to run in the container.


environment?

Type: { [string]: string } (optional, default: no environment variables.)

The environment variables to pass to the container.


esbuildArgs?

Type: { [string]: string | boolean } (optional, default: no additional esbuild arguments are passed)

Build arguments to pass into esbuild.

For example, to add the --log-limit flag:

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

esbuildVersion?

Type: string (optional, default: latest v0)

The version of esbuild to use when running in a Docker container.


externalModules?

Type: string[] (optional, default: ['aws-sdk'] if the runtime is < Node.js 18.x, ['@aws-sdk/'] otherwise.)*

A list of modules that should be considered as externals (already available in the runtime).


footer?

Type: string (optional, default: no comments are passed)

Use this to insert an arbitrary string at the end of generated JavaScript files.

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

This is commonly used to insert comments


forceDockerBundling?

Type: boolean (optional, default: 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?

Type: OutputFormat (optional, default: OutputFormat.CJS)

Output format for the generated JavaScript files.


inject?

Type: string[] (optional, default: no code is injected)

This option allows you to automatically replace a global variable with an import from another file.

See also: https://esbuild.github.io/api/#inject


keepNames?

Type: boolean (optional, default: 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?

Type: { [string]: string } (optional, default: use esbuild default loaders)

Use loaders to change how a given input file is interpreted.

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' }.

See also: https://esbuild.github.io/api/#loader


logLevel?

Type: LogLevel (optional, default: LogLevel.WARNING)

Log level for esbuild.

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


mainFields?

Type: string[] (optional, default: [])

How to determine the entry point for modules.

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


metafile?

Type: boolean (optional, default: 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):

{
  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.

See also: https://esbuild.github.io/api/#metafile


minify?

Type: boolean (optional, default: false)

Whether to minify files when bundling.


network?

Type: string (optional, default: no networking options)

Docker Networking options.


nodeModules?

Type: string[] (optional, default: all modules are bundled)

A list of modules that should be installed instead of bundled.

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


preCompilation?

Type: boolean (optional, default: 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?

Type: string (optional, default: no security options)

Security configuration when running the docker container.


sourceMap?

Type: boolean (optional, default: false)

Whether to include source maps when bundling.


sourceMapMode?

Type: SourceMapMode (optional, default: SourceMapMode.DEFAULT)

Source map mode to be used when bundling.

See also: https://esbuild.github.io/api/#sourcemap


sourcesContent?

Type: boolean (optional, default: true)

Whether to include original source code in source maps when bundling.

See also: https://esbuild.github.io/api/#sources-content


target?

Type: string (optional, default: the node version of the runtime)

Target environment for the generated JavaScript code.

See also: https://esbuild.github.io/api/#target


tsconfig?

Type: string (optional, default: automatically discovered by esbuild)

Normally the esbuild automatically discovers tsconfig.json files and reads their contents during a build.

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?

Type: string (optional, default: root or image default)

The user to use when running the container.


volumes?

Type: DockerVolume[] (optional, default: no volumes are mounted)

Docker volumes to mount.


volumesFrom?

Type: string[] (optional, default: no containers are specified to mount volumes from)

Where to mount the specified volumes from.

See also: https://docs.docker.com/engine/reference/commandline/run/#mount-volumes-from-container---volumes-from


workingDirectory?

Type: string (optional, default: image default)

Working directory inside the container.