/aws-lambda-nodejs-webpack

λ CDK Construct to build Node.js AWS lambdas using webpack

Primary LanguageTypeScriptMIT LicenseMIT

Update from the maintainer: Unless you have a good reason to use Webpack with AWS lambda, you should use the default CDK construct (https://docs.aws.amazon.com/cdk/api/latest/docs/aws-lambda-nodejs-readme.html). It works really well and is even faster than this Webpack based project, thanks to esbuild. I initially wrote this Webpack based construct because, at the time, the official Node.js construct was very slow. Since September 2021 I now use the default Node.js construct.

Consider this package deprecated as I won't be maintaining it, but it works.

aws-lambda-nodejs-webpack npm Mentioned in Awesome CDK GitHub license Tests npm


CDK Construct to build Node.js AWS lambdas using webpack

Table of contents:

Usage example

yarn add aws-lambda-nodejs-webpack
// infra/super-app-stack.js
const sns = require("@aws-cdk/aws-sns");
const subscriptions = require("@aws-cdk/aws-sns-subscriptions");
const core = require("@aws-cdk/core");
const { NodejsFunction } = require("aws-lambda-nodejs-webpack");

module.exports = class SuperAppProductionStack extends core.Stack {
  constructor(scope, id, props) {
    super(scope, id, props);

    const slackNotificationsLambda = new NodejsFunction(
      this,
      "slack-notifications-lambda",
      {
        entry: "events/slack-notifications.js", // required
      },
    );
  }
};
// events/slack-notifications.js
import { WebClient as SlackWebClient } from "@slack/web-api";

export function handler(event) {
  const message = event.Records[0].Sns.Message;
  // do something with message
}

Features

  • webpack 5
  • compiles and deploys to Node.js 14.x by default
  • fast, no-docker CDK construct
  • lambda output only contains the necessary files, no README, tests, ...
  • bundling happens in temporary directories, it never writes in your project directory
  • source map support
  • TypeScript support
  • Babel support (preset-env)
  • babel & webpack caching
  • node_modules are split into a single vendor.js file. Allowing you to debug your own code in AWS console most of the time

Why?

There's already a dedicated aws-lambda-nodejs module for CDK but I had two major issues with it:

  1. CDK uses docker for anything lambda build related. This means it mounts your whole Node.js project (not just the lambda code) inside Docker before running a bundler like Parcel. This is perfectly fine and performant on Linux and Windows, but this is extremely slow on macOS: a single cdk synth would take 2 minutes for a 3 lines lambda. Since it might take a very long time for Docker on macOS to get as fast as on Linux. Even their latest update (mutagen), while significantly faster, still takes 20s just to mount a Node.js project.
  2. aws-lambda-nodejs generates a single file bundle with every local and external module inlined. Which makes it very hard to debug and read on the AWS console. I wanted a lambda output that mimicks my project file organization.

I want to be clear: I respect a LOT the work of the CDK team, and especially @jogold, author of aws-lambda-nodejs) that helped me a lot into debugging performance issues and explaining to me how everything works.

Caveats

⚠️ the only configuration file from your project that we will read is tsconfig.json (not including compilerOptions, which are overwritten using https://www.npmjs.com/package/@tsconfig/node12).

Other files won't be used (example: .babelrc). If you need to reuse part of your babel configuration, please open an issue with details on your usecase so we can build the best API for how to do this.

How to make changes and test locally

// fork and clone
cd aws-lambda-nodejs-webpack
yarn
yarn link
yarn start

# in another terminal and project where you want to test changes
yarn link aws-lambda-nodejs-webpack
# cdk commands will now use your local aws-lambda-nodejs-webpack

Thanks

  • the CDK team for this awesome project
  • @jogold for his time while helping me debugging performance issues on Docker