AWS Lambda Function Builder

1.0.8 · maintenance · verified Sun Apr 19

`aws-lambda-build` is a lightweight command-line interface (CLI) tool designed for building and packaging AWS Lambda functions into `.zip` archives. Its core functionality involves navigating to a specified function directory, executing `npm install` to resolve dependencies, and then zipping the entire directory contents into a deployable `.zip` file. Currently at version 1.0.8, the project has seen slow but stable development, with recent updates focusing on cross-platform compatibility across Windows, Mac, and Linux, and a transition to pure Node.js for its implementation (v1.0.4). A key differentiator is its minimal footprint, explicitly stating "no external dependencies except *archiver*", making it a highly self-contained solution compared to more complex build systems.

Common errors

```
lambda-build: command not found
```
cause The `aws-lambda-build` executable is not in the system's PATH, typically because the package was not installed globally or `npx` was not used.

fix Install the package globally: `npm install -g aws-lambda-build`, or execute it via `npx`: `npx aws-lambda-build [arguments]`.
```
Error: Function directory not found: [your/path]
```
cause The path provided to the `--function` (or `-f`) argument does not point to an existing directory containing your Lambda function code.

fix Verify that the `--function` path is correct and absolute, or relative to the directory where you are executing `lambda-build`.
```
npm ERR! code ENOSPC
```
cause During the internal `npm install` step, the system ran out of disk space, preventing dependencies from being fully installed or extracted.

fix Free up disk space on the machine where the build process is running.

Warnings

gotcha This package is primarily a command-line interface (CLI) tool and is not designed for programmatic import as a JavaScript or TypeScript library. Its core functionality is exposed exclusively via the `lambda-build` executable.
Fix: Use `npx aws-lambda-build ...` for one-off executions or `npm install -g aws-lambda-build` followed by `lambda-build ...` for frequent use. Do not attempt to `import` or `require` it as a module.
gotcha The `npm install` step performed by `aws-lambda-build` requires Node.js (>=5.0) and npm to be correctly installed and available in the system's PATH where the build command is executed.
Fix: Ensure that a compatible version of Node.js and npm are installed and accessible in your shell or CI/CD environment.
gotcha Although the tool claims cross-platform support (since v1.0.7), inconsistencies in path separators (e.g., backslashes on Windows vs. forward slashes on Linux/macOS) can still lead to errors if not handled carefully, especially when passing paths via command-line arguments.
Fix: Prefer using consistent forward slashes (`/`) for paths, which are generally compatible across operating systems, or use Node.js `path.resolve()` when generating paths programmatically.

Install

npm install aws-lambda-build npm
yarn add aws-lambda-build yarn
pnpm add aws-lambda-build pnpm

Imports

lambda-build
wrong:
```
import { lambdaBuild } from 'aws-lambda-build'
```
correct:
```
npx lambda-build --function=path/to/your/lambda --archive=output.zip
```
This package is primarily a CLI tool. Its main 'symbol' is the `lambda-build` executable, invoked via `npx` or a global installation. It does not export JavaScript modules for programmatic `import` or `require` in the traditional sense.
Function Path Argument
wrong:
```
lambda-build path/to/your/function
```
correct:
```
lambda-build -f path/to/your/function
```
The function directory path must be specified using the `--function` or `-f` flag.
Archive Name Argument
wrong:
```
lambda-build --function=... -n my-function.zip
```
correct:
```
lambda-build --function=... --archive=my-function.zip
```
The output archive name is specified using `--archive` or `-a`. The README shows `-n` in examples, but `package.json` CLI definition typically uses `-a` for archive.

Quickstart

Demonstrates how to programmatically execute the `aws-lambda-build` CLI tool via Node.js `child_process` to package a sample Lambda function. This shows the typical workflow of using the CLI.

const { exec } = require('child_process');
const path = require('path');

// Create a dummy Lambda function directory for demonstration
const functionName = 'MyTestLambda';
const functionPath = path.resolve(__dirname, functionName);
require('fs').mkdirSync(functionPath, { recursive: true });
require('fs').writeFileSync(path.join(functionPath, 'index.js'), `
exports.handler = async (event) => {
  console.log('Received event:', JSON.stringify(event, null, 2));
  return { statusCode: 200, body: JSON.stringify('Hello from ${functionName}!') };
};
`);
require('fs').writeFileSync(path.join(functionPath, 'package.json'), `
{
  "name": "${functionName.toLowerCase()}",
  "version": "1.0.0",
  "description": "A simple Lambda function",
  "main": "index.js",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}
`);

const archiveName = `${functionName}.zip`;

console.log(`Building Lambda function from: ${functionPath}`);
console.log(`Output archive: ${archiveName}`);

// Execute the aws-lambda-build CLI tool
// Using 'npx' ensures the tool is available without global installation.
exec(`npx aws-lambda-build --function=${functionPath} --archive=${archiveName} --verbose`, (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`);
    console.error(`stderr: ${stderr}`);
    return;
  }
  console.log(`stdout: ${stdout}`);
  console.log('Lambda build completed successfully!');
  console.log(`You can now upload ${archiveName} to AWS Lambda.`);
  
  // Clean up the dummy function directory and zip file
  require('fs').rmSync(functionPath, { recursive: true, force: true });
  require('fs').rmSync(archiveName, { force: true });
  console.log('Cleaned up dummy function and archive.');
});

view raw JSON →