Claudia.js - From Zero to Your First App on AWS

I have been in love with a woman named Claudia for longer than I've been a computer programmer.

Only recently did I discover an amazing project I should have created myself called Claudia.js.

Claudia makes it easy to deploy Node.js projects to AWS Lambda and API Gateway. It automates all the error-prone deployment and configuration tasks, and sets everything up the way JavaScript developers expect out of the box. This means that you can get started with Lambda microservices easily, and focus on solving important business problems instead of dealing with AWS deployment workflows.

To make up for missing such a no-brainer opportunity for a name to use for one of my JavaScript projects, I have decided to use Claudia.js and AWS Lambda as a platform to help my son pursue his interest in programming. Serverless and edge computing are the future, so knowing some AWS and JavaScript will be a good foundation to start with.

The goal of this post is to provide an introduction for going from zero to deploying a Node.js application to AWS Lambda. Claudia.js really makes creating node.js applications, and allowing other people to access them, as easy as can be. That I would rely on it as something somebody with little to no experience programming could use to launch their first application should speak volumes, considering I have also used it professionally to:

power the e-commerce websites of multiple big brands
power extremely high traffic flash sale websites for popular youtube influencers
power event driven workflows for critical applications used by one of the largest car rental companies in the world.

So Claudia.js powerful, like the woman I mentioned. Claudiajs is also easy to work with, unlike that same woman.

Getting Started

What you will need:

Install Visual Studio Code on your computer
Create an AWS Account. You can use the free tier.
Node.js installed on your computer
A lot of patience and time.

If you have never programmed JavaScript before, don't worry. I have been a professional programmer for 20+ years and my first programs were all copied and pasted code I didn't understand when I barely knew the language I was programming in. Before I started, I did have a decent understanding of computers and networking, as well as basic proficiency with the command line.

If you don't know these, and don't have somebody to teach you:

Reach out to me at jon@chicago.com I will be happy to help. I was a straight up nuissance to everyone who knew more than me when I was getting started, so I am obligated to pay it back.
Watch videos on TikTok, Youtube
Find an online course

Having a pre-existing structure that works to begin in will give you a place to explore experiment and learn. That is what I hope to help you accomplish by the end of this post.

You will write some code.
You will use the command line to run a command which publishes your code to AWS.
You will have a URL to put into your web browser and interact with your application.
You will begin to see the difference between a client and a server.
You will begin to see how JavaScript can be used for both of these things.

Before you Begin
Creating your first project
Publishing a version of your program to AWS
Using your application from your phone, ipad, or computer browser.
Running your app locally
Walk through what we built

Before You Begin

Download and Install Visual Studio Code

If you're on windows, here is a youtube tutorial for installing VSCode on Windows.
If you're on Mac, here is a youtube tutorial for installing VSCode on Mac

Install Node.js

If you're on windows, here is a youtube tutorial for installing node.js on windows
If you're on Mac, here is a youtube tutorial for installing node.js on Mac

Setup your AWS Account

If you're a student, you should talk to your adult about what you are doing, and maybe have them help you with this step.

Amazon Web Services works on a pay for what you use model, so if you accidentally give somebody else access to your account they can cost you a lot of money.

There are ways to prevent this, but that would be an entire article. Please proceed with caution on this step.

Follow the steps here to create your AWS Account

You need to create some security credentials, by clicking on the menu on the top right.

Very Important the security keys we're creating here should never be posted online, or shared with anyone. If you're streaming you want to make sure they don't show up on your screen. If somebody gets ahold of these, they can rack up a bill on your account. Hopefully you are using a free tier AWS account, like you can get as a student by applying here

You need to create Access Keys

And store them in your AWS Credentials file.

If you're on windows, that will be in C:\Users\USERNAME\.aws\credentials.

If you're on mac or linux, that will be /home/USERNAME/.aws/credentials or ~/.aws/credentials

You'll want that file to look like, after you've pasted in your values

[default]
access_key_id=ABCDEFG
secret_access_key=HIJKLMNOPQRSTUVWXYZ

Creating Your First Project

The source code for this can be found on github.

Follow these steps

Create a new folder, and open that folder in Visual Studio Code

This folder will be empty at first. That is ok, we are going to start adding files to it.

In VSCode, open a new terminal

Create a package.json file

In the terminal you opened up in VSCode, type the following. ( Don't copy and paste, type everything after the dollar sign. )

$ npm init --yes

Install Claudia.js

$ npm install claudia --save-dev

Claudia.js is software that runs on your computer only, and is used to publish your app to AWS.

When we install it this way, we're installing it as a development dependency.

This means our app doesn't need it to run, but we need it to develop our app.

Claudia API Builder is software that our app runs. So we install it as a normal dependency.

$ npm install claudia-api-builder --save

You'll notice after doing this, our package.json file has the following in it:

{
  "name": "first-claudiajs-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "claudia-api-builder": "^4.1.2"
  },
  "devDependencies": {
    "claudia": "^5.14.0"
  }
}

Create a app.js handler file

Create a new file called app.js and paste the following code into it. Don't worry about what it does yet.

var ApiBuilder = require('claudia-api-builder'),
  api = new ApiBuilder()

module.exports = api

api.post('/hello', function (event) {
  return new api.ApiResponse(
    `
      <html>
        <head>
          <title>My First Claudia.js Project</title>
        </head>
        <body>
          <h1>Hello ${event.post.name}</h1>
        </body>
      </html>
    `,
    {
      'Content-Type': 'text/html',
    }
  )
})

