Class BundlingOptions
Bundling options.
Inheritance
Implements
Namespace: Amazon.CDK.AWS.Lambda.Nodejs
Assembly: Amazon.CDK.AWS.Lambda.Nodejs.dll
Syntax (csharp)
public class BundlingOptions : Object, IBundlingOptions
Syntax (vb)
Public Class BundlingOptions
Inherits Object
Implements IBundlingOptions
Remarks
ExampleMetadata: infused
Examples
new NodejsFunction(this, "my-handler", new NodejsFunctionProps {
Bundling = new BundlingOptions {
DockerImage = DockerImage.FromBuild("/path/to/Dockerfile")
}
});
Synopsis
Constructors
BundlingOptions() |
Properties
AssetHash | Specify a custom hash for this asset. |
Banner | Use this to insert an arbitrary string at the beginning of generated JavaScript files. |
BuildArgs | Build arguments to pass when building the bundling image. |
Charset | The charset to use for esbuild's output. |
CommandHooks | Command hooks. |
Define | Replace global identifiers with constant expressions. |
DockerImage | A custom bundling Docker image. |
Environment | Environment variables defined when bundling runs. |
EsbuildArgs | Build arguments to pass into esbuild. |
EsbuildVersion | The version of esbuild to use when running in a Docker container. |
ExternalModules | A list of modules that should be considered as externals (already available in the runtime). |
Footer | Use this to insert an arbitrary string at the end of generated JavaScript files. |
ForceDockerBundling | Force bundling in a Docker container even if local bundling is possible. |
Format | Output format for the generated JavaScript files. |
Inject | This option allows you to automatically replace a global variable with an import from another file. |
KeepNames | Whether to preserve the original |
Loader | Use loaders to change how a given input file is interpreted. |
LogLevel | Log level for esbuild. |
MainFields | How to determine the entry point for modules. |
Metafile | This option tells esbuild to write out a JSON file relative to output directory with metadata about the build. |
Minify | Whether to minify files when bundling. |
NodeModules | A list of modules that should be installed instead of bundled. |
PreCompilation | Run compilation using tsc before running file through bundling step. |
SourceMap | Whether to include source maps when bundling. |
SourceMapMode | Source map mode to be used when bundling. |
SourcesContent | Whether to include original source code in source maps when bundling. |
Target | Target environment for the generated JavaScript code. |
Tsconfig | Normally the esbuild automatically discovers |
Constructors
BundlingOptions()
public BundlingOptions()
Properties
AssetHash
Specify a custom hash for this asset.
public string AssetHash { get; set; }
Property Value
System.String
Remarks
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.
public string Banner { get; set; }
Property Value
System.String
Remarks
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
BuildArgs
Build arguments to pass when building the bundling image.
public IDictionary<string, string> BuildArgs { get; set; }
Property Value
System.Collections.Generic.IDictionary<System.String, System.String>
Remarks
Default: - no build arguments are passed
Charset
The charset to use for esbuild's output.
public Nullable<Charset> Charset { get; set; }
Property Value
System.Nullable<Charset>
Remarks
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
CommandHooks
Command hooks.
public ICommandHooks CommandHooks { get; set; }
Property Value
Remarks
Default: - do not run additional commands
Define
Replace global identifiers with constant expressions.
public IDictionary<string, string> Define { get; set; }
Property Value
System.Collections.Generic.IDictionary<System.String, System.String>
Remarks
For example, { 'process.env.DEBUG': 'true' }
.
Another example, { 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }
.
Default: - no replacements are made
DockerImage
A custom bundling Docker image.
public DockerImage DockerImage { get; set; }
Property Value
Remarks
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
Environment
Environment variables defined when bundling runs.
public IDictionary<string, string> Environment { get; set; }
Property Value
System.Collections.Generic.IDictionary<System.String, System.String>
Remarks
Default: - no environment variables are defined.
EsbuildArgs
Build arguments to pass into esbuild.
public IDictionary<string, object> EsbuildArgs { get; set; }
Property Value
System.Collections.Generic.IDictionary<System.String, System.Object>
Remarks
For example, to add the --log-limit flag:
new NodejsFunction(scope, id, {
...
bundling: {
esbuildArgs: {
"--log-limit": "0",
}
}
});
Default: - no additional esbuild arguments are passed
EsbuildVersion
The version of esbuild to use when running in a Docker container.
public string EsbuildVersion { get; set; }
Property Value
System.String
Remarks
Default: - latest v0
ExternalModules
A list of modules that should be considered as externals (already available in the runtime).
public string[] ExternalModules { get; set; }
Property Value
System.String[]
Remarks
Default: ['aws-sdk']
Footer
Use this to insert an arbitrary string at the end of generated JavaScript files.
public string Footer { get; set; }
Property Value
System.String
Remarks
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
ForceDockerBundling
Force bundling in a Docker container even if local bundling is possible.
public Nullable<bool> ForceDockerBundling { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
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.
public Nullable<OutputFormat> Format { get; set; }
Property Value
System.Nullable<OutputFormat>
Remarks
Default: OutputFormat.CJS
Inject
This option allows you to automatically replace a global variable with an import from another file.
public string[] Inject { get; set; }
Property Value
System.String[]
Remarks
Default: - no code is injected
KeepNames
Whether to preserve the original name
values even in minified code.
public Nullable<bool> KeepNames { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
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
Use loaders to change how a given input file is interpreted.
public IDictionary<string, string> Loader { get; set; }
Property Value
System.Collections.Generic.IDictionary<System.String, System.String>
Remarks
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' }
.
LogLevel
Log level for esbuild.
public Nullable<LogLevel> LogLevel { get; set; }
Property Value
System.Nullable<LogLevel>
Remarks
This is also propagated to the package manager and applies to its specific install command.
Default: LogLevel.WARNING
MainFields
How to determine the entry point for modules.
public string[] MainFields { get; set; }
Property Value
System.String[]
Remarks
Try ['module', 'main'] to default to ES module versions.
Default: ['main', 'module']
Metafile
This option tells esbuild to write out a JSON file relative to output directory with metadata about the build.
public Nullable<bool> Metafile { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
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
Whether to minify files when bundling.
public Nullable<bool> Minify { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
Default: false
NodeModules
A list of modules that should be installed instead of bundled.
public string[] NodeModules { get; set; }
Property Value
System.String[]
Remarks
Modules are installed in a Lambda compatible environment only when bundling runs in Docker.
Default: - all modules are bundled
PreCompilation
Run compilation using tsc before running file through bundling step.
public Nullable<bool> PreCompilation { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
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
SourceMap
Whether to include source maps when bundling.
public Nullable<bool> SourceMap { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
Default: false
SourceMapMode
Source map mode to be used when bundling.
public Nullable<SourceMapMode> SourceMapMode { get; set; }
Property Value
System.Nullable<SourceMapMode>
Remarks
Default: SourceMapMode.DEFAULT
SourcesContent
Whether to include original source code in source maps when bundling.
public Nullable<bool> SourcesContent { get; set; }
Property Value
System.Nullable<System.Boolean>
Remarks
Default: true
Target
Target environment for the generated JavaScript code.
public string Target { get; set; }
Property Value
System.String
Remarks
Default: - the node version of the runtime
Tsconfig
Normally the esbuild automatically discovers tsconfig.json
files and reads their contents during a build.
public string Tsconfig { get; set; }
Property Value
System.String
Remarks
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