Claudia 5: better packaging and NPM5 support

• By Gojko Adzic
• Jun 7, 2018

Claudia 5.0.0 is now on NPM, making it much easier to use NPM 5 and 6 with AWS Lambda projects. And not just with Claudia, but with other tools as well. In particular, Claudia 5.x will be very helpful for teams using the AWS Serverless Application Model (SAM) if they want to get the most out of Node 8 and NPM 5.

The Serveless Application Model significantly simplifies running a web API backed by a Lambda function, but it is language and platform agnostic by design. SAM makes it very easy to upload code to AWS, but it will just package the target directory, regardless of whether it includes development dependencies or symbolic links to folders elsewhere on the disk. For JavaScript developers, this either meant creating a complicated deployment pipeline to remove development and optional dependencies every time, or creating a separate project just for packaging and then using local file links. NPM 5 made the second option much more troublesome, as relative directory dependencies are just symbolically linked instead of copied and packaged. The change makes it faster to develop locally, but if you’re using file: dependencies for packaging with NPM 5, you might unintentionally get development dependencies of your local production dependencies in the package. And it’s very difficult to enforce a clean setup, as each dependent project has to be cleaned up individually.

SAM doesn’t know about NPM. But Claudia does, and that’s one of its best features. Until version 5, if you wanted to get the benefits from the Claudia packaging pipeline, you had to use Claudia to deploy as well. With version 5, we introduced a new command, claudia pack, that just creates a clean deployable ZIP with all the knowledge of NPM, so you can use it inside SAM, CloudFormation or with any other tool. claudia pack will use your NPM configuration to include only the required files, include only production dependencies, repackage all the local file: dependencies correctly, remove duplicated dependencies to reduce the package size, copy everything into node_modules without symbolic links and fix potential file permission problems in all the dependencies. You can even customise packaging by including a post-package script in your NPM project, and claudia will run it after the files are ready but before producing the final zip. Because development dependencies will be excluded automatically, it’s safe to include claudia as a development dependency in your SAM projects directly, so you don’t have to install it to your global modules.

By default, claudia will save the zip into a file named based on the current NPM project name and version, but you can use --output <FILE NAME> to specify a name. This is useful for automated build pipelines, as you can then use the resulting ZIP directly as your CodeUri parameter in SAM and CloudFormation templates.

Check out the example project showing how to use the new command, or the claudia pack documentation for more information about the packaging options.

Note that claudia pack only prepares the code for deployment, it does not produce a CloudFormation/SAM template, so it will not automatically create the Web API definition for you.

Other notable changes

Because AWS has announced that they are dropping support for Node 4.3 in Lambda from July, Claudia 5.x now uses version 6 as the baseline. This means that you will no longer be able to use Node 4 for running Claudia itself. You can still deploy 4.3 projects to Lambda, but using at least Node 6.10 from the deployment machine. Because of this backwards-incompatible change, we increased the major version of the tool to 5.x, so you won’t get a surprise upgrade automatically. If you require running in Node 4, keep using Claudia 4.x until the July switch-over date.

Here are some other important new features

• use --npm-options to pass additional options to NPM when installing packages. Useful to specify behaviour for package locking.
• packaging using NPM 6 is now faster as audits are turned off by default
• packaging support for NPM 5 and 6 using relative file dependencies – this previously worked only with NPM 3 because NPM 5 uses symbolic links for relative references
• upload size optimised using for NPM 5 and 6 by deduping dependencies after packaging
• use --post-package-script=<NPM SCRIPT NAME> with claudia create or claudia update to execute a custom post-package step to clean up resources, optimise package size etc. This runs after all validations are complete, and development dependencies are not available at this stage… but you can use npm to uninstall utility tools as part of this step if needed.
• claudia automatically fixes file access permissions in your package that would prevent Lambda from running code.
• NPM output is now directly written to the console, rather than a separate log file, to make packaging errors more obvious
• (for newly created functions only) claudia destroy will not delete a role if it was created using --role