api.get('/', function () {
  return new api.ApiResponse(
    `
      <html>
        <head>
          <title>My First Claudia.js Project</title>
        </head>
        <body>
          <h1>Say Hello</h1>
          <form action="/latest/hello" method="POST">
            <label>What is your name?</label>
            <input type="text" name="name" />
            <input type="submit" value="Say Hello" />
          </form>
        </body>
      </html>
    `,
    {
      'Content-Type': 'text/html',
    }
  )
})

Save that file. You're done. You now have an application that you can publish, or deploy, to AWS and share with your friends.

Testing your app locally

When we're developing real applications, we test them out on our own computers first before publishing them to the real world.

You can run your application on your own computer too.

To do that we need to use a library from npm called claudia-local-api.

This library simulates the way AWS Lambda works, so you can test out your code before releasing it.

To install it, run the following command:

$ npm install claudia-local-api -g

This -g flag says to install it globally, which means it will be available to all of your projects.

Once installed you can run the following command to start your app on your own computer

$ claudia-local-api --api-module app.js

If you open your browser to http://localhost:3000 you should see your application running.

localhost is the name of your own computer on the network. :3000 is the port that the application is listening on.

Nobody but you can access the application that is running this way.

If you want to publish the application to the world, you need to deploy it to AWS.

Publishing your program to AWS

Now we're going to publish our code to AWS.

Inside the Terminal in VSCode, run the following. (Again, type it in, everything after the $.)

$ claudia create --region us-east-1 --api-module app

This code creates an AWS Lambda function inside AWS, as well as an API Gateway resource that is connected to that lambda.

In AWS, API Gateway is responsible for providing you with a URL, and directing anybody who visits that URL to run our code. AWS Lambda is responsible for running our code.

This will create a file called claudia.json that links to the AWS Lambda and API Gateway resources that were created in AWS for you. This file is so that we can later update our code if we make changes to it.

This command will also output a URL for this function.

Wait a minute or two. When you click on this URL you should see:

If you do, congrats, you've launched your first program!

Using your application

Once you have the URL to your application, it is actually live on the internet for everyone to use. You can text or email yourself the URL and open it up in your phone.

What we've launched is a pretty trivial application, but I want to use it to show you an important concept in web development.

Let's go to our application.

Mine, for as long as it is up, can be found here

Your url will be different, hopefully you copy and paste it from the step above.

Walkthrough of what we've built

A web application consists of two major parts. You have the client, and the server.

In our app.js file notice the following block:

api.get('/', function () {
  return new api.ApiResponse(
    `
      <html>
        <head>
          <title>My First Claudia.js Project</title>
        </head>
        <body>
          <h1>Say Hello</h1>
          <form action="/latest/hello" method="POST">
            <label>What is your name?</label>
            <input type="text" name="name" />
            <input type="submit" value="Say Hello" />
          </form>
        </body>
      </html>
    `,
    {
      'Content-Type': 'text/html',
    }
  )
})

This block is saying, when a user visits the root of the application, return some HTML.

<html>
  <head>
    <title>My First Claudia.js Project</title>
  </head>
  <body>
    <h1>Say Hello</h1>
    <form action="/latest/hello" method="POST">
      <label>What is your name?</label>
      <input type="text" name="name" />
      <input type="submit" value="Say Hello" />
    </form>
  </body>
</html>

The web browser will turn this HTML into a page, with an input the user can type in, and a button they can click.

This code is The Client Side of our application.

This code contains an HTML Form tag

<form action="/latest/hello" method="POST">
  <label>What is your name?</label>
  <input type="text" name="name" />
  <input type="submit" value="Say Hello" />
</form>

Form tags are for communicating back to the server.

Notice it has a POST method, and a /latest/hello action.

When the user clicks the submit button, our web browser will make a POST style request to that URL.

In the app.js file, notice this code:

api.post('/hello', function (event) {
  return new api.ApiResponse(
    `
      <html>
        <head>
          <title>My First Claudia.js Project</title>
        </head>
        <body>
          <h1>Hello ${event.post.name}</h1>
        </body>
      </html>
    `,
    {
      'Content-Type': 'text/html',
    }
  )
})

This code is the The Server Side of our application. It is saying, if a web browser makes a POST request to the /hello URL, run this code.

This code is taking whatever the user typed in the input field, and displaying HTML which says hello to that person.

Again, this is pretty useless, but it shows you the core of what web application programming is about.

Applications which run on the client, talking to a server.

This application shows the core model of web applications everywhere.

Present the user with a form and a button
Send information to the server when they click that button
Present the user with a new page that does something with this information

A real server would be more advanced, and do more complicated things. A lot of things you can do on the client or in the browser itself, without needing a server. The code would need to be organized differently, for a more complex application. These are all things you will need to learn about to build whatever application you are imagining.

Conclusion

By following this tutorial, you were able to write code, change code, send it to AWS, and share a URL with somebody who wants to use that code. You did it using tools that professional software developers use every day and make great money with.

That's a big accomplishment! You have a lot more to learn, but that is a sample of what real players do every day.

Cleanup

You should destroy the application you just deployed when you're done, if you don't want to worry about getting charged money.

To do that:

$ claudia destroy

If you're done using AWS for now, you can also delete the access keys you created when you started. This way nobody can get ahold of them and use your account.