BundlingOptions¶

class aws_cdk.aws_lambda_nodejs.BundlingOptions(*, asset_hash=None, banner=None, build_args=None, charset=None, command_hooks=None, define=None, docker_image=None, environment=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: object

Bundling options.

Parameters

asset_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 output
banner (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 passed
build_args (Optional[Mapping[str, str]]) – Build arguments to pass when building the bundling image. Default: - no build arguments are passed
charset (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, use Charset.UTF8. Default: Charset.ASCII
command_hooks (Optional[ICommandHooks]) – Command hooks. Default: - do not run additional commands
define (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 made
docker_image (Optional[DockerImage]) – A custom bundling Docker image. This image should have esbuild installed globally. If you plan to use nodeModules it should also have npm or yarn depending on the lock file you’re using. See https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-lambda-nodejs/lib/Dockerfile for the default image provided by @aws-cdk/aws-lambda-nodejs. Default: - use the Docker image provided by
environment (Optional[Mapping[str, str]]) – Environment variables defined when bundling runs. Default: - no environment variables are defined.
esbuild_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 passed
esbuild_version (Optional[str]) – The version of esbuild to use when running in a Docker container. Default: - latest v0
external_modules (Optional[Sequence[str]]) – A list of modules that should be considered as externals (already available in the runtime). Default: [‘aws-sdk’]
footer (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 passed
force_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: false
format (Optional[OutputFormat]) – Output format for the generated JavaScript files. Default: OutputFormat.CJS
inject (Optional[Sequence[str]]) – This option allows you to automatically replace a global variable with an import from another file. Default: - no code is injected
keep_names (Optional[bool]) – 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. Default: false
loader (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 an import statement or a require call. Default: - use esbuild default loaders
log_level (Optional[LogLevel]) – Log level for esbuild. This is also propagated to the package manager and applies to its specific install command. Default: LogLevel.WARNING
main_fields (Optional[Sequence[str]]) – How to determine the entry point for modules. Try [‘module’, ‘main’] to default to ES module versions. Default: [‘main’, ‘module’]
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: false
minify (Optional[bool]) – Whether to minify files when bundling. Default: false
node_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 bundled
pre_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’s tsc compiler. One example of such feature is emitDecoratorMetadata. Default: false
source_map (Optional[bool]) – Whether to include source maps when bundling. Default: false
source_map_mode (Optional[SourceMapMode]) – Source map mode to be used when bundling. Default: SourceMapMode.DEFAULT
sources_content (Optional[bool]) – Whether to include original source code in source maps when bundling. Default: true
target (Optional[str]) – Target environment for the generated JavaScript code. Default: - the node version of the runtime
tsconfig (Optional[str]) – 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

ExampleMetadata

infused

Example:

lambda_.NodejsFunction(self, "my-handler",
    bundling=lambda.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

Return type

Optional[str]

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

Return type

Optional[str]

build_args¶

Build arguments to pass when building the bundling image.

Default

no build arguments are passed

Return type

Optional[Mapping[str, str]]

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: https://esbuild.github.io/api/#charset
Return type: Optional[Charset]

command_hooks¶

Command hooks.

Default

do not run additional commands

Return type

Optional[ICommandHooks]

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

Return type

Optional[Mapping[str, str]]

docker_image¶

A custom bundling Docker image.

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

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

Default

use the Docker image provided by

Aws-cdk

/aws-lambda-nodejs

Return type

Optional[DockerImage]

environment¶

Environment variables defined when bundling runs.

Default

no environment variables are defined.

Return type

Optional[Mapping[str, str]]

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

Return type

Optional[Mapping[str, Union[str, bool]]]

esbuild_version¶

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

Default

latest v0

Return type

Optional[str]

external_modules¶

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

Default: [‘aws-sdk’]
Return type: Optional[List[str]]

footer¶

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

Return type

Optional[str]

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
Return type: Optional[bool]

format¶

Output format for the generated JavaScript files.

Default: OutputFormat.CJS
Return type: Optional[OutputFormat]

inject¶

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

Default

no code is injected

See

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

Return type

Optional[List[str]]

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

Default: false
Return type: Optional[bool]

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 a require call.

Default

use esbuild default loaders

See

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

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

Return type: Optional[Mapping[str, str]]

log_level¶

Log level for esbuild.

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

Default: LogLevel.WARNING
Return type: Optional[LogLevel]

main_fields¶

How to determine the entry point for modules.

Try [‘module’, ‘main’] to default to ES module versions.

Default: [‘main’, ‘module’]
Return type: Optional[List[str]]

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: https://esbuild.github.io/api/#metafile
Return type: Optional[bool]

minify¶

Whether to minify files when bundling.

Default: false
Return type: Optional[bool]

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

Return type

Optional[List[str]]

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 is emitDecoratorMetadata.

Default: false
Return type: Optional[bool]

source_map¶

Whether to include source maps when bundling.

Default: false
Return type: Optional[bool]

source_map_mode¶

Source map mode to be used when bundling.

Default: SourceMapMode.DEFAULT
See: https://esbuild.github.io/api/#sourcemap
Return type: Optional[SourceMapMode]

sources_content¶

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

Default: true
See: https://esbuild.github.io/api/#sources-content
Return type: Optional[bool]

target¶

Target environment for the generated JavaScript code.

Default

the node version of the runtime

See

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

Return type

Optional[str]

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

Return type

Optional[str]