The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
This library provides constructs for Node.js Lambda functions.
To use this module, you will need to have Docker installed.
Define a NodejsFunction
:
new lambda.NodejsFunction(this, 'my-handler');
By default, the construct will use the name of the defining file and the construct's id to look up the entry file:
.
├── stack.ts # defines a 'NodejsFunction' with 'my-handler' as id
├── stack.my-handler.ts # exports a function named 'handler'
This file is used as "entry" for esbuild. This means that your code is automatically transpiled and bundled whether it's written in JavaScript or TypeScript.
Alternatively, an entry file and handler can be specified:
new lambda.NodejsFunction(this, 'MyFunction', {
entry: '/path/to/my/file.ts', // accepts .js, .jsx, .ts and .tsx files
handler: 'myExportedFunc'
});
All other properties of lambda.Function
are supported, see also the AWS Lambda construct library.
The NodejsFunction
construct automatically reuses existing connections
when working with the AWS SDK for JavaScript. Set the awsSdkConnectionReuse
prop to false
to disable it.
The NodejsFunction
requires a dependencies lock file (yarn.lock
or
package-lock.json
). When bundling in a Docker container, the path containing this
lock file is used as the source (/asset-input
) for the volume mounted in the
container.
By default, the construct will try to automatically determine your project lock file.
Alternatively, you can specify the depsLockFilePath
prop manually. In this
case you need to ensure that this path includes entry
and any module/dependencies
used by your function. Otherwise bundling will fail.
If esbuild
is available it will be used to bundle your code in your environment. Otherwise,
bundling will happen in a Lambda compatible Docker container.
For macOS the recommendend approach is to install esbuild
as Docker volume performance is really poor.
esbuild
can be installed with:
$ npm install --save-dev esbuild@0
OR
$ yarn add --dev esbuild@0
To force bundling in a Docker container even if esbuild
is available in your environment,
set bundling.forceDockerBundling
to true
. This is useful if your function relies on node
modules that should be installed (nodeModules
prop, see below) in a Lambda
compatible environment. This is usually the case with modules using native dependencies.
By default, all node modules are bundled except for aws-sdk
. This can be configured by specifying
bundling.externalModules
:
new lambda.NodejsFunction(this, 'my-handler', {
bundling: {
externalModules: [
'aws-sdk', // Use the 'aws-sdk' available in the Lambda runtime
'cool-module', // 'cool-module' is already available in a Layer
],
},
});
By default, all node modules referenced in your Lambda code will be bundled by esbuild
.
Use the nodeModules
prop under bundling
to specify a list of modules that should not be
bundled but instead included in the node_modules
folder of the Lambda package. This is useful
when working with native dependencies or when esbuild
fails to bundle a module.
new lambda.NodejsFunction(this, 'my-handler', {
bundling: {
nodeModules: ['native-module', 'other-module'],
},
});
The modules listed in nodeModules
must be present in the package.json
's dependencies or
installed. The same version will be used for installation. The lock file (yarn.lock
or
package-lock.json
) will be used along with the right installer (yarn
or npm
).
When working with nodeModules
using native dependencies, you might want to force bundling in a
Docker container even if esbuild
is available in your environment. This can be done by setting
bundling.forceDockerBundling
to true
.
The NodejsFunction
construct exposes some esbuild options
via properties under bundling
: minify
, sourceMap
, target
and loader
.
new lambda.NodejsFunction(this, 'my-handler', {
bundling: {
minify: true, // minify code, defaults to false
sourceMap: true, // include source map, defaults to false
target: 'es2020', // target environment for the generated JavaScript code
loader: { // Use the 'dataurl' loader for '.png' files
'.png': 'dataurl',
},
},
});
It is possible to run additional commands by specifying the commandHooks
prop:
new lambda.NodejsFunction(this, 'my-handler-with-commands', {
commandHooks: {
// Copy a file so that it will be included in the bundled asset
afterBundling(inputDir: string, outputDir: string): string[] {
return [`cp ${inputDir}/my-binary.node ${outputDir}`];
}
// ...
}
});
The following hooks are available:
beforeBundling
: runs before all bundling commandsbeforeInstall
: runs before node modules installationafterBundling
: runs after all bundling commands
They all receive the directory containing the lock file (inputDir
) and the
directory where the bundled asset will be output (outputDir
). They must return
an array of commands to run. Commands are chained with &&
.
The commands will run in the environment in which bundling occurs: inside the container for Docker bundling or on the host OS for local bundling.
Use bundling.environment
to define environments variables when esbuild
runs:
new lambda.NodejsFunction(this, 'my-handler', {
bundling: {
environment: {
NODE_ENV: 'production',
},
},
});
Use bundling.buildArgs
to pass build arguments when building the Docker bundling image:
new lambda.NodejsFunction(this, 'my-handler', {
bundling: {
buildArgs: {
HTTPS_PROXY: 'https://127.0.0.1:3001',
},
}
});
Use bundling.dockerImage
to use a custom Docker bundling image:
new lambda.NodejsFunction(this, 'my-handler', {
bundling: {
dockerImage: cdk.BundlingDockerImage.fromAsset('/path/to/Dockerfile'),
},
});
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.
Use the default image provided by @aws-cdk/aws-lambda-nodejs
as a source of inspiration.