BundlingOptions
- class aws_cdk.aws_lambda_nodejs.BundlingOptions(*, command=None, entrypoint=None, environment=None, network=None, platform=None, security_opt=None, user=None, volumes=None, volumes_from=None, working_directory=None, asset_hash=None, banner=None, build_args=None, bundle_aws_sdk=None, bundling_file_access=None, charset=None, command_hooks=None, define=None, docker_image=None, esbuild_args=None, esbuild_version=None, external_modules=None, footer=None, force_docker_bundling=None, format=None, inject=None, keep_names=None, loader=None, log_level=None, main_fields=None, metafile=None, minify=None, node_modules=None, pre_compilation=None, source_map=None, source_map_mode=None, sources_content=None, target=None, tsconfig=None)
Bases:
DockerRunOptions
Bundling options.
- Parameters:
command (
Optional
[Sequence
[str
]]) – The command to run in the container. Default: - run the command defined in the imageentrypoint (
Optional
[Sequence
[str
]]) – The entrypoint to run in the container. Default: - run the entrypoint defined in the imageenvironment (
Optional
[Mapping
[str
,str
]]) – The environment variables to pass to the container. Default: - no environment variables.network (
Optional
[str
]) – Docker Networking options. Default: - no networking optionsplatform (
Optional
[str
]) – Set platform if server is multi-platform capable. Requires Docker Engine API v1.38+. Example value:linux/amd64
Default: - no platform specifiedsecurity_opt (
Optional
[str
]) – Security configuration when running the docker container. Default: - no security optionsuser (
Optional
[str
]) – The user to use when running the container. Default: - root or image defaultvolumes (
Optional
[Sequence
[Union
[DockerVolume
,Dict
[str
,Any
]]]]) – Docker volumes to mount. Default: - no volumes are mountedvolumes_from (
Optional
[Sequence
[str
]]) – Where to mount the specified volumes from. Default: - no containers are specified to mount volumes fromworking_directory (
Optional
[str
]) – Working directory inside the container. Default: - image defaultasset_hash (
Optional
[str
]) – 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. Default: - asset hash is calculated based on the bundled outputbanner (
Optional
[str
]) – 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: Default: - no comments are passedbuild_args (
Optional
[Mapping
[str
,str
]]) – Build arguments to pass when building the bundling image. Default: - no build arguments are passedbundle_aws_sdk (
Optional
[bool
]) – Includes AWS SDK in the bundle asset. Default: - false iftrue
theaws-sdk
will be included in the asset bundle and not be resolved to the Lambda provided sdk.bundling_file_access (
Optional
[BundlingFileAccess
]) – Which option to use to copy the source files to the docker container and output files back. Default: - BundlingFileAccess.BIND_MOUNTcharset (
Optional
[Charset
]) – 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, useCharset.UTF8
. Default: Charset.ASCIIcommand_hooks (
Optional
[ICommandHooks
]) – Command hooks. Default: - do not run additional commandsdefine (
Optional
[Mapping
[str
,str
]]) – Replace global identifiers with constant expressions. For example,{ 'process.env.DEBUG': 'true' }
. Another example,{ 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }
. Default: - no replacements are madedocker_image (
Optional
[DockerImage
]) – A custom bundling Docker image. This image should have esbuild installed globally. If you plan to usenodeModules
it should also havenpm
,yarn
orpnpm
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. Default: - use the Docker image provided by aws-cdk-lib/aws-lambda-nodejsesbuild_args (
Optional
[Mapping
[str
,Union
[str
,bool
]]]) – Build arguments to pass into esbuild. For example, to add the –log-limit flag:: new NodejsFunction(scope, id, { … bundling: { esbuildArgs: { “–log-limit”: “0”, } } }); Default: - no additional esbuild arguments are passedesbuild_version (
Optional
[str
]) – The version of esbuild to use when running in a Docker container. Default: - latest v0external_modules (
Optional
[Sequence
[str
]]) – A list of modules that should be considered as externals (already available in the runtime). Default: - no replacements are madefooter (
Optional
[str
]) – 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 Default: - no comments are passedforce_docker_bundling (
Optional
[bool
]) – 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. Default: falseformat (
Optional
[OutputFormat
]) – Output format for the generated JavaScript files. Default: OutputFormat.CJSinject (
Optional
[Sequence
[str
]]) – This option allows you to automatically replace a global variable with an import from another file. Default: - no code is injectedkeep_names (
Optional
[bool
]) – Whether to preserve the originalname
values even in minified code. In JavaScript thename
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 thename
property for many of these cases. This is usually fine because thename
property is normally only used for debugging. However, some frameworks rely on thename
property for registration and binding purposes. If this is the case, you can enable this option to preserve the originalname
values even in minified code. Default: falseloader (
Optional
[Mapping
[str
,str
]]) – 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 animport
statement or arequire
call. For example,{ '.png': 'dataurl' }
. Default: - use esbuild default loaderslog_level (
Optional
[LogLevel
]) – Log level for esbuild. This is also propagated to the package manager and applies to its specific install command. Default: LogLevel.WARNINGmain_fields (
Optional
[Sequence
[str
]]) – How to determine the entry point for modules. Try [‘module’, ‘main’] to default to ES module versions. Default: []metafile (
Optional
[bool
]) – 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. Default: falseminify (
Optional
[bool
]) – Whether to minify files when bundling. Default: falsenode_modules (
Optional
[Sequence
[str
]]) – 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. Default: - all modules are bundledpre_compilation (
Optional
[bool
]) – 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’stsc
compiler. One example of such feature isemitDecoratorMetadata
. Default: falsesource_map (
Optional
[bool
]) – Whether to include source maps when bundling. Default: falsesource_map_mode (
Optional
[SourceMapMode
]) – Source map mode to be used when bundling. Default: SourceMapMode.DEFAULTsources_content (
Optional
[bool
]) – Whether to include original source code in source maps when bundling. Default: truetarget (
Optional
[str
]) – Target environment for the generated JavaScript code. Default: - the node version of the runtimetsconfig (
Optional
[str
]) – Normally the esbuild automatically discoverstsconfig.json
files and reads their contents during a build. However, you can also configure a customtsconfig.json
file to use instead. This is similar to entry path, you need to provide path to your customtsconfig.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: - automatically discovered byesbuild
- ExampleMetadata:
infused
Example:
nodejs.NodejsFunction(self, "my-handler", bundling=nodejs.BundlingOptions( docker_image=DockerImage.from_build("/path/to/Dockerfile") ) )
Attributes
- asset_hash
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.
- Default:
asset hash is calculated based on the bundled output
- banner
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:
- Default:
no comments are passed
- build_args
Build arguments to pass when building the bundling image.
- Default:
no build arguments are passed
- bundle_aws_sdk
Includes AWS SDK in the bundle asset.
- Default:
false
if
true
theaws-sdk
will be included in the asset bundle and not be resolved to the Lambda provided sdk.
- bundling_file_access
Which option to use to copy the source files to the docker container and output files back.
- Default:
BundlingFileAccess.BIND_MOUNT
- charset
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
.- Default:
Charset.ASCII
- See:
- command
The command to run in the container.
- Default:
run the command defined in the image
- command_hooks
Command hooks.
- Default:
do not run additional commands
- define
Replace global identifiers with constant expressions.
For example,
{ 'process.env.DEBUG': 'true' }
.Another example,
{ 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }
.- Default:
no replacements are made
- docker_image
A custom bundling Docker image.
This image should have esbuild installed globally. If you plan to use
nodeModules
it should also havenpm
,yarn
orpnpm
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.
- Default:
use the Docker image provided by aws-cdk-lib/aws-lambda-nodejs
- entrypoint
The entrypoint to run in the container.
- Default:
run the entrypoint defined in the image
- environment
The environment variables to pass to the container.
- Default:
no environment variables.
- esbuild_args
Build arguments to pass into esbuild.
For example, to add the –log-limit flag:
new NodejsFunction(scope, id, { ... bundling: { esbuildArgs: { "--log-limit": "0", } } });
- Default:
no additional esbuild arguments are passed
- esbuild_version
The version of esbuild to use when running in a Docker container.
- Default:
latest v0
- external_modules
A list of modules that should be considered as externals (already available in the runtime).
- Default:
no replacements are made
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
- Default:
no comments are passed
- force_docker_bundling
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.- Default:
false
- format
Output format for the generated JavaScript files.
- Default:
OutputFormat.CJS
- inject
This option allows you to automatically replace a global variable with an import from another file.
- Default:
no code is injected
- See:
- keep_names
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 thename
property is normally only used for debugging. However, some frameworks rely on thename
property for registration and binding purposes. If this is the case, you can enable this option to preserve the originalname
values even in minified code.- Default:
false
- loader
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 arequire
call.For example,
{ '.png': 'dataurl' }
.- Default:
use esbuild default loaders
- See:
- log_level
Log level for esbuild.
This is also propagated to the package manager and applies to its specific install command.
- Default:
LogLevel.WARNING
- main_fields
How to determine the entry point for modules.
Try [‘module’, ‘main’] to default to ES module versions.
- Default:
[]
- metafile
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.
- Default:
false
- See:
- minify
Whether to minify files when bundling.
- Default:
false
- network
//docs.docker.com/engine/reference/commandline/run/#connect-a-container-to-a-network—network>`_.
- Default:
no networking options
- Type:
Docker `Networking options <https
- node_modules
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.
- Default:
all modules are bundled
- platform
Set platform if server is multi-platform capable. Requires Docker Engine API v1.38+.
Example value:
linux/amd64
- Default:
no platform specified
- pre_compilation
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 isemitDecoratorMetadata
.- Default:
false
- security_opt
//docs.docker.com/engine/reference/run/#security-configuration>`_ when running the docker container.
- Default:
no security options
- Type:
`Security configuration <https
- source_map
Whether to include source maps when bundling.
- Default:
false
- source_map_mode
Source map mode to be used when bundling.
- Default:
SourceMapMode.DEFAULT
- See:
- sources_content
Whether to include original source code in source maps when bundling.
- Default:
true
- See:
- target
Target environment for the generated JavaScript code.
- Default:
the node version of the runtime
- See:
- tsconfig
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' }
.- Default:
automatically discovered by
esbuild
- user
The user to use when running the container.
- Default:
root or image default
- volumes
Docker volumes to mount.
- Default:
no volumes are mounted
- volumes_from
Where to mount the specified volumes from.
- Default:
no containers are specified to mount volumes from
- See:
https://docs.docker.com/engine/reference/commandline/run/#mount-volumes-from-container—volumes-from
- working_directory
Working directory inside the container.
- Default:
image default