Skip to main content

The CDK Construct Library for AWS Lambda in Node.js

Project description

Amazon Lambda Node.js Library

---

cdk-constructs: Stable


This library provides constructs for Node.js Lambda functions.

Node.js Function

The NodejsFunction construct 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 uses esbuild under the hood.

Reference project architecture

The NodejsFunction allows 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.json

By default, the construct will use the name of the defining file and the construct's id to look up the entry file. In my-construct.ts above we have:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
# automatic entry look up
api_handler = lambda_.NodejsFunction(self, "api")
auth_handler = lambda_.NodejsFunction(self, "auth")

Alternatively, an entry file and handler can be specified:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "MyFunction",
    entry="/path/to/my/file.ts", # accepts .js, .jsx, .ts and .tsx files
    handler="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.json

Customizing the underlying Lambda function

All properties of lambda.Function can be used to customize the underlying lambda.Function.

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.

Lock file

The NodejsFunction requires a dependencies lock file (yarn.lock, pnpm-lock.yaml 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.

Local bundling

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.

Working with modules

Externals

By default, all node modules are bundled except for aws-sdk. This can be configured by specifying bundling.externalModules:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler",
    bundling={
        "external_modules": ["aws-sdk", "cool-module"
        ]
    }
)

Install modules

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.

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler",
    bundling={
        "node_modules": ["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, pnpm-lock.yaml or package-lock.json) will be used along with the right installer (yarn, pnpm 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.

Configuring esbuild

The NodejsFunction construct exposes some esbuild options via properties under bundling:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler",
    bundling={
        "minify": True, # minify code, defaults to false
        "source_map": True, # include source map, defaults to false
        "source_map_mode": SourceMapMode.INLINE, # defaults to SourceMapMode.DEFAULT
        "target": "es2020", # target environment for the generated JavaScript code
        "loader": {# 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": LogLevel.SILENT, # defaults to LogLevel.WARNING
        "keep_names": True, # defaults to false
        "tsconfig": "custom-tsconfig.json", # use custom-tsconfig.json instead of default,
        "metafile": True, # include meta file, defaults to false
        "banner": "/* comments */", # requires esbuild >= 0.9.0, defaults to none
        "footer": "/* comments */"
    }
)

Command hooks

It is possible to run additional commands by specifying the commandHooks prop:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler-with-commands",
    bundling={
        "command_hooks": {
            # Copy a file so that it will be included in the bundled asset
            def after_bundling(self, input_dir, output_dir): return [f"cp {inputDir}/my-binary.node {outputDir}"]
        }
    }
)

The following hooks are available:

  • beforeBundling: runs before all bundling commands
  • beforeInstall: runs before node modules installation
  • afterBundling: 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.

Customizing Docker bundling

Use bundling.environment to define environments variables when esbuild runs:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler",
    bundling={
        "environment": {
            "NODE_ENV": "production"
        }
    }
)

Use bundling.buildArgs to pass build arguments when building the Docker bundling image:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler",
    bundling={
        "build_args": {
            "HTTPS_PROXY": "https://127.0.0.1:3001"
        }
    }
)

Use bundling.dockerImage to use a custom Docker bundling image:

# Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
lambda_.NodejsFunction(self, "my-handler",
    bundling={
        "docker_image": cdk.DockerImage.from_build("/path/to/Dockerfile")
    }
)

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

Use the default image provided by @aws-cdk/aws-lambda-nodejs as a source of inspiration.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aws-cdk.aws-lambda-nodejs-1.121.0.tar.gz (71.3 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file aws-cdk.aws-lambda-nodejs-1.121.0.tar.gz.

File metadata

  • Download URL: aws-cdk.aws-lambda-nodejs-1.121.0.tar.gz
  • Upload date:
  • Size: 71.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.2 CPython/3.6.5

File hashes

Hashes for aws-cdk.aws-lambda-nodejs-1.121.0.tar.gz
Algorithm Hash digest
SHA256 18ae253f50ccef7b5b9c1f9323c55541d4758ffaa48a7a03cae8fe4a0e15e8c5
MD5 6b21ab603a2c07cc303b25b8cb8feafe
BLAKE2b-256 c43f7cb842a231e46490527085ae5f1272a4d2df567c62e2557f4c1dd9d9df75

See more details on using hashes here.

File details

Details for the file aws_cdk.aws_lambda_nodejs-1.121.0-py3-none-any.whl.

File metadata

  • Download URL: aws_cdk.aws_lambda_nodejs-1.121.0-py3-none-any.whl
  • Upload date:
  • Size: 69.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.2 CPython/3.6.5

File hashes

Hashes for aws_cdk.aws_lambda_nodejs-1.121.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4bd03cb396066adc634759212a2577735591f6481c6323dff8f9624ab3737278
MD5 2f0bd01bd0205b5579213fcb9b6a0430
BLAKE2b-256 d6753be27d8d242d0fb9d48f9e77da37fe103fa547a15e34e6ccd19835a9fe5c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page