Claudia uses the standard Node.js packaging model (by executing npm pack
), so if you’re used to NPM, things will just work out of the box:
- all the standard patterns ignored by NPM are ignored by Claudia as well (including
.git
,.hg
and so on) - if
.gitignore
or.npmignore
exist, patterns listed in those files will be excluded (check out the NPM packaging documentation for details on how to keep files out of your package). - if the
package.json
file includes thefiles
property, only those patterns will be included. See the files section of the NPM configuration guide for more information. - all NPM workflow steps (such as
post-install
) will be executed as during a normal installation, so you can script additional tasks such as transpilation easily.
It’s a good practice, although not necessary, to explicitly list the files or file patterns you want to deploy in the files
property of package.json
. This will ensure you avoid deploying test and development resources and local configuration files. You do not have to list package.json
here, it will automatically be included.
Dependent libraries
Although the AWS Node.js deployment guide requires including the node_modules
folder for deployment, don’t add it to the files
section. Claudia will do that automatically for you. Even better, while preparing a package, Claudia will copy all the relevant files to a temporary directory and prepare a clean install, validating the package before uploading to Lambda, to make sure that you’re deploying the right version of the dependent libraries.
Claudia will install production dependencies only, so just make sure to install the dependent libraries with --save
or -S
. Development dependencies (installed with --save-dev
or -D
) will not be sent to AWS.
Excluding standard libraries
The Node.js Lambda runtime already includes some standard libraries, such as aws-sdk
and imagemagick
. You can reduce the size of your deployment package slightly by excluding those libraries, even if your code uses them. To do that, install them as optional dependencies (-O
, --save-optional
), and then provide the --no-optional-dependencies
flag when running claudia create
or claudia update
.
Using local NPM modules
Claudia normally creates a clean package and installs dependencies from scratch to help you avoid uploading development dependencies and test files. However, you can also force it to send pre-built dependencies from your local project directory. This might be useful if you want to send up precompiled binaries for a different platform (eg you use Windows locally, but want to send compiled Linux binaries).
To use the local node_modules
instead of packaging a clean installation, use the --use-local-dependencies
when running claudia create
or claudia update
. Please note that this just packages everything in the local node_modules
directory, even development and optional dependencies.
Claudia will try to load the main Lambda module during deployment, to validate the package before sending to AWS. Make sure that this module can load with just the dependencies installed in node_modules
if you want to use local dependencies. For example, if you use binaries for a different operating system, lazy-load those modules when you need them, so they do not prevent package validation.
Installation post-processing
If you need to do any post-processing or validation before deployment, you can do that in the NPM post-install
lifecycle task. Because Claudia runs npm install
to fetch the dependencies, the post-install task will kick-off directly after the dependencies are downloaded, but before the package is uploaded to AWS. (So the post-install tasks will run on your machine, not AWS).
Troubleshooting your package
Claudia uses NPM for packaging, so most of the configuration is actually in your project package.json
. Check out the NPM docs for more information on how to control the package contents.
If some files or dependencies are missing from your package, or if the package is too big, you can simulate the packaging manually to see what and when gets included:
- Claudia will first run
npm pack
to produce the source package, - then unpack the archive in a temporary directory to generate a clean package,
- then download the dependencies
- If you did not provide any specific options, it will just execute
npm install --production
.- If you decided to exclude optional dependencies, Claudia will validate your package, then remove
node_modules
and thennpm install --production --no-optional
- If you decided to exclude optional dependencies, Claudia will validate your package, then remove
- If you use local dependencies, the local
node_modules
will be copied instead of runningnpm install
.
- If you did not provide any specific options, it will just execute
Here are some common tips for troubleshooting in case of problems:
- If the package validation fails, first try loading your API module or Lambda function module in Node.js (just open
node
, thenrequire
your module in the command line). This will help you troubleshoot syntax errors. - Use
claudia pack
to produce a package without deploying. This will save a local zip file to your disk which you can inspect manually. - Run
npm pack
on the project folder to simulate NPM packaging without deploying to AWS. If some source files are missing or there are too many source files, the problem is inpackage.json
. - Run
npm install --production
in the directory where you unpacked the clean package, then try loading your module in Node again. This will help you troubleshoot dependency issues. - Use
aws lambda get-function --function-name <FUNCTION_NAME> --query Code.Location --output text
to retrieve the actual uploaded package URL. You can then download and unzip it locally to check what was processed by AWS.