AWS Lambda Bundler

Common errors

• Error: Cannot find module 'aws-lambda-bundler'

  cause The package is not installed in your project's `node_modules`.
  fix Run `npm install aws-lambda-bundler` or `yarn add aws-lambda-bundler` in your project directory.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` syntax within an ES Module (ESM) file, or the bundler itself does not correctly handle ESM input/output.
  fix Ensure your Lambda function code is written in CommonJS if using older tooling, or migrate to a modern bundler (like `esbuild`) that fully supports ESM input and output for Node.js Lambda functions.

• Error: EACCES: permission denied, open '/path/to/output.zip'

  cause The user running the bundling command or script does not have write permissions to the specified output directory.
  fix Ensure you have appropriate write permissions for the target output directory, or specify an output path where the user has permissions (e.g., a subdirectory within your project or a temporary directory).

Warnings

• breaking The package `aws-lambda-bundler` has not been updated in over six years and is considered abandoned. It may contain unpatched security vulnerabilities, lack support for modern Node.js runtimes (e.g., Node.js 18+), and not support contemporary JavaScript features or module systems (ESM). Using it in new projects is highly discouraged.
  Fix: Migrate to actively maintained alternatives like `@aws-cdk/aws-lambda-nodejs` (which uses `esbuild`), `serverless-esbuild`, `serverless-webpack`, or directly use `esbuild` for bundling. These tools provide better performance, security, and feature support.
• gotcha This bundler's primary optimization is to exclude the `aws-sdk` to reduce bundle size. While this was a common practice, newer AWS Lambda runtimes (Node.js 18+) include AWS SDK v3, and for optimal cold start performance and full control, it is often recommended to bundle the specific AWS SDK v3 modules your function uses with your deployment package, rather than relying on the runtime's provided SDK.
  Fix: Consider using a modern bundler that allows explicit inclusion and tree-shaking of AWS SDK v3 modules (e.g., `esbuild` with `bundleAwsSDK: true` in CDK's `NodejsFunction` configuration) to fine-tune cold start performance and ensure consistent SDK versions.
• gotcha This package might not correctly handle advanced bundling scenarios such as TypeScript transpilation, ES Modules (ESM) resolution, or robust tree-shaking for complex dependency graphs. Its 'simple' approach of just zipping and excluding `aws-sdk` may lead to larger-than-necessary bundles or runtime errors with modern codebases.
  Fix: Evaluate modern bundlers (`esbuild`, `webpack`) that offer comprehensive support for TypeScript, ESM, and advanced optimizations like dead code elimination to significantly reduce package size and improve Lambda cold start times.

Install

• npm install aws-lambda-bundler npm
• yarn add aws-lambda-bundler yarn
• pnpm add aws-lambda-bundler pnpm

Imports

• bundle
  wrong:

  const bundle = require('aws-lambda-bundler').bundle;

  correct:

  import { bundle } from 'aws-lambda-bundler';

  While the README shows CommonJS `require`, modern Node.js and TypeScript usage often prefers ES Modules. However, given the package's age, its primary API is likely CJS-first, and ESM import might not be natively supported or correctly transpiled by older versions of the tool itself. Explicit named import is correct for both CJS and ESM, assuming modern tooling can handle CJS to ESM interop.
• default export
  wrong:

  import { default as bundler } from 'aws-lambda-bundler';

  correct:

  import bundler from 'aws-lambda-bundler';

  The README excerpt suggests a named export `{ bundle }`. If there's a default export (e.g., the `bundle` function itself), it would be imported as `import bundler from 'aws-lambda-bundler';`. However, based on the provided snippet, `bundle` is a named export.

Quickstart

Demonstrates programmatic bundling of a simple AWS Lambda project, including its dependencies, into a zip file, then cleans up.

const { bundle } = require('aws-lambda-bundler');
const fs = require('fs');
const path = require('path');

async function createDummyLambdaProject() {
  const projectDir = path.join(__dirname, 'my-lambda-project');
  const handlerDir = path.join(projectDir, 'src');
  const handlerFile = path.join(handlerDir, 'handler.js');
  const packageJsonFile = path.join(projectDir, 'package.json');

  if (!fs.existsSync(handlerDir)) {
    fs.mkdirSync(handlerDir, { recursive: true });
  }

  fs.writeFileSync(handlerFile, `
exports.handler = async (event) => {
  console.log('Received event:', event);
  const response = {
    statusCode: 200,
    body: JSON.stringify('Hello from Lambda!'),
  };
  return response;
};
`);

  fs.writeFileSync(packageJsonFile, `
{
  "name": "my-lambda-project",
  "version": "1.0.0",
  "description": "A dummy lambda for bundling demo",
  "main": "src/handler.js",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}
`);

  console.log('Dummy lambda project created at:', projectDir);
  return projectDir;
}

async function runBundler() {
  const projectPath = await createDummyLambdaProject();
  try {
    console.log(`\nBundling project at ${projectPath}...`);
    // The bundle function takes the source directory and optionally an output path.
    // It returns a promise that resolves with the path to the created zip file.
    const zipFilePath = await bundle(projectPath);
    console.log(`Successfully bundled to: ${zipFilePath}`);
    console.log('You can now inspect the contents of the zip file.');
  } catch (error) {
    console.error('Bundling failed:', error);
    process.exit(1);
  } finally {
    // Clean up dummy project after bundling
    fs.rmSync(projectPath, { recursive: true, force: true });
    console.log(`Cleaned up ${projectPath}`);
  }
}

runBundler();