Forem: Al Madireddy

The "Serverless" Backend MVP

Al Madireddy — Mon, 04 Nov 2019 18:11:47 +0000

Welcome to part 3! If you've made it this far, you must be itching to write some code already. Not to worry, because by the end of this post, you will have written and deployed the Node.js backend for our app.

Routes and REST API's, whom?

Before we get into the code itself, lets take a minute to deconstruct exactly what we are writing.

Our backend application will do one task: send our form contents in an email to (y)our inbox.

This entails a couple of steps: take input over the network, validate it, and then trigger an email send. Simple enough, but what exactly does it mean to take input over the network and how is it accomplished? The answer to that will become apparent through the code we are going to write; that's why I am writing this tutorial!

Communicating over the network: JSON

The one thing that we do need to know is the concept of using JSON to encode useful information.

JSON is a key-value pair system that can be used to store data in a very human-readable and organized way. JSON stands for "Java*Script **Object **N*otation because the syntax is very similar to how objects are defined in Javascript:

// This is Javascript so we have comments

let name = {
    first: "Luke",
    last: "Skywalker"
};
// name is now a variable pointing to an "object"

let firstName = name.first // firstName == "Luke" 
let lastName = name["last"] // subscript notation also works. Useful if you have spaces in the key.

JSON (doesn't support comments):

{
    "name": {
        "first": "Luke",
        "last": "Skywalker"
    }
}

JSON is a string representation of a JavaScript object (or python's dictionary or Java's HashMap, etc).

One important note is every key in the JSON is wrapped in double quotes, and in Javascript, it doesn't need to be. An object is denoted with a set of braces { ... } so in this case, the key name maps to a value of type object which itself contains two keys, first and last, within it. Notice how the example in it's entirety is contained within an object.

JSON supports numbers, strings, arrays, booleans, null, and other objects as values, but only strings as keys.

So what?

Remember in Part 1 how our code sent the text "hello there" over the network to the browser? Now, instead of plain text, we are going to be sending JSON.

If we wanted to encode some data from an app into the text we were sending, such as certain variables' values, we could easily have made up a data to text encoding specific to our app.

For example, if our program had a firstname and lastname variable in memory, we can make up an encoding for a "name" which looks like this: name - [first: <Luke> last: <Skywalker>];

Everytime we wanted to encode those two variables in order to write to a text file or send over the network from our program, we can output it like that. Your app which reads from the file or recieves that input over the network can decode it accordingly and place the values into its own variables.

This solves the problem just fine, but what if you wanted to open up your app for other people to use for their names? What if you were working with other developers on your team and all your apps needed to work together? Now, you would have to explain how to decode the messages from the text encoding into a first and last name that their program could use.

To alleviate this, the industry decided to use JSON. It's a standardized specification with specific rules that apps use to encode data. JSON encoding and decoding tools are built into virtually every useful language and therefore is fairly easy to work with. It also helps that is is a good compromise between machine and human readablility: you can just look at the key-value pairs to see the information and understand it.

So, in order to communicate across the internet, apps and services can just send JSON-encoded data back and forth.

Here is official website you can learn more about the JSON format.

So what's an API?

API stands for "Application Programming Interface." Compare this to a GUI, or "graphical user interface." The same semantics apply: An API is a way for your application or program to interface with other applications or programs. But what does that mean?

Well, think about Google Maps. They have a lot of code, science, math, and geospacial algorithms that make up the magical functionality of Google Maps. Google naturally wants to sell this functionality and make money from developers wanting to get routing in their applications.

However, they can't just give developers access to the code, because now other developers know the code and secrets. Doing this also means there is no way for Google to limit what they can do.

So, they run the Google Maps "app" on a server, and then expose an API to the outside world. Other developers' applications can interface with the Google Maps API.

Developers can make a request from their code that goes to a specific Google Maps URL (like our browser request to our hello world app's URL, could be maps.google.com/get-route or something). They'll encode the starting location and ending locations into that request and the Google Maps API will recieve this request. It will run its magic and send back a response with the route encoded as a list of coordinates in JSON format.

This way, developers' applications can interface with the Google Maps application programmatically, sending data back and forth. This is exactly how we are going to be using the SendGrid API to send emails: our Node.js app will request an email send, and SendGrid will send it and respond with a success.

This JSON API pattern is also used internally within an application. The best example is what we are writing here:

Our front-end will be a React application that will send a request to our back-end that contains the contents of the form encoded in JSON format. Our back-end sees this, validates, sends email, and responds with a success if SendGrid worked.

JSON API's are organized into specific routes. Taking whatever URL we get generated from Now's system as the "base," we would define a route to send emails maybe at /sendMail. Sending a request to that route would run the email sending code.

Let's get started

To begin, set up a folder for your project on your computer. Mine will be called mailer and will live in the same folder as most of my other software projects.

Open that folder up in your favorite code editor (again, VS Code or bust).

Create a file called now.json in that folder, and also a new folder called api. Create a file inside the api folder called index.js. This should be very much the same as what you did in the first part of the tutorial.

Your folder structure should look the same as before, like this:

tutorial/
  |- hello-world/
  |- mailer/
     |- now.json
     |- api/
        |- index.js

(If you haven't done the first part of the tutorial, you won't have the hello-world folder.

Now in your terminal, cd into the mailer folder, and run:

$ npm init -y

This will generate a file called package.json with the following contents:

{
  "name": "mailer",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

This is more JSON (see, its everywhere).

This file contains metadata about your project, and is useful for portability, since the list of your project's libraries also gets stored in this file when something is installed. You can open it up in VS Code and fill in the author and keyword tags if you'd like.

Copy in the following into now.json as well, similar to before:

{
    "version": 2
}

MVP - Minimum Viable Product

It's time to define the MVP and get it deployed. For us, the MVP for the backend will be a deployed application that responds with a JSON "hello world" to a request. All other features can be added on one-by-one iteratively on top of that.

Look in Part 2 for the definition of an MVP.

So let's get that MVP deployed. Create our function similar to Part 1 that responds to a request with "Hello World":

module.exports = (req, res) => {
  let response = {
    message: "Hello World" 
  };

  res.json(response);
}

Here, you can see some small differences from the first part of the tutorial: instead of setting the status and passing in a string to send(), we are calling res's json() function and passing in an object to it.

To get a small explanation of what the module.exports means as well as the fat-arrow => function syntax, checkout Part 1.

The next step to finish our MVP is to deploy this:

$ now

This should run, produce some output, part of which is the URL at which this function is deployed. My URL as per the logs is tutorial-mailer.almadireddy.now.sh. Your's would probably be "mailer.[username].now.sh" but mine starts with tutorial-mailer because I wanted it set up that way for organizational purposes. You can look up how to modify your ZEIT project name.

Like before, if you access that URL with /api in your browser, you should be able to see the JSON that you sent from the app.

Congrats! The MVP is complete!

Setting up Continuous Deployment

One cool thing about ZEIT Now is that it allows us to easily set up Continuous Deployment with Github. You can attach a Github repository to a ZEIT project, and ZEIT will automatically deploy new versions as the selected branch on Github is updated.

This isn't intended to be a tutorial on git and github, so look that up on your own if you haven't used it before. But, because I'm nice, I'll show the commands I use to get the project up on my own github.

Let's set that up now. First, we need to initialize git in our project folder. Again in the mailer folder, run the following command:

$ git init

You'll see an output message along the lines of:

Initialized empty Git repository in [..]/mailer/.git/

Like the message says, this will have created a hidden .git folder inside your project. This folder contains all the information that git needs to work properly. Don't mess with it.

Create a new file called .gitignore. This file is a listing of file and folder names that should be ignored by git.

Add the following to that file:

node_modules/
.env

The node_modules folder and .env file don't exist yet, but they will in later parts of the tutorial.

Now, create another file called README.md. This is a Markdown file, and you can look up how to use Markdown on your own. Add some information to this file saying what the project is, or whatever you want.

Save both those files, and commit:

$ git add .
$ git commit -m 'initial commit'

Now, we need to set up a repository on our Github account. Go into Github, click the button for a new repository, name it, and mark as private if you want. Make sure the the checkbox for Initialize this repository with a README is unchecked, since we already have one. Make sure the Add .gitignore and Add a license dropdowns are the default None selection. Hit the green Create repository button.

You'll be brought to an empty repository page with some instructions. We are interested in the section that says …or push an existing repository from the command line. Run those two commands in the project folder to get your code uploaded.

If everything went well, you'll see output with the last line being something along the lines of Branch 'master' set up to track remote branch 'master' from 'origin'. Reload the github page, and you should see your files as well as the contents of the README.

Now, we can set up the connection between our Github and ZEIT on ZEIT's website.

Head to zeit.co/dashboard and click on the mailer project. Use the "GIT INTEGRATION" section to select and connect your Github repo. Depending on how you signed into ZEIT, it may take you into a authorization flow to connect your Github account so ZEIT can see your repositories.

An Important Aside: HTTP Verbs

HTTP verbs are a concept that will become pretty important in the next part. The most common/important ones are:

POST
GET
PUT
PATCH
DELETE

These are also called "HTTP methods" sometimes, especially in code. These verbs classify the type of request made. For example there can be a GET request to an endpoint which does one thing, or a POST request to an endpoint which does another. Every time we've been accessing a URL through the browser, we've been making a GET request.

To see information about our network requests, open up the Developer Tools in your browser and go to the Network tab. Do this on your app's ZEIT URL and hit Refresh. You'll be able to see information for your /api request if you click on it from the list of requests.

When designing an API, each of the HTTP verbs should correspond to the proper action from Create, Read, Update, Delete (CRUD). This is a common practice, and makes it easier to understand. There's nothing stopping you from doing something else, except convention.

This will be important for us, because we will make our our app trigger email sends only with a POST request. This is semantically more correct, since we are "creating" an email message or email-send action.

Here is a great summarization with a little more detail about HTTP verbs. Note the distinction for the two Update verbs, PATCH and PUT.

Coming up Next

With that, I think it's a good place to end Part 3. Feel free to mess around with the code and do cool things before I finish the next part, where we will finish up the backend with all the features we need to recieve input and send email.

Also, download Postman and look into using it to send requests to your deployed application. You can change the type of request being made using Postman, and you can look into how to detect the request method being used in Node.js.

Designing A Web App Architecture

Al Madireddy — Fri, 13 Sep 2019 16:21:15 +0000

The Project

Now that we've installed everything we need to in order to create a service and deploy it online, we're going to design and create the main project that will teach you everything I promised to teach you.

Let's go over what we will actually be building. Because I am fed up with coding interview questions, in-class examples, and coding assignments that have no point, I won't be contriving a project for you. Instead, we are going to be building something actually useful (i.e I needed to use it): A web app that shows the user a "Contact Form" and emails the things that they filled out to the make believe company's email. (Okay it's a little contrived, but in my case, I actually had a company I was making this for)

Here's what it'll look like:

This is a screenshot from my company's website (Have a web project? Contact us!). Anyone interested in connecting with us would ideally fill out this form, not be a robot, click submit, and see a confirmation message that their message was sent. Then, we see that message in our inbox.

Why not just put an email for them to contact you?

Because then our email gets picked up by web scrapers and we get spam. This hides the email, and lets us change it internally.

Architecture

I was really into architecting actual houses and things in high school before I switched to code. But that's irrelevant.

To get started with creating an app like this, we need several moving components. Let's think about what they are and then translate that into a plan for our software.

The Front End

To begin, the most obvious thing we need is the User Interface. This is what the user will be able to see and interact with, and we need to make sure it's nice, pretty, and usable. This is the part of the application we call the front-end. It's on the "front" of the application because that's what the user sees and interacts with. This front-end is an app in itself, deployed to the internet and generally accessible by the outside world by going to a URL.

If the application was a car, then the front-end would be the steering wheel, pedals, buttons, gauges, interior detailing, leather on the seats, etc. It's the pretty part that works well and is responsive to the users' demands.

Aside: It's not too hard to take a simple prototype of something and make it look a little nice with CSS. We'll do a little bit in this project, but I suggest reading some articles on CSS and designing websites with it. Here's a great starting point: Learn CSS in 5 minutes

A lot of times, a little CSS in your prototype can mean the difference between a client/boss accepting your idea or rejecting it on the basis of ugliness and "no one will like it."

The Back End

The next thing we need is a way to send what they filled out to our email address. Luckily, the solution to this problem is basically this whole tutorial. Here's the plan: we're going to send the data they filled out on the contact form through the pipes that make up the internet, to an app that we write in Node.js. This app needs to be live so that we are able to access this app at a URL. Our front-end code can send requests to that URL and data along with those requests. (Hence the previous part of the tutorial).

Our back-end app will accept the data over the internet, make sure it's all nice and safe (for the most part) and then actually send the email. Because sending and receiving emails is a whole big task in itself, we will be using a service called SendGrid to send the email for us.

This is intentional because I don't want to write an email service, and using this will let me show how to use a third-party library in our code.

I'm actually appalled that it takes students (at least in the set of classes I took) until their third year upper levels to learn that it's okay for people to use other peoples' code not not get points taken off for using a library. smh.

SendGrid is a service which makes sure that the emails get delivered, provides tracking for emails, tracks whether they were delivered, and more. Our back-end will talk to the SendGrid service in a similar fashion to how our front-end talks to our back-end. (Sending data over the internet).

You've lost me

Looking at this huge wall of text, I'm lost too. So I'm going to draw a picture for you. Because no architecture is truly designed until there's a drawing with boxes and lines.

                                           +------------+
                                           |            |
+-------------------------+                |  SendGrid  |
|                         <----------------+ (External) |
|     Node.js Backend     +---------------->            +-----------+
|                         |                +------------+           |
+-------^-----------------+                                         |
        ||                                                   +------v------+
        ||                                                   |             |
        ||                                                   |  Our Inbox  |
        ||                                                   |             |
        ||                                                   +-------------+
        ||
        ||
        ||
        ||
        ||
        ||          +-----------------------+
        |----------->                       |
        +-----------+     React Frontend    |
                    |                       |
                    +----------^------------+
                               ||
                               ||
                               ||
                     +----------v----------+
                     |                     |
                     |   User's Computer   |
                     |                     |
                     +---------------------+

(ASCII art because we are c o o l )

Each box is its own application/service, and each connector is a pipeline of communication along which data is sent. These boxes are the "moving parts" that make up our app.

To summarize:

the user uses their computer to send requests to the front-end, filling out a form.
The front-end sends data in a request to the back-end, and if input is safe, the back-end accepts, and sends a request to SendGrid.
If the email was sent, SendGrid sends back a "Success" response (remember that 200 from earlier?).
The back-end sees this success and sends a "Success" response to the front-end.
The front-end in turn notifies the user that their message was sent to the company. If anything goes wrong, the back-end would be sending non-success messages (of many possible varieties like 401, 404, 500, etc) and the user will see an error message telling them to try again.

How are we supposed to know to set it up like this?

This is the aspect of the job that I really struggled with when I was learning all these for the first time. The answer is you aren't, and you probably never will right off the bat. I called this section "Designing our web app architecture" because that's exactly what we are doing. Designing a solution that does what we need to. Like any design, we put thought into it, explore our options, change aspects as we get more information and as we plan for contingencies and future features.

Some common Architecture patterns

However, there are some starting points. There are several architecture patterns that are used in industry and we will talk about two of them here. For one, the architecture we are using here with a single front-end, a single back-end, and that's all we need. After all, by modifying the backend code, we can do much more than the singular task of sending emails. We could add login/logout so users would have to be logged in to send messages. We could add a blogging feature so that users can publish posts and have others see. Suddenly, we have a blogging platform with a technical support contact system.

Monoliths

The architecture we have designed follows the the Monolith pattern. This is because the back-end is a "Monolith" as in it does everything our app needs to in one place, in one codebase. All functionality we might build in would be built into this back-end.

For a long, long while, this is how apps were built. It was simple, it could be scalable, and it was easy to follow and reason about. However, there are some problems with this that you might already be able to see.

If everything is in one codebase, adding or changing something in one place in the code, such as the login/logout authentication logic, might inadvertently break something completely irrelevant that is somehow dependent on the authentication logic.

To contrive an example, our hypothetical blogging system might be using a variable declared in the auth system to figure out who to set as the publishing author in a blog post, and that variable might have gotten refactored away into the ether in the last code merge. Now, the blogging system is broken, and the blogging platform team has to spend time fixing something that could have been avoided. To avoid this brings us to the next architecture pattern:

Microservices (important!!)

If you've been reading developer blogs, looking at software headlines, or been in a meeting with someone obsessed with buzzwords, you might have heard about microservices. A microservice is just that, a small service. Our back-end that we just designed into our application does one task: take in contact form content, and trigger an email send. Now imagine that all functionality in our application is broken down into components like that based on the task they achieve, and written into separate codebases and deployed separately, and you've arrived at a Microservice Architecture.

Your authentication system might be its own app, deployed to a large, powerful server on AWS, because it needs to handle traffic from a lot of people logging in and out.

Your blogging system would be its own service, deployed and scaled on an even more powerful server, with several copies of the app running to handle the mega traffic from everyone, including trial users who don't need to log in.

Your contact form (from this tutorial) would be it's own thing, deployed to a smaller, less expensive server, since it barely sees any traffic compared to the other components.

Each app has its own concerns that it's worried about, and as long as the team works to keep the data sent between the services consistent, a team could completely rewrite one component and redeploy it, even in a wholly different language, and the system as a whole would still work uninterrupted.

That is the ideal, anyway, but like in everything, the real world (read: real teams) isn't perfect so communication and knowledge share remain key in keeping everything working.

Microservices are the new more-and-more common method of doing this, and a lot of companies are making a transition from their legacy systems into this. (This usually also coincides with a move from mainframes and data centers into cloud service providers like Amazon Web Services or Google Cloud Platform. These providers make things like microservices easy to manage.)

Aside: Microservices, their differences and similarities to Monoliths, and how to design one, is great knowledge to have and is very impressive to recruiters if you're looking for internships while in college.

Here is the essential talk on microservices (in my opinion).

Your homework to close out this part of the tutorial is to watch that video. I even bolded it so you'll see it.

Other options?

Monoliths and Microservices aren't the only way to do things. Feel free to come up with your own completely new and better paradigm and then write a blog post and send it to me so I can learn about it.

Other architecture patterns include event-driven architecture, which is pretty cool, Sagas, which I don't really know about. I'd again suggest googling around to learn.

The Concept of an MVP

When developing a new application, script, or anything, it's good to start with an "MVP" or "Minimum Viable Product." (Note: this is all about the way I personally use "MVP" in both meaning and practice, and company or "official" convention may be slightly different)

A minimum viable product is simply that. A small, rudimentary proof-of-concept or initial feature-set of whatever you are building. It is seen usually as the first step and takes less than a day to complete, leaving time for discussion with your team. In practice, I usually use it as a term to define what it means to "start" working on the application. For this project, it would mean setting up an empty React project, making the deployment that we made in Part 1, and achieving communication between the two.

You can start with an MVP, then work in an iterative way to get to where you want to be. You break down your goals into small steps, then boil those steps into easily digestible tasks, then split those tasks into individual action items you can assign to people to complete. Completing each one slowly adds to the product, slowly but surely completing the application as each task is implemented and merged into the initial codebase from the MVP.

This is a great way to get some scope, and lose the fear of starting when you are faced with creating something complicated or "big." After all, by implementing the MVP, you already have code pushed, and you are simply adding things one by one.

Continuous Deployment

This pattern of having an MVP upon which all future features are added to will also help us practice Continuous Deployment. You may have seen the term "CI/CD" floating around, which stands for Continuous Integration and Continuous Deployment. Combined, this is the practice of merging developers' code changes into the master several times throughout the day (Integration) and also deploying new versions of the code live as those changes are made (Deployment).

This is a useful practice for us, because as we complete features one by one, we can push each one live as they are completed. In effect, this means that at any stage during development, there is a live working version of the application, and it is (theoretically) never broken. This is common practice nowadays and there are many tools to automatically run tests, deploy, and notify developers on errors as changes are pushed into the codebase. Here is an in depth article from Atlassian explaining the concept in more detail.

Part 3 of this tutorial will be creating an MVP for our app, and also a small (lengthy) aside to explain some more fundamentals that will help make Parts 4 and 5 make more sense. We will then go into Parts 4 and 5, building the back-end and front-end respectively.

Node.js, ZEIT Now, and Deploying

Al Madireddy — Wed, 11 Sep 2019 21:56:03 +0000

Have a cool app idea, but have no idea where to start in learning all the things one needs to know to create a modern, connected app for the web or smartphone?

I was in the same place two years ago, attending Computer Science classes for the first time at university. I felt lost as my friends and classmates seemed to be making all sorts of cool, game-changing apps while I was stuck in class turning in fancy for loops that I spent all night on.

This tutorial is intended for everyone wanting to get an introduction to all the moving pieces of what makes up a modern app. We will walk through designing the architecture of the application, what exactly the back- and the front-ends are, how to write them, and how to deploy them.

Prerequisites

You should have a working understanding of Javascript or a similar-looking language like Java or C++. I won't explain syntax and everything, but will try to provide useful links and some explanation where I think it's important.

Other than that, there isn't much else you need to know beforehand. If you don't know something mentioned here, Google is your friend.

Aside: I think being able to Google efficiently is one of the most important skills a software engineer can have. Every time something goes wrong while you're working through this tutorial, copy the error message and google it! No error message? Google what is going wrong in plain english! More often than not, typing out what's going wrong will let you distill the problem in your head and arrive at the solution. (If this happens a lot, it's time to invest in a rubber duck).

The tech you'll learn

In this series, we are going to learn how to write a front-end using React, a front-end javascript framework, how to write a back-end service with Node.js using a framework called Express, and how to deploy it to ZEIT Now, a serverless deployment platform. To finish, we will explore how writing this project can be used to pick up new languages for the backend easily. We'll walk through a re-write of the backend using Go to demonstrate. By the end, you'll have the basic knowledge and skills to architect and write a web service to support your app or website. Along the way, we will pick up some useful bash skills as well.

Enough talk, let's go!

To start, let's install Node and the Zeit CLI, and deploy a small hello world!

Installing Node

If you have a preferred version of Node already installed, you can skip this section.

Head over to the node.js website and download the LTS version, which at the time of this writing is 10.16.3. Once downloaded and installed, run the following command in the Terminal (or the command line on windows:

$ node -v

Note: Throughout this tutorial, $ is used to identify the Terminal prompt, and not a part of the command.

You should see your version number printed to the screen, confirming a successful install. If it fails, google the error, debug, and fix the installation.

After that works, run

$ npm -v

to confirm the version of npm. If it prompts you to update, do what it says and run

$ npm install -g npm

to update to the latest version.

Node? Who dis?

Node.js is a "javascript runtime environment" for the desktop. Let's break that down.

Javascript is a language created mainly for the browser, and runs entirely in the browser. It's used to add interactivity and usefulness to HTML sites, and can do a lot of cool things.

Go ahead and hit the F12 key to open up the browser's console. This is a useful debug tool that allows developers to run javascript commands in the browser. Try typing in any Javascript you know, or just some math like 1 + 2 and you should see it tell you the answer.

To make this happen, Google wrote a Javascript engine that is built into Chrome called "V8." This engine is responsible for taking Javascript input, parsing it, and running it. (This is all very high level so I'd recommend reading better articles about it if you are interested.)

This engine is open-source, and is available to read about at v8.dev. In 2009, a guy named Ryan Dahl took this open source Javascript engine, and built it into an application called Node.js, which is able to take in Javascript files and run it on computers outside the browser. If you've used python, this isn't too different from how python run files with something like $ python file.py. The only difference is that you're using the Javascript language instead of python.

npm

npm is a package manager for node. It doesn't stand for "Node Package Manager," apparently, and doesn't have a meaning, but you can go to the npm website to see all the things "npm" could stand for.

Anyway, npm allows us to install "packages" which can contain libraries, utilities, and apps that we can take advantage of to extend the functionality of our application. A lot of packages are more or less industry standards, and we can use those to avoid wasting time reinventing the wheel.

Installing the ZEIT CLI

One of the applications we will install through npm is the ZEIT Now CLI.

Aside: A CLI is a "Command Line Interface" which, as you can probably guess, is a way to use an application or service through the command line. This is kind of like how a GUI (Graphical User Interface) is a way to use an application through "Graphics" i.e. your screen.

This is an open source application, so you can look at its code and usage details on its Github repo. This application allows us to login to and deploy to the ZEIT serverless service through the command line. This is a common thing for many utilities and apps that are used in the industry, so it's good to get used to it now. Plus, using the terminal will make you look cool and you will become the pride of your family. (Not really, but maybe)

We will install Now from npm, by running the npm install command. You can look in the Now README on Github to see what the package is called in the npm registry, which surprisingly is just "now." Use

$ npm install -g now

to install it. Before we use it, let's head over to zeit.co and create an account. In my opinion, their free tier is amazingly useful, so you'll be able to keep using this account after this tutorial.

Once the account setup is finished, head back to the terminal and run

$ now login

which will let you login to the CLI and use your account to do things.

No magic: breaking down the npm install command

Before we continue, let's take a minute to look at the npm install command we just ran. Right now, it seems a bit magical that the command was typed in and then stuff happened and now there's a new app on your computer. Generally speaking, whenever we come across things with a bit of "magic" about them, we should look into exactly what's going on so that we have an understanding of the internals. When something breaks, this knowledge is really helpful in fixing problems quickly. Then, we can go back to the magic.

To take out the magic from all these command we ran and will run in the future, let's break down what that command is doing to learn the basics of using the terminal. If you're good with the terminal and how it works, skip this section.

The npm is the name of the program you want to run, and runs the npm executable that came with the node.js install.

The second thing we type in is install, a command that is available in the program. In this case, install tells npm that we want to install something and that we are going to pass in the name of the package we want to install.

The next thing we pass in isn't the name though, it's -g. This is called a "switch" - it is something that either exists or doesn't in the command, and are usually optional. This one stands for "global" and you can use the corresponding long-form version of the switch by replacing it with --global.

Aside: Notice that long-form starts with two dashes instead of one and starts with the same letter as the short-form. This is a common practice across 99% of all unix/linux command line applications. It's easier to type -g in the terminal, and you definitely should, but in scripts and other situations where you only write the command once, you use the long-form --global to increase readability.

Switches in the commands allow users to specify options and turn on/off features in programs, and are what allow the command line to be an "interface"

The -g switch tells npm to install the package globally on your computer. This allows you to use the installed package from anywhere in your file system, which makes sense for this situation, since you might want to use Now to deploy applications that are stored in various places on your computer.

The last part of the command is now which is the name of the ZEIT Now package on the npm registry. Sometimes these are not so obvious and you should look at the docs or npm page of whichever package you want to install to get the right command. (Look on the top right part of the npm page for a copy-paste-able command.)

Deploy a thing!

Now, you should have the basic necessities installed in order to write and deploy a node.js service to Now. So to close out this section, let's do just that.

Open up your favorite code editor (if it isn't VS Code you're wrong).

Using the file explorer (if you have time, look into doing it with the command line to be cool and learn to do things quicker), create a folder to hold your files for this tutorial somewhere on your computer. For example, mine is in Documents/GreatestTutorial. Create another folder inside that called hello-world.

Make sure your folder names do not contain any spaces, all the way through the path. This makes it easier to work with the command line.

Organizing your code into folders is important, since that separates apps' configurations, libraries, and code and prevents overlap. It's possible to write three different python apps, a Go utility, and a Node.js web-app all in the same folder, but that sounds like a nightmare to work with.

Now, open that folder in VS Code (or your lesser editor of choice) so that we can get started writing files.

Create a file called now.json. Then, create another folder beside that called api/ and create a new file inside the api/ folder called index.js.

Your folder structure should look like this

tutorial/
  |- hello-world/
     |- now.json
     |- api/
        |- index.js

In the index.js, type in the following code: (Type, don't copy/paste)

module.exports = (req, res) => {
  res.status(200).send("hello there!");
}

We will go over what this code is doing below in the next section, but for now, let's continue.

Open up now.json and type in the following:

{
  "version": 2
}

This simply defines a version number, which ZEIT uses to know which version of its platform we want to use. (We will always use v2, the latest and greatest from ZEIT).

Now, go back to the terminal, change the working directory to be in the hello-world folder, and run

$ now

You should see it run and output something similar to this:

> Deploying ~/Documents/tutorial/hello-world under almadireddy
> Using project hello-world
> https://hello-world-3bonj1wv9.now.sh [v2] [951ms]
> Ready! Deployed to https://hello-world.almadireddy.now.sh [in clipboard] [3s]

The last line which says Ready! is important. Copy that URL (mine is live, go ahead and try if you aren't running this on your computer), and open it in your favorite browser with /api appended. So for example, I would open https://hello-world.almadireddy.now.sh/api. You should see something like this:

Congrats! You've just written and deployed a service using Node.js!

Breaking down the code

Let's break down what our code is actually doing. The first line begins with module.exports =. This is a node.js feature that allows programmers to define the parts of your code to "export." Exported objects, functions, and variables can be used in other files by importing the file that has the module.exports defined. We set our module.exports to be equal to the next part:

(req, res) => {
  res.status(200).send("hello there!");
}

This is a Javascript function definition with the arrow syntax. To explain, the following two function definitions are equivalent:

function add(x, y) {
  return x+y;
}

add(1, 3); // returns 4

and

let add = (x, y) => {
  return x+y;
}

add(1, 3); // returns 4

In the first example, the function definition names the function add, in the second, we give the function a name by assigning it to a variable. In our app, we have no explicit name, we just set it to the module.exports variable. This way, the function is exported so ZEIT's system can import and run it for us.

Here is a great read on the differences, cosmetic and otherwise (and there are significant differences that go beyond cosmetics). ES5 functions vs. ES6 ‘fat arrow’ functions

Our function takes in two parameters, req and res. When we call now and deploy it, ZEIT will listen for requests at the auto-generated URL, and call our function and pass in the two parameters whenever there is a request to that url. We made this request by going to the url in the browser, causing ZEIT to fill in the params, and run the code. Because you are defining the function, you can call req and res whatever you want. I sometimes use request and response since I have auto complete in VS Code, and that makes the code more readable. It also follows with the information we get access to in those parameters.

Zeit will pass in information about the request - such as the parameters in the URL that were specified - to the first parameter of the function. This is why we name it req or request. We can add information about the response to the second parameter by calling functions such as send or status functions on that parameter, which is why we name it res or response.

In our function, we are calling the status() function, and passing in 200, which signifies a success. This is a HTTP Response Code, and we will go over those briefly in one of the next sections. This functionality is useful since if something goes wrong in our function, we can let the caller know with a status code that something went wrong. As the server, we control what response is sent, so it's our responsibility to send useful information. Sending a 200 allows our browser to treat it as a successful response.

An example of a different status code is 401 which is "Unauthorized." This can be used in situations where the user is trying to access something but they aren't signed in. It's up to the developer to choose the proper codes and there are conventions you can look up to find out about them.

Then, we chain a call to send() which is a function that sends whatever you pass into the function back to the requestor (our browser in this example). In our case, we are passing in the string "hello there!". Our response could be anything: an HTML file, an image, a JSON file, or just a string. Using these conventions, we are mapping a request to a response, and that's the basis of all web servers.

Coming up

In the next part of this tutorial, we will go over designing and architecting our project. This is an important step in making modern software, and can inform a lot of programming down the line. We will get a high level view of all the moving pieces and the considerations we need to make. We will go over what it means to be "serverless," as I've used that term many times to describe ZEIT already without explaining it, and also download and install Postman which you can get a head start on right now.