Sealights Lambda Layer Builder

A CLI tool for building AWS Lambda layers with Sealights integration for Node.js applications. This tool enables you to create custom Lambda layers that automatically collect code coverage and quality metrics from your serverless functions.

Features

• 🚀 Build Lambda layers for any Node.js version
• 📦 Support for both CommonJS and ESM module formats
• 🐳 Docker-based build process with automatic BuildKit detection
• 🔧 Smart configuration with environment variable support
• 🎯 Optimized for CI/CD pipelines
• ⚡ Native V8 coverage collection support
• 🔍 NYC instrumentation support for static analysis

Prerequisites

Before using this tool, ensure you have the following installed:

• Node.js: v16.20.2 or higher
• npm: v6 or higher
• Docker: Required for building Lambda layers
• AWS CLI: Required for deploying layers to AWS (optional for building)

Installation

Global Installation (Recommended)

npm install -g sealights-lambda-layer-builder

Local Installation

npm install --save-dev sealights-lambda-layer-builder

Quick Start

Basic Usage

Build a Lambda layer for the default Node.js version (v22.11.0):

sealights-lambda-layer-builder

Specify Node.js Version

Build a layer for a specific Node.js version:

sealights-lambda-layer-builder --node-version v20.11.0

Specify Sealights Agent Version

sealights-lambda-layer-builder --sl-nodejs-version 6.0.0

Command Line Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --node-version | -nv | Node.js version to build the layer for | v22.11.0 | | --sl-nodejs-version | -slv | Sealights Node.js agent version | canary | | --help | | Display help information | |

Environment Variables

You can configure the tool using environment variables, which is especially useful in CI/CD pipelines:

Build Configuration

• SL_NODE_VERSION - Default Node.js version if not specified via CLI
• SL_NODEJS_VERSION - Default slnodejs package version

Docker Configuration

• DOCKER_BUILDKIT - Force enable/disable BuildKit (0 or 1)
• DOCKER_BUILD_TIMEOUT - Timeout for Docker build operations

Output

The tool generates two variants of the Lambda layer:

1. CommonJS (CJS) - sealights-extension-node-{version}-cjs.zip
2. ES Modules (ESM) - sealights-extension-node-{version}-esm.zip

Both files are created in the current directory.

Deploying to AWS

After building the layer, you can deploy it to AWS using the AWS CLI:

# Navigate to scripts directory
cd scripts

# Publish the layer
./publish.sh ../sealights-extension-node-20.11.0-cjs.zip sealights-node-20-cjs us-east-1

The publish script will return an ARN that you can use in your Lambda configuration.

Using the Layer in Lambda

1. Add the Layer to Your Lambda Function

In your serverless.yml or SAM template:

functions:
  myFunction:
    handler: index.handler
    layers:
      - arn:aws:lambda:us-east-1:123456789:layer:sealights-node-20-cjs:1
    environment:
      AWS_LAMBDA_EXEC_WRAPPER: /opt/sealights-extension
      SL_TOKEN: ${env:SL_TOKEN}
      SL_BUILD_SESSION_ID: ${env:SL_BUILD_SESSION_ID}

2. Required Environment Variables

Configure these environment variables in your Lambda function:

• AWS_LAMBDA_EXEC_WRAPPER - Must be set to /opt/sealights-extension
• SL_TOKEN - Your Sealights token
• SL_BUILD_SESSION_ID - Build session ID from Sealights

3. Optional Environment Variables

• SL_PROJECT_ROOT - Project root path (usually auto-detected)
• SL_COLLECTOR_URL - Custom collector URL
• SL_LAB_ID - Lab ID for test separation
• SL_PROXY - Proxy URL for Sealights communication
• SL_RAW_COVERAGE - Enable raw V8 coverage mode (true/false)

Coverage Collection Modes

V8 Coverage (Default)

The layer uses native V8 coverage by default, which provides:

• Zero instrumentation overhead
• Accurate coverage data
• No code modification required

NYC Coverage

For static instrumentation, set SL_USE_NYC=true and instrument your code before deployment:

npx nyc instrument src --in-place

Examples

Building for AWS Lambda Node.js 18.x Runtime

sealights-lambda-layer-builder --node-version v18.20.0

Building with Specific Sealights Version

sealights-lambda-layer-builder --node-version v20.11.0 --sl-nodejs-version 5.2.0

CI/CD Pipeline Example

# In your CI/CD pipeline
export SL_NODE_VERSION=v20.11.0
sealights-lambda-layer-builder

Troubleshooting

Docker BuildKit Issues

If you encounter BuildKit compatibility issues, the tool will automatically fall back to the legacy builder. You can also force the legacy builder:

export DOCKER_BUILDKIT=0
sealights-lambda-layer-builder

Permission Issues

Make sure Docker is running and you have the necessary permissions:

# Check Docker status
docker info

# Clean Docker cache if needed
docker system prune -f

Node.js Version Compatibility

Ensure the Node.js version you're building for:

1. Has a corresponding Alpine Docker image on Docker Hub
2. Is compatible with your Lambda runtime

Supported Node.js Versions

This tool supports any Node.js version that has:

• An official Alpine Linux Docker image
• AWS Lambda runtime compatibility

Common versions:

• Node.js 18.x (Lambda runtime: nodejs18.x)
• Node.js 20.x (Lambda runtime: nodejs20.x)
• Node.js 22.x (For future Lambda runtime support)