Package: aws-cdk.aws-lambda-nodejs
Amazon Lambda Node.js Library---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.For more information on how to migrate, see theMigrating to AWS CDK v2guide.This library provides constructs for Node.js Lambda functions.Node.js FunctionTheNodejsFunctionconstruct creates a Lambda function with automatic transpiling and bundling
of TypeScript or Javascript code. This results in smaller Lambda packages that contain only the
code and dependencies needed to run the function.It usesesbuildunder the hood.Reference project architectureTheNodejsFunctionallows you to define your CDK and runtime dependencies in a single
package.json and to collocate your runtime code with your infrastructure code:.
├── lib
│   ├── my-construct.api.ts # Lambda handler for API
│   ├── my-construct.auth.ts # Lambda handler for Auth
│   └── my-construct.ts # CDK construct with two Lambda functions
├── package-lock.json # single lock file
├── package.json # CDK and runtime dependencies defined in a single package.json
└── tsconfig.jsonBy default, the construct will use the name of the defining file and the construct's
id to look up the entry file. Inmy-construct.tsabove we have:# automatic entry look upapi_handler=lambda_.NodejsFunction(self,"api")auth_handler=lambda_.NodejsFunction(self,"auth")Alternatively, an entry file and handler can be specified:lambda_.NodejsFunction(self,"MyFunction",entry="/path/to/my/file.ts",# accepts .js, .jsx, .ts, .tsx and .mjs fileshandler="myExportedFunc")For monorepos, the reference architecture becomes:.
├── packages
│   ├── cool-package
│   │   ├── lib
│   │   │   ├── cool-construct.api.ts
│   │   │   ├── cool-construct.auth.ts
│   │   │   └── cool-construct.ts
│   │   ├── package.json # CDK and runtime dependencies for cool-package
│   │   └── tsconfig.json
│   └── super-package
│       ├── lib
│       │   ├── super-construct.handler.ts
│       │   └── super-construct.ts
│       ├── package.json # CDK and runtime dependencies for super-package
│       └── tsconfig.json
├── package-lock.json # single lock file
├── package.json # root dependencies
└── tsconfig.jsonCustomizing the underlying Lambda functionAll properties oflambda.Functioncan be used to customize the underlyinglambda.Function.See also theAWS Lambda construct library.TheNodejsFunctionconstruct automaticallyreuses existing connectionswhen working with the AWS SDK for JavaScript. Set theawsSdkConnectionReuseprop tofalseto disable it.Lock fileTheNodejsFunctionrequires a dependencies lock file (yarn.lock,pnpm-lock.yamlorpackage-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 thedepsLockFilePathprop manually. In this
case you need to ensure that this path includesentryand any module/dependencies
used by your function. Otherwise bundling will fail.Local bundlingIfesbuildis available it will be used to bundle your code in your environment. Otherwise,
bundling will happen in aLambda compatible Docker containerwith the Docker platform based on the target architecture of the Lambda function.For macOS the recommended approach is to installesbuildas Docker volume performance is really poor.esbuildcan be installed with:$npminstall--save-devesbuild@0OR$yarnadd--devesbuild@0If you're using a monorepo layout, theesbuilddependency needs to be installed in the "root"package.jsonfile,
not in the workspace. From the reference architecture describedabove, theesbuilddev dependency needs to be in./package.json, notpackages/cool-package/package.jsonorpackages/super-package/package.json.To force bundling in a Docker container even ifesbuildis available in your environment,
setbundling.forceDockerBundlingtotrue. This is useful if your function relies on node
modules that should be installed (nodeModulesprop, seebelow) in a Lambda
compatible environment. This is usually the case with modules using native dependencies.Working with modulesExternalsBy default, all node modules are bundled except foraws-sdk. This can be configured by specifyingbundling.externalModules:lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(external_modules=["aws-sdk","cool-module"]))Install modulesBy default, all node modules referenced in your Lambda code will be bundled byesbuild.
Use thenodeModulesprop underbundlingto specify a list of modules that should not be
bundled but instead included in thenode_modulesfolder of the Lambda package. This is useful
when working with native dependencies or whenesbuildfails to bundle a module.lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(node_modules=["native-module","other-module"]))The modules listed innodeModulesmust be present in thepackage.json's dependencies or
installed. The same version will be used for installation. The lock file (yarn.lock,pnpm-lock.yamlorpackage-lock.json) will be used along with the right installer (yarn,pnpmornpm).When working withnodeModulesusing native dependencies, you might want to force bundling in a
Docker container even ifesbuildis available in your environment. This can be done by settingbundling.forceDockerBundlingtotrue.ConfiguringesbuildTheNodejsFunctionconstruct exposesesbuild optionsvia properties underbundling:lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(minify=True,# minify code, defaults to falsesource_map=True,# include source map, defaults to falsesource_map_mode=lambda_.SourceMapMode.INLINE,# defaults to SourceMapMode.DEFAULTsources_content=False,# do not include original source into source map, defaults to truetarget="es2020",# target environment for the generated JavaScript codeloader={# Use the 'dataurl' loader for '.png' files".png":"dataurl"},define={# Replace strings during build time"process.env.API_KEY":JSON.stringify("xxx-xxxx-xxx"),"process.env.PRODUCTION":JSON.stringify(True),"process.env.NUMBER":JSON.stringify(123)},log_level=lambda_.LogLevel.SILENT,# defaults to LogLevel.WARNINGkeep_names=True,# defaults to falsetsconfig="custom-tsconfig.json",# use custom-tsconfig.json instead of default,metafile=True,# include meta file, defaults to falsebanner="/* comments */",# requires esbuild >= 0.9.0, defaults to nonefooter="/* comments */",# requires esbuild >= 0.9.0, defaults to nonecharset=lambda_.Charset.UTF8,# do not escape non-ASCII characters, defaults to Charset.ASCIIformat=lambda_.OutputFormat.ESM,# ECMAScript module output format, defaults to OutputFormat.CJS (OutputFormat.ESM requires Node.js 14.x)main_fields=["module","main"],# prefer ECMAScript versions of dependenciesinject=["./my-shim.js","./other-shim.js"],# allows to automatically replace a global variable with an import from another fileesbuild_args={# Pass additional arguments to esbuild"--log-limit":"0","--splitting":True}))Command hooksIt is possible to run additional commands by specifying thecommandHooksprop:// This example only available in TypeScript
// Run additional props via `commandHooks`
new lambda.NodejsFunction(this, 'my-handler-with-commands', {
  bundling: {
    commandHooks: {
      beforeBundling(inputDir: string, outputDir: string): string[] {
        return [
          `echo hello > ${inputDir}/a.txt`,
          `cp ${inputDir}/a.txt ${outputDir}`,
        ];
      },
      afterBundling(inputDir: string, outputDir: string): string[] {
        return [`cp ${inputDir}/b.txt ${outputDir}/txt`];
      },
      beforeInstall() {
        return [];
      },
      // ...
    },
    // ...
  },
});The following hooks are available:beforeBundling: runs before all bundling commandsbeforeInstall: runs before node modules installationafterBundling: runs after all bundling commandsThey 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.Pre Compilation with TSCIn some cases,esbuildmay not yet support some newer features of the typescript language, such as,emitDecoratorMetadata.
In such cases, it is possible to run pre-compilation usingtscby setting thepreCompilationflag.lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(pre_compilation=True))Note: Atsconfig.jsonfileis requiredCustomizing Docker bundlingUsebundling.environmentto define environments variables whenesbuildruns:lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(environment={"NODE_ENV":"production"}))Usebundling.buildArgsto pass build arguments when building the Docker bundling image:lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(build_args={"HTTPS_PROXY":"https://127.0.0.1:3001"}))Usebundling.dockerImageto use a custom Docker bundling image:lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(docker_image=DockerImage.from_build("/path/to/Dockerfile")))This image should haveesbuildinstalledglobally. If you plan to usenodeModulesit
should also havenpm,yarnorpnpmdepending on the lock file you're using.Use thedefault image provided by@aws-cdk/aws-lambda-nodejsas a source of inspiration.Asset hashBy default the asset hash will be calculated based on the bundled output (AssetHashType.OUTPUT).Use theassetHashprop to pass a custom hash:lambda_.NodejsFunction(self,"my-handler",bundling=lambda.BundlingOptions(asset_hash="my-custom-hash"))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.