BundlingOptions Struct
Bundling options.
Example
new nodejs.NodejsFunction(this, 'my-handler', {
bundling: {
dockerImage: DockerImage.fromBuild('/path/to/Dockerfile'),
},
});
Properties
assetHashoptionalstringasset_hashoptionalstrassetHashoptionalStringAssetHashoptionalstringAssetHashoptional*string#Default: asset hash is calculated based on the bundled output
notes
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.
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:
buildArgsoptional{ [key: string]: string }build_argsoptionaltyping.Mapping[str, str]buildArgsoptionalMap<String, String>BuildArgsoptionalIDictionary<string, string>BuildArgsoptional*map[string]*string#Default: no build arguments are passed
bundleAwsSDKoptionalbooleanbundle_aws_sdkoptionalboolbundleAwsSDKoptionalBooleanBundleAwsSDKoptionalboolBundleAwsSDKoptional*bool#Default: false if true the aws-sdk will be included in the asset bundle and not be resolved to the Lambda provided sdk.
bundlingFileAccessoptionalBundlingFileAccessbundling_file_accessoptionalBundlingFileAccessbundlingFileAccessoptionalBundlingFileAccessBundlingFileAccessoptionalBundlingFileAccessBundlingFileAccessoptionalBundlingFileAccess= BundlingFileAccess.BIND_MOUNT#charsetoptionalCharsetcharsetoptionalCharsetcharsetoptionalCharsetCharsetoptionalCharsetCharsetoptionalCharset= Charset.ASCII#notes
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.
commandoptionalstring[]commandoptionaltyping.List[str]commandoptionalList<String>Commandoptionalstring[]Commandoptional*[]*string#Default: run the command defined in the image
commandHooksoptionalICommandHookscommand_hooksoptionalICommandHookscommandHooksoptionalICommandHooksCommandHooksoptionalICommandHooksCommandHooksoptionalICommandHooks#Default: do not run additional commands
defineoptional{ [key: string]: string }defineoptionaltyping.Mapping[str, str]defineoptionalMap<String, String>DefineoptionalIDictionary<string, string>Defineoptional*map[string]*string#Default: no replacements are made
For example, { 'process.env.DEBUG': 'true' }.
Another example, { 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }.
dockerImageoptionalDockerImagedocker_imageoptionalDockerImagedockerImageoptionalDockerImageDockerImageoptionalDockerImageDockerImageoptionalDockerImage#Default: use the Docker image provided by aws-cdk-lib/aws-lambda-nodejs
notes
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.
entrypointoptionalstring[]entrypointoptionaltyping.List[str]entrypointoptionalList<String>Entrypointoptionalstring[]Entrypointoptional*[]*string#Default: run the entrypoint defined in the image
environmentoptional{ [key: string]: string }environmentoptionaltyping.Mapping[str, str]environmentoptionalMap<String, String>EnvironmentoptionalIDictionary<string, string>Environmentoptional*map[string]*string#Default: no environment variables.
esbuildArgsoptional{ [key: string]: string | boolean }esbuild_argsoptionaltyping.Mapping[str, typing.Union[str, bool]]esbuildArgsoptionalMap<String, String>EsbuildArgsoptionalIDictionary<string, string>EsbuildArgsoptional*map[string]interface{}#Default: no additional esbuild arguments are passed
For example, to add the --log-limit flag:
new NodejsFunction(scope, id, {
...
bundling: {
esbuildArgs: {
"--log-limit": "0",
}
}
});
esbuildVersionoptionalstringesbuild_versionoptionalstresbuildVersionoptionalStringEsbuildVersionoptionalstringEsbuildVersionoptional*string#Default: latest v0
externalModulesoptionalstring[]external_modulesoptionaltyping.List[str]externalModulesoptionalList<String>ExternalModulesoptionalstring[]ExternalModulesoptional*[]*string#Default: no replacements are made
forceDockerBundlingoptionalbooleanforce_docker_bundlingoptionalboolforceDockerBundlingoptionalBooleanForceDockerBundlingoptionalboolForceDockerBundlingoptional*bool= false#This is useful if your function relies on node modules that should be installed (nodeModules) in a Lambda compatible environment.
formatoptionalOutputFormatformatoptionalOutputFormatformatoptionalOutputFormatFormatoptionalOutputFormatFormatoptionalOutputFormat= OutputFormat.CJS#injectoptionalstring[]injectoptionaltyping.List[str]injectoptionalList<String>Injectoptionalstring[]Injectoptional*[]*string#Default: no code is injected
keepNamesoptionalbooleankeep_namesoptionalboolkeepNamesoptionalBooleanKeepNamesoptionalboolKeepNamesoptional*bool= false#notes
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.
loaderoptional{ [key: string]: string }loaderoptionaltyping.Mapping[str, str]loaderoptionalMap<String, String>LoaderoptionalIDictionary<string, string>Loaderoptional*map[string]*string#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' }.
logLeveloptionalLogLevellog_leveloptionalLogLevellogLeveloptionalLogLevelLogLeveloptionalLogLevelLogLeveloptionalLogLevel= LogLevel.WARNING#This is also propagated to the package manager and applies to its specific install command.
mainFieldsoptionalstring[]main_fieldsoptionaltyping.List[str]mainFieldsoptionalList<String>MainFieldsoptionalstring[]MainFieldsoptional*[]*string= []#Try ['module', 'main'] to default to ES module versions.
metafileoptionalbooleanmetafileoptionalboolmetafileoptionalBooleanMetafileoptionalboolMetafileoptional*bool= false#notes
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.
minifyoptionalbooleanminifyoptionalboolminifyoptionalBooleanMinifyoptionalboolMinifyoptional*bool= false#networkoptionalstringnetworkoptionalstrnetworkoptionalStringNetworkoptionalstringNetworkoptional*string#Default: no networking options
nodeModulesoptionalstring[]node_modulesoptionaltyping.List[str]nodeModulesoptionalList<String>NodeModulesoptionalstring[]NodeModulesoptional*[]*string#Default: all modules are bundled
Modules are installed in a Lambda compatible environment only when bundling runs in Docker.
platformoptionalstringplatformoptionalstrplatformoptionalStringPlatformoptionalstringPlatformoptional*string#Default: no platform specified
Example value: linux/amd64
preCompilationoptionalbooleanpre_compilationoptionalboolpreCompilationoptionalBooleanPreCompilationoptionalboolPreCompilationoptional*bool= false#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.
securityOptoptionalstringsecurity_optoptionalstrsecurityOptoptionalStringSecurityOptoptionalstringSecurityOptoptional*string#Default: no security options
sourceMapoptionalbooleansource_mapoptionalboolsourceMapoptionalBooleanSourceMapoptionalboolSourceMapoptional*bool= false#sourceMapModeoptionalSourceMapModesource_map_modeoptionalSourceMapModesourceMapModeoptionalSourceMapModeSourceMapModeoptionalSourceMapModeSourceMapModeoptionalSourceMapMode= SourceMapMode.DEFAULT#sourcesContentoptionalbooleansources_contentoptionalboolsourcesContentoptionalBooleanSourcesContentoptionalboolSourcesContentoptional*bool= true#Default: the node version of the runtime
tsconfigoptionalstringtsconfigoptionalstrtsconfigoptionalStringTsconfigoptionalstringTsconfigoptional*string#Default: automatically discovered by esbuild
notes
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' }.
Default: root or image default
volumesoptionalDockerVolume[]volumesoptionaltyping.List[DockerVolume]volumesoptionalList<DockerVolume>VolumesoptionalDockerVolume[]Volumesoptional*[]DockerVolume#Default: no volumes are mounted
volumesFromoptionalstring[]volumes_fromoptionaltyping.List[str]volumesFromoptionalList<String>VolumesFromoptionalstring[]VolumesFromoptional*[]*string#Default: no containers are specified to mount volumes from
workingDirectoryoptionalstringworking_directoryoptionalstrworkingDirectoryoptionalStringWorkingDirectoryoptionalstringWorkingDirectoryoptional*string#Default: image default