Godwin Ekuma I learn so that I can solve problems.

Deploying a serverless API to AWS with Claudia.js

3 min read 1108

Claudiajs Deploying Serverless API Aws

AWS Lambda is a serverless technology that lets you run code without provisioning or managing servers. It supports most popular programming languages, including Node.js.

Why go serverless? The benefits of deploying a serverless API include auto-scalling, zero server administration, the ability to pay only for what you use, increased velocity, etc. Running your Express.js API on AWS Lambda is a great way to take advantage of all these benefits.

However, Lambda doesn’t have direct support for frameworks such as Express.js built with programming languages such as Node.js. That’s where an adapter such as Claudia.js comes in.

Claudia.js sits between AWS Lambda and your Express.js app and converts Lambda invocation events from various AWS sources, such as API gateways or application load balancers, into HTTP events that your Express app can listen to.

In this tutorial, we’ll demonstrate how to use Claudia.js to deploy a serverless API to AWS. We’ll show you how to build and deploy an Express.js application to AWS Lambda.

Here’s what we’ll cover:

The tutorial assumes that you’re conversant with Node.js, Express.js, and Lambda. Lambda expects your code to be structured a certain way. So if you want to use it to host something like an Express app, you’ll need to use an adapter like Claudia.js.

What is Claudia.js?

Claudia.js is a tool designed to simplify deployment of Node.js projects to AWS Lambda and API Gateway. It automates deployment tasks so you don’t need to worry about introducing errors and configures everything the way you would expect it to be set up out of the box.

According to the official website, Claudia’s primary objective is to help JavaScript developers get started using Lambda microservices easily so they can “focus on solving important business problems instead of dealing with AWS deployment workflows.”

Getting started with Claudia.js

In this section, we’ll walk you through setting up an example Node.js and Express.js app to show Claudia.js in action.

Installing Claudia.js

Claudia.js is available on npm. The simplest way to use Claudia.js is to install it as a global utility:

npm install -g claudia

This will make Claudia.js instantly available to all your projects. Verify that Claudia.js was installed correctly by running the following command:

claudia --version

If the installation works as expected, you’ll see a version number similar to the one below:


Setting up an AWS account

If you don’t already have an AWS account, you’ll need to create one. Amazon has a free tier plan, which will cover creating and testing the Express.js app in Lambda. Follow this guide to set up your AWS account

Configuring AWS access credentials

Now that you have an AWS account, you’ll need to create a new user and give the user programmatic access to your AWS account. Follow the steps outlined below:

  1. Sign in to the AWS Management Console and open the IAM console
  2. In the navigation pane, choose Users
  3. Create a new user, choose the Programmatic access option and follow the rest of the prompt
  4. At the last prompt, you’ll see new user credentials. To view the new access key pair, choose Show. You won’t have access to the secret access key again after this dialog box closes. Your credentials will look something like this:
    • Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  5. Download the credentials as a CSV and store the file in a safe location
  6. Click on the Users tab and select the newly added user
  7. On the Permissions tab, add the following permission:
    • AWSLambdaFullAccess is required for all Claudia.js deployments
    • IAMFullAccess is required if you want Claudia.js to automatically create execution roles for your Lambda function (recommended for beginners)

Now, install the AWS CLI and use it to configure a local profile. Claudia will use this profile to deploy your app to Lambda:

$ aws configure
AWS Access Key ID [None]: Your Access Key ID
AWS Secret Access Key [None]: Your screet key
Default region name [None]: us-east-1
Default output format [None]: json

Generating an Express.js app

Install the Express.js app generator using npm:

npm install express-generator -g

The Express generator is a CLI that allows you to run the express command in your terminal:

express claudia-demo

This creates a new Express project called claudia-demo, which is then placed inside of the claudia-demo directory:

cd claudia-demo

Now install all project dependencies:

npm install

Your app does not need to listen to a TCP port because API Gateway will handle the web requests. You can get rid of the .bin folder created by the Express generator.

Configuring your Express.js app for deployment

The Express.js app will be hosted by a Lambda function, so it needs a handler to send data between the app and the API Gateway. This is where Claudia.js comes in. Claudia uses aws-serverless-express to generate a helper function to interface between API Gateway requests and Express.js requests and responses.

Execute the command below in your project directory. If you have renamed your Express.js application module, replace app with the name of the main Express.js application module:

$ claudia generate-serverless-express-proxy --express-module app

This will add aws-serverless-express to your project dependencies and create the file containing your Lambda function. By default, the file will be called lambda.js.

Deploying to AWS Lambda

Your app is now ready to go live:

claudia create --handler lambda.handler --deploy-proxy-api --region us-east-1

Congratulations! you have your Express.js application running on Lambda.


We have seen that we can run an Express.js app on AWS Lambda, but should every Express application run on Lambda?

Express.js assumes that your application is running on a traditional server and not serverless. Certain operations that work easily in a traditional Express.js server app may not work serverless.

For example, file and image uploads would not work in an Express.js app on Lambda because the app doesn’t have access to a persistent filesystem. Also, WebSocket communication would not work on Lambda because your server doesn’t exist when there are no requests.

Like any tool, the viability of running your Express.js app on AWS Lambda depends on your use case and the unique requirements of your project. I hope this tutorial gives you some insight to help you determine when to use this method.

Get set up with LogRocket's modern error tracking in minutes:

  1. Visit https://logrocket.com/signup/ to get an app ID
  2. Install LogRocket via npm or script tag. LogRocket.init() must be called client-side, not server-side
  3. $ npm i --save logrocket 

    // Code:

    import LogRocket from 'logrocket';
    Add to your HTML:

    <script src="https://cdn.lr-ingest.com/LogRocket.min.js"></script>
    <script>window.LogRocket && window.LogRocket.init('app/id');</script>
  4. (Optional) Install plugins for deeper integrations with your stack:
    • Redux middleware
    • NgRx middleware
    • Vuex plugin
Get started now
Godwin Ekuma I learn so that I can solve problems.

One Reply to “Deploying a serverless API to AWS with Claudia.js”

  1. Why would you need the Claudia.js layer in-between gateway and lambda if you can use gateway and lambda proxy with built in express implementation from AWS?

Leave a Reply