The JavaScript ecosystem is changing so fast that it can be overwhelming to pick the best tools to use. To solve this problem, in this article, I’m going to walk you through how to set up a front-end project from scratch.

We'll cover things like must-have editor extensions, adding JavaScript libraries to your project, why you'll use Node.js even if you want to do front-end development, and setting up an application bundler that will generate a live preview as you code in your browser.

You can also watch this article as a video on YouTube. Let's dive in.

Table of Contents

1. How to Choose a Code Editor

2. How to Auto-format Your Code in VS Code

3. Why Do You Need Node for a Front-End Project?

4. How to Run Your Project

5. How to Add Libraries to Your JavaScript Project

6. How to Get Coding Tips While You Code

7. Initialize a Project with Vite

8. Summary

How to Choose a Code Editor

Let’s start with the foundations. As a web developer, you mostly edit text, so you need a good editor. So which one should you use?

Picking an editor is highly based on personal preference, as most editors have very similar features.

If you don’t have a personal preference, I highly recommend VS Code. Lately, it has become the de facto standard editor for web development.

One of the greatest features of all the mainstream editors is that you can add extensions to them. Let’s walk through two extensions that are must-haves.

How to Auto-format Your Code in VS Code

Prettier is an extension that makes your code more readable and more consistent.

Let’s say you copy-pasted some code, and it’s hard to read. The tabulation is off, a line is too long, and so on. Then you just save the file, and magically, everything looks as it should be.

This is what Prettier does. It formats the code based on best practices. It doesn't just fix tabulation and wrap the lines. It also adds parentheses to improve code readability, makes sure you are consistent with quotation marks, and many more.

To make it work in VS Code, we must first install the Prettier extension. To do so, go to the extensions panel in VS Code, search for Prettier, and then install it.

Installing this extension doesn't format your files automatically on save by default. The default behavior is that once you install this extension, you can right-click within a file and select Format Document. You can also select part of a file and choose Format Selection.

The first time you do this, you need to select the default formatter. VS Code already has a formatter, but it isn’t as powerful as Prettier. Now that you have two formatters, you have to let VS Code know that you want to use Prettier for formatting in the future.

If you wish to auto-format your files when you save them, you need to change the settings. Go to Settings in your VS Code preferences and search for the Format on Save option. By default, this is false, so make sure that you tick this checkbox. With this, Prettier formats your files every time you save them.

Formatting can be controversial, though. I highly recommend the default settings, especially for beginners. But if you prefer a different style, you can customize things.

You can indicate with comments to ignore specific lines and create a config file to list your preferences.

In the root folder of your project, you can create a file called .prettierrc and add a few options. A typical option could be if you prefer single quotes instead of double quotes in your files. Or if you don't want to have semi-colons at the end of your lines.

With this configuration, you will have a different format once you save your files.

{
  "singleQuote": true,
  "semi": false
}

There are many more options, of course. If you want to dig deeper, check out Prettier's documentation.

Why Do You Need Node for a Front-End Project?

Before we get to the second must-have extension, we need to set up a few other things. First, we need to talk about Node.js. What is Node, and why do you need it even if you work as a front-end developer?

Node is often associated with backend development, but that's not its only job. Node is a JavaScript runtime – this means it runs JavaScript files outside of the browser.

There are two ways of running JavaScript code. You can either have it as part of a website and run the entire website in a browser, or run only the Javascript file with a runtime like Node.

In the example below, we have a very simple Javascript file that prints "Hello World" to the console. If we have Node installed, we can go to the terminal, navigate to the folder where this file is, and then run it with Node like this. You can see that the file was executed, and the result is in the console.

That's what Node really is: a tool that runs JavaScript files on their own.

JavaScript mostly behaves the same way in both environments. But there are also differences in what JavaScript can do in a browser vs when it runs with Node.

For instance, when running in the browser, JavaScript can access and modify HTML elements. That's the main point of having JavaScript in the first place.

In Node, there's no HTML file. JavaScript runs on its own. On the other hand, in Node, JavaScript has access to your file system and can read and write your files.

For instance, you can run scripts on your machine to initialize a project. We are going to do that. You can run checks on your files and automatically correct the mistakes. Or you can run your test files.

In short, Node lets you run some tools that make your life much easier as a developer.

To install Node, go to nodejs.org and install it. If you are unsure if you already have Node, you can also go to your terminal and run node -v to check. If you get a version number, you have Node.

So, why do people associate Node primarily with backend development? If the backend code is in JavaScript, the servers must run it somehow without a browser. So yes, if you are a backend developer using JavaScript, then you're most probably going to use Node. But Node is much more than that.

How to Run Your Project

Now that we have Node, we can use a live server to see our site live in the browser as we develop it. Without this, you need to manually refresh the browser window every time you make a change.

These tools are called bundlers because they take all your files and turn them into a neat package you can run in the browser. So why do you need them?

• They update your site live in the browser with hot reloading. When you save a file, you immediately see the result in your browser.

• As web development tools have evolved, the browser won't understand your files when you use anything more advanced. For instance, are you using React? Then, you're using the JSX syntax – the one that looks like HTML. The JSX syntax is not part of JavaScript. You need a tool to convert it into plain JavaScript. Otherwise, it won't run in your browser. Or are you using TypeScript? You also need to turn that into JavaScript. Or, if you're using SCSS or any other CSS dialect, you need to convert it to plain CSS.

• If you import libraries using the JavaScript module system, you need a live server to avoid CORS issues in your browser.

This is what bundlers do. They make sure that you can use modern-day tooling while you're developing your application, and they can also create a final production build that you can publish on the internet.

How do you pick a bundler? There are several options, and essentially, they all do the same thing. The difference between them is in their performance, configuration options, and ease of use.

The most used bundler is still webpack, one of the earliest bundlers in the field. But the one that seems to have taken over the throne and gained more and more popularity is Vite. Here's a chart from the latest edition of the State of JavaScript survey.

This chart shows that while most developers have used Webpack, they don’t necessarily love it. At the same time, Vite's popularity is rising while still maintaining a positive sentiment.

If you haven't checked out the State of JavaScript survey before, I highly recommend going through it. It gives you an excellent overview of the latest trends with JavaScript. You can learn which tools and libraries people love to use and which they will abandon soon. If you feel overwhelmed by all the changes in the JavaScript ecosystem, the results of this survey can be a great guide.

Once we have a folder for our project, let's navigate to it using our terminal. The easiest way to do this is to open the folder in VS Code and then use the built-in terminal. VS Code will open the terminal with the correct folder.

Then, you can run the project in the terminal with the following command. npx is a command line tool that comes with Node. This is one of the reasons we installed Node: to be able to run commands like this.

npx vite

The first time you run this script, it will ask you to install Vite. Say yes. Then, it will show you the URL of a local server, which you can open in a browser to view your project.

  VITE v6.1.0  ready in 162 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Now, if you update a file and save the changes, the new version appears in the browser immediately. It generates a live preview of your site until you stop the script or close the terminal. You can keep it running while you're developing your site.

Once you have finished, you can press Ctrl+C to stop the script. If it gets desynchronized or you break it with an error, restart it by pressing Ctrl+C to stop it and rerunning the same script. So that's how you run a project with Vite.

How to Add Libraries to Your JavaScript Project

Now that we have Node, we can also use npm or Note Package Manager to add libraries to our project. npm is another tool included with Node. So how does it work?

First, I will walk you through setting things up step by step the manual way so it's clear how the different parts come together. Then, I will show you how to automate most of these steps.

Navigate to your current folder in the terminal and run the following command to initialize the project. This command initializes a package.json file with some metadata.

npm init --yes

At this point, this file is not very interesting. It contains the project name, description, version number, and so on. You can change these values.

Now, we can add libraries to our package with the npm install command. In a previous article, we used Three.js to render 3D boxes in the browser.

So, as an example, let's install Three.js. Go to your terminal again, make sure you are in the correct folder, and run the following command:

npm install three

This command will install Three.js. But how do you know that the keyword is three here, not Three.js?

When you don’t know the package name, you can just google npm and the name of the library you need. Or, if you don't even know the library name, you can also just search for an npm 3D library and see what Google comes up with.

We can go through each package one by one and pick one based on their capabilities and other info. These packages mostly come with descriptions and quick examples to give you an idea of what the library can do for you.

Another indicator you might want to look for is the weekly downloads and the date of the last update to ensure you select an actively maintained library that people still use.

Once you find the package you are looking for, you can see the command to install it at the top right corner: npm i three. The i here is just shorthand for install. Another way to learn how to install Three.js is to go to its official documentation and check the installation guide.

When we install a package, three things happen:

• It adds the latest version of Three.js in our package.json file as a project dependency.

• It also creates a package-lock file, which NPM uses to keep track of the dependencies. You should never edit the dependency section of your package.json file or the package-lock file manually. Instead, you should always use commands like npm install and uninstall to add, remove, or update packages.

• Finally, the node_modules folder gets created. This folder contains the source code of Three.js. When we import Three.js in our project, it looks for it in this folder. The content of this folder is also something that you should never change. You can look into it if you're interested in the source code of the library that you're using, but you shouldn't change it.

If something goes wrong and you have an error with your dependencies that you can't figure out, then you can always safely delete the node_modules folder and the package-lock file and reinstall your dependencies based on the package.json file. This is not something that you should do, but you can always go back to having a clean slate.

Now that we have installed Three.js, we can create a simple website that displays a 3D box. It's a simple HTML file and a JavaScript file with the code for the 3D box. The key here is that we import Three.js with the import statement in the JavaScript file. This import will use the package that we just installed.

Then, we can run the project with Vite. Using imports means that we use the module system now. Running a project with the module syntax can be a bit tricky, as the browser gives you CORS errors by default. However, as we are using Vite to run our project, it works seamlessly without any questions. That’s one of the reasons we use Vite.

If you want to learn more about building 3D games with Three.js, check out my earlier article on building a minimalistic car in the browser.

How to Get Coding Tips While You Code

The second must-have editor extension is ESLint. While Prettier formatted the code, ESLint gives you coding tips.

It helps you catch basic mistakes and avoid patterns that can cause bugs or be misleading when you try to understand the code.

Here’s a simple example where you declare a variable, but then you have a typo, and you try to use another variable that doesn't exist. ESLint will highlight this for you. It will give you an error both at the variable declaration, saying that you created a variable you don't use, and add the usage, saying that you're trying to use a variable that is not declared. With ESLint, it's easy to spot that you made a typo.

ESLint, of course, is much more complex than just being able to catch simple errors. There are also less obvious use cases where you might not understand why ESLint is complaining. Then, you can always click the link in the error popup for more details explaining why this pattern is harmful and what you can do to avoid it.

So how can we use ESLint in our projects? This time, we need to have an extension and a configuration. First, as we did with Prettier, we must install the ESLint extension. Go to your extensions, search for ESLint, and install it.

We also need to set up ESLint for our project. Before we do that, we need to make sure that the project already has a package.json file. If you don't already have a package.json file, we first have to run npm init --yes to initialize the project. Then, we can generate an ESLint config with the following command:

npm init @eslint/config@latest

This script will ask you a few questions. Based on your answers, it will customize the configuration and the rules to check. For most cases, you can use the default option.

• The first time, it will ask for permission to install ESLint. Say yes.

• Then, it will ask you whether to use ESLint only for syntax checks or to find problems as well. Choose the second option to get the most help from ESLint.

• Then select that you’ll use it with JavaScript modules. Modern web development projects use the JavaScript module system. We use JavaScript modules if we have imports and exports in our code.

• Then, it will ask what framework we are using. If we select a framework, it will add framework-specific rules to our project. For instance, using it with React will force us to define the prop types. If we don't use a front-end framework, just vanilla JavaScript, then select "None of these".

• Then, it will ask if the project is using TypeScript. Choose based on your preference.

• It asks where you run the code. As we have a front-end project, select "Browser".

• Then, it will ask if you want to install the additional dependencies that are required for the rules based on your selections. Select yes.

• It will also ask what package manager we’re using. We haven't talked a lot about this, but there are multiple package managers that we can use. Select the default: npm.

These were a lot of questions. Let's see what happened after we ran this command.

After this step, we have ESLint and some other dependencies based on the answers in the package.json file as development dependencies. Development dependency means that ESLint won't be part of your website's final code, but we need it during development.

ESLint also became part of our node_modules folder, and there are many more packages here now. This is because a dependency can have other dependencies, and the dependencies of the dependencies will also be part of the node_modules folder.

ESLint also created a config file that sets up the rules based on your answers. We will see how to customize the rules.

Now that ESLint is working, you should also see errors in the code once something is off. If you go to your JavaScript file and try to use an undeclared variable, ESLint will highlight the issue.

ESLint is also highly customizable. For instance, we might not want to mark an unused variable as an error. First, we go to the error popup and select the identifier of this type of error. Then, we go to the ESLint config and override this error as follows. Here, we can reduce the severity to a warning or completely turn off this rule.

import globals from "globals";
import pluginJs from "@eslint/js";


/** @type {import('eslint').Linter.Config[]} */
export default [
  {languageOptions: { globals: globals.browser }},
  pluginJs.configs.recommended,
  {
    rules: {
      "no-unused-vars": "off", // Turn off the No Unused Variables rule
    }
  }
];

But if you're a beginner, I recommend following the rules that ESLint has by default. Sometimes, it might be annoying to fix all the seemingly harmless issues, but all these rules are based on industry best practices, so it's good to follow them. For more details, check out ESLint's documentation.

Initialize a Project with Vite

We walked through the step-by-step process of setting up a project. We used npm init to initialize the project, manually set up ESLint, and ran our project with Vite. Vite can also initialize the project with a sample application and all the necessary files, which is especially handy when we set up a React project.

Let's see how to set up a vanilla JavaScript and a React project. Let's navigate to a folder in the terminal that will contain our project. We don't need to create a project folder this time because the script will make it for us. Then, run the following command to initialize a project:

npm create vite@latest

This command asks you a few questions.

• First, it will ask you for the project name, which will also be the name of the folder created as the project root.

• Then, it will ask what framework you use. If you don't use any framework and want plain old JavaScript, choose "Vanilla." If you use React, choose React.

• Then, it will ask you if you want to use TypeScript or JavaScript. Here, the default is TypeScript. If you're a beginner in web development, choose JavaScript. If you are more confident with your skills, then go with TypeScript. TypeScript is more complicated, but it has become the industry standard in web development, and most jobs require you to know it. As a beginner, you can go with JavaScript.

Now, we can navigate to the new folder created and check out what we have here. If you choose a vanilla JavaScript project, you can see it generated a simple application with HTML, CSS, and some JavaScript files. You can change or even delete these. You'll need an HTML file as an entry point, but you can replace the rest.

We can run this project with npx vite as we did before, but there’s a better way. For a real project, we want to add Vite as a development dependency to ensure consistency with the version we are using.

{
  "name": "my-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "vite": "^6.1.0"
  }
}

The package.json file shows that Vite has been added as a development dependency. To use this hardcoded version, we first have to install it via npm install. This command installs all the dependencies listed in the package.json file.

npm install

This package.json file now also has a scripts section. This section can define scripts to run your app locally, create a production build, or test your application. You can run them with npm run. So, for instance, to run the application, you can open the terminal with the correct folder and run the following command.

npm run dev

This runs the script labeled as “dev” in the scripts section, which will run the Vite version we just installed with npm install.

Vite does not install ESLint when you create a vanilla project, but you can always install it manually, as we did before with npm init @eslint/config@latest.

If you choose React as a framework when we initialize the project, we will have a couple more files. For instance, we have an ESLint config with the recommended React settings. We also have a Vite config that enables us to use React and a sample application that we can run.

To run this app, we need to install the dependencies. So, let's go to the terminal and run npm install. This will install all the dependencies, including React. Then, we can run this app with npm run dev, and we will have a working React application.

Summary

In this article, we set up and run a front-end project with Vite. We also covered how to find and add dependencies, how to have consistent and automatic formatting with Prettier, and how to avoid bugs with ESLint.

What happens once you finish developing your app? How do you upload it to the web and share it with the world? That's the topic of a future article.

Subscribe for more tutorials on Web Development:

Modern-day computing services also provide a wide range of features which make web apps easier to use and more efficient. So it's important for developers to have a basic understanding of how the cloud works.

This article is a beginner's guide to deploying backend applications to the cloud. We'll use the Azure platform as our cloud infrastructure and Node.js/Express for the backend web application. Before we go on, here are a few requirements:

• Basic understanding of cloud computing (you can check out this article to learn more about that).
• Knowledge of JavaScript.
• VS Code.

With that, let's get started.

Introduction to Azure

Azure is a cloud computing platform developed by Microsoft that acts as a server for deploying and hosting web applications, databases, file storage, and so on.

Compared to other cloud computing services, it is quite beginner-friendly and has an actively growing user base. Let’s explore the Azure portal.

How to Set Up Azure Account

Signing up on the Azure platform is the first step to hosting your application. First, navigate to the website and complete the signup process.

Azure sign in page

After signing up, you'll have access to the management console of the Azure application where all our activities can be carried out.

Before we go on, here are some of the services we'll be getting familiar with on this platform.

• Azure Resource groups
• Azure app services
• Storage accounts
• SQL databases
• Virtual networks

Azure services

Congratulations on successfully creating your Azure account.

Deployment Options on Azure

As a cloud computing platform, Azure boasts of its wide versatility. Depending on your skill level or preference, you can deploy web applications to Azure via the following options:

• Azure CLI
• Azure Virtual machines
• Azure Functions
• Azure Kubernetes Service
• Azure Storage.
• Azure DevOps
• Azure portal service

We'll utilize the Azure portal service for this tutorial and use its VS Code integration to deploy a simple Node.js application to the Azure cloud.

How to Set Up the Backend Application

We'll create our web application using Node.js via the command line and Visual Studio Code.

Firstly, navigate to the folder where your app will be created and initialize a Node project by executing npm init

Next, initialize the app by installing the Express framework. This can be done via npm i express.

Go on and paste the sample code for this tutorial:

const express = require("express");
const app = express();

app.use(express.json());

app.get("/", (req, res) => {
    res.send("Hello, World");
});

app.listen(process.env.PORT || 5000, () => {
    console.log("Server is running on port " + (process.env.PORT || 5000));
});

The code above outputs Hello World whenever it is executed.

Application Deployment

The backend code we wrote in the preceding paragraph will be deployed to Azure via the use of Azure’s VS Code extension.

VS Code homepage

Navigate to the Extensions tab, search for Azure App Services and install the extension. On successful installation, an Azure widget will appear on your taskbar where you can sign in to the Azure cloud.

Extensions marketplace

Subsequently, we'll be creating a cloud-based web application in which our Node.js code will later be deployed.

On the Azure resources tab, clicking the plus icon will display a drop-down menu where various development options can be seen. We'll be clicking on the Azure app services option.

Azure drop down menu

After clicking that, a prompt will pop up asking for a unique name for the cloud application. In my case, I went with newApp777.

creating a web application

However, you can use any other name you so wish. Subsequently, you will need to select the backend language of your choice. Any version of Node.js will be compatible with our application.

web stacks available

Also, the F1 service option will be used for this tutorial. However, you can pick anyone you so desire.

Various Azure tiers

On successful completion, your application will be created on the Azure portal.

Now to the crux of the matter. Let's install our Node.js code on this web application.

We'll click on the code folder which provides us with options to automatically deploy our code to an Azure web app service.

Deployment dropdown menu

As soon as this is done, the list of the cloud servers on your Azure account will be shown. You can then select the new app we just created.

app deployment

Your backend code should then be deployed on the NewApp cloud server we created. On successful completion, you'll receive a success message with a link to your cloud application.

command prompt interface

Congratulations, you have successfully hosted your first web application. Navigate here to see the hosted application.

The application webpage

Additional Information

So far, we have covered the basics of deploying an application via the use of VS code extensions on Azure portal services. As you progress in the field of cloud computing, other interesting fields can also be explored such as:

• App monitoring with Azure Monitor.
• Azure app networking essentials.
• Azure MySQL database integration.
• Node JS serverless functions deployment.

You can also interact with me on my blog and check out my other articles here. Till next time, keep on coding!

Prerequisites

Before we start, you need to have some basic command line knowledge. Nothing sophisticated, but make sure you've used it before reading this article otherwise you might feel a bit lost.

What Is NVM?

Node Version Manager (NVM) is a command-line utility that enables you to manage multiple installations of Node.js and easily switch between them.

Whether you need to work on projects requiring different Node.js versions or want to experiment with the latest releases without affecting your existing setups, NVM provides an easy way to do so.

Why Do You Need Multiple Node Version?

Nowadays, companies often build their application in the microservice architecture. This means that applications tend to be divided into many smaller services, where every service has its dedicated role.

It might sound like an over-engineering but there are a few benefits from this approach. In some cases, companies decide to build their applications using micro services to reach high availability and allow deployments without downtime. In the end, they can deploy one service at a time.

This approach also has downsides related to complexity and managing multiple projects. Imagine that your application is divided into many micro services, where the first one was built over 5 years ago.

The service is likely running on a legacy version of Node.js. In an ideal world, you would have to upgrade Node version to the newest version but it isn't always possible. In the end, the users' satisfaction comes first, and if they need new features, their needs must be fulfilled first.

Sometimes, a new feature might require you to introduce a new micro service. In this case, you should always try to use the newest Node version available. I will show you how to install multiple Node versions on your machine.

But I Am a Front End Developer

You'll still need NVM as a front end developer.

Nowadays, every JavaScript library and framework requires Node runtime and that's why you should manage Node versions for the frontend projects as well. The example project we will be using in this article is built in React 18 & Next.js.

Let's get started.

How to Install NVM on Linux and Mac

Installation on Linux and Mac is ultra simple.

Just open your terminal and run the following command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

This script will configure NVM on your machine and you will be able to use immediately. Nothing else is required.

Just try to run nvm command in your terminal, and you should see the following output:

nvm command output

If you see something like nvm: command not found then you can run these commands:

source ~/.bashrc
source ~/.zshrc

It's expected that one of them fails. This commands will reload you bash / zsh profile and enable NVM in your command prompt.

How to Install NVM on Windows

You can easily install NVM on Windows – just open the nvm-windows repository on GitHub, scroll down to the Assets section, and download the nvm-setup.exe file.

NVM Windows repository

Now the installer file will be downloaded. Once the download is completed, double-click on the nvm-setup.exe file and follow the instructions:

NVM for Windows Installer by Corey Butler

After the installation, open PowerShell and run nvm command, you should see the following output:

NVM in PowerShell by Corey Butler

If nvm command returns command not found you should restart your computer to refresh your user settings.

How to Set Node Version For Your Project

Now, we are reaching the root of this guide – setting dedicated Node version for your project.

First, create a .nvmrc file in your project root folder and specify the expected Node version.

It is 20.10.0 in my case:

Node version in .nvmrc file

Now open your terminal and navigate to your project and run the nvm use command. NVM will automatically load the expected Node version by your project.

nvm use command

If you don't have the expected version on your machine, you'll be prompted to install it:

prompt to install node version

In this case, you need to install required Node version by running nvm install x.y.z. Replace x.y.z with the expected Node version. It was 20.10.0, in my case.

Conclusion

Working on multiple projects can be a hassle, especially when they require different Node versions. However, with NVM, changing the Node version is as quick as blinking an eye.

You should always use it, whether you're working alone on your personal project or with multiple colleagues on a large enterprise application.

If this article helped you, please share it on your social media or give me a shout-out on Twitter. Thank you!

Learn React 18 & Next.js

This article is a part of my React and Next.js course on Udemy. I will help you to get started with React and Next.js by creating a 2048 Game with awesome animations. I believe creating games makes learning more fun, and you'll have something cool to show your friends.

👇👇👇👇

🧑‍🎓 Enroll to my course on Udemy

But if you use the typical sudo apt install nodejs command, it may install a very old version of Node which can be troublesome for you.

So you'll want to install a specific version, which requires a different command. This will install the LTS (Long-Term Support) version of Node which is useful for devs because it has a longer period for support.

Today, I am going to show you how you can install the latest LTS version of Node on your Ubuntu operating system.

This processes will work on any kind of Debian-based Linux operating system (Ubuntu, Mint, Zorin, Debian, Elementary OS, and so on). It'll work whether you are using that as your main operating system, secondary operating system on dual boot, WSL on Windows, or using in a virtual machine (VMware Workstation, VirtualBox, and so on).

Video Tutorial

I have also created a complete video to show you the process step-by-step. You can watch it here:

At the time of writing this article, the latest LTS version for Node is 18.18.2.

Node download page showing current LTS version

When you install Node following the instructions in this article, it will install the latest LTS version of Nodejs automatically. So you'll be safe without any hassle if you simply follow this article and the accompanying video.

Update Your Operating System

First, you'll want to ensure that you have installed all the updates beforehand. I like to work in the terminal mostly, so I'll install the updates using the terminal directly.

For updating to the latest versions of all the relevant packages, use sudo apt update in the terminal. Use your password when it asks for that.

Updating all relevant packages

Now use sudo apt upgrade -y to upgrade all the upgradable packages.

Upgrading all relevant packages

Install CURL

We're using the Node Version Manager (NVM) here to install Node. There are various advantages when we install Node and npm using the NVM as it also allows us to manage multiple versions of Node.js on our system altogether.

First, you'll need to install curl if it's not installed on your system already. You can install curl by using the command below:

sudo apt install curl -y

Installing CURL

How to Install Node.js

Now you'll need to follow these steps in order to ensure that you've installed Node.js successfully on your system.

Install Node Version Manager (NVM)

Install the Node Version Manager (NVM) by using the following command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Installing the Node Version Manager (NVM)

When you run this specific command, the curl downloads the NVM installation script from that specific URL. Afterward, bash executes the same script for installing NVM.

Activate NVM

Activate the NVM using the command below:

source ~/.bashrc

Activating the Node Version Manager (NVM)

Install the latest LTS version of Node

Install the latest Long Term Support version of Node by using the command below:

nvm install --lts

Command for installing the latest LTS version of Node.js

It installs the latest version of the LTS release of Node by default.

Make the default LTS version as NVM

We have installed the latest LTS version of Node, but we also need to set the default version of NVM so that it gets used by default whenever we need it. You can use the command below to do that. Make sure to change the version to the exact LTS version you have installed on your system just now.

nvm alias default 18.18.2

Selecting the appropriate Node version as the default version

If your LTS version is something like 24.1.2 then the command would be like below:

nvm alias default 24.1.2

Confirm that Node was installed

Use the command below to check whether the default version is the exact version you just installed:

node -v npm -v

Showing the current version of Node installed

How to Set Up the Node.js Environment

After installing Node and NPM, you need to set up the Node environment by creating a new Node project.

Use the command below to create a new directory/folder where you want to test a simple "Hello World" type Node project.

mkdir my-node-project

Creating a new directory/folder to test a simple "Hello World" program on Node

Navigate to the my-node-project directory by using the command below:

cd my-node-project

Changing the directory to enter into that newly created directory/folder

Initialize the new Node project like this:

npm init -y

This command will create a "package.json" file containing your project's metadata and dependencies. Here is the JSON output:

Initializing npm in the folder

The JSON output is below:

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

Now run the setup with the simple command. For this, I am going to create a new file called app.js using the nano text editor in the terminal.

sudo nano app.js

Opening app.js file in nano

Once the text editor opens, type the below code:

console.log("Hello, Node.js from Ubuntu!");

Writing a simple console.log code in the app.js file using nano

Use Ctrl+ O to save the file. Use Enter to save the file as app.js:

Save the app.js file with the newly added line of code

Use Ctrl + X to return to the bash terminal again.

Returning to the terminal again

Now, it is time to check the output and see whether it's working or not.

Use the command below:

node app.js

Running the app.js file using Node

It is working!

We have successfully installed the latest LTS release of Node on our Ubuntu/Debian-based Linux operating system.

Cheers! 🥂

Conclusion

Thank you so much for reading the entire article till now.

If you have enjoyed the procedures step-by-step, then don't forget to let me know on Twitter/X or LinkedIn.

You can follow me on GitHub as well if you are interested in open source. Make sure to check my website (https://fahimbinamin.com/) as well!

If you like to watch programming and technology-related videos, then you can check my YouTube channel, too.

All the best for your programming and development journey. 😊

You can do it! Don't give up, never! ❤️

• Building an API server in Node
• Integrating securely with a 3rd party API
• Interacting with a Postgres database using Prisma
• Making API requests from React
• Creating reusable components
• Working with pagination
• Working with UI elements such as tabs, image grids, modals and styling

Let's dive in.

Table of Contents

• Prerequisites
• GitHub Repositories
• Video Tutorial
• Project Architecture
• How to Setup the Backend
• How to Setup the Database and Prisma
• How to Get and Secure a Spoonacular API Key
• How to Create the Search Endpoint
• How to Setup the Frontend
• How to Call the Search API and Display Results on the Frontend
• How to Create the Search Input and Recipe Card Component
• How to Build the Pagination and View More Functionality
• How to Build the Recipe Summary Modal Component
• How to Create Endpoints to Get/Create/Delete Favorite Recipes
• How to Add Favorites Functionality to the Frontend
• How to Adding CSS/Styling
• Conclusion

Prerequisites

Since we will be focusing on how to build a project, there are a few prerequisites that will be needed to get the most out of this tutorial:

• Some knowledge about web development concepts (frontend, backend, databases, API's, REST).
• Some knowledge of JavaScript (variables, functions, objects, arrays, and so on).
• Basic understanding on React (how to create components, add styles, work with state).
• Basic understanding on Node.js/Express (working with APIs).

GitHub Repositories

Completed Code

You can find the completed code on GitHub by clicking here, or clone the repo:

git clone git@github.com:chrisblakely01/react-node-recipe-app.git

Starter Code

If you want to save some time and skip the initial setup, you can find the starter code here. This has a skeleton frontend/backend project already setup, as well as the basic layout and CSS. Or clone the repo:

git clone git@github.com:chrisblakely01/react-node-recipe-app-starter.git

Video Tutorial

If you'd like to learn from the video version as well, here it is:

Project Architecture

Here's a diagram that illustrates how the various components of our app will interact with each other:

Diagram illustrating the various components of the app

We will have a React front end and a Node backend. These two will communicate through specific endpoints. We will establish five endpoints, all housed within our backend.

We can categorize these endpoints into two distinct groups. The first group will cater to recipe searches. It will invoke the recipe API and return the results based on a given search query. Our front end will initiate a call to our backend, which will then relay the search request to the recipe API.

We choose not to call the recipe API directly from our front end because it requires an API key—a form of authentication similar to a password. Exposing this key in our front end code could lead to unauthorized access if someone delves into the code through their browser to retrieve the API key.

It's a more secure practice to house the API key on our backend within environment variables. From there, we can call the recipe API and then transmit the response back to our front end.

This approach aligns with common practices in production environments. It also offers the flexibility to modify the data on the backend, if necessary, before sending it back to the front end. And it enhances performance, as the UI will not have to manage multiple API requests to and from the recipe API.

That's the essence of how our search functionality will operate. We'll also have several endpoints to add, create, and delete favorites. These favorites will be stored in our own database, providing a clear picture of what we aim to build.

How to Setup the Backend

In this tutorial, we will walk through the process of building a full-stack recipe application. We'll set up the backend, create the frontend, and link it to a database. We will also connect to a recipe API using an API key.

If you prefer to skip the setup, a starter code is available on CodeCoyotes, which includes some basic setup and CSS. But you'll still need to create a database and obtain an API key.

Let’s start by setting up our workspace:

Step 1: Setup Your Workspace

Start by opening Visual Studio Code (or your preferred code editor). Create a new folder named recipe-app on your desktop or another location. Then drag this folder into the Visual Studio Code window to open it.

Your folder structure should now look like this:

recipe-app

Step 2: Setup the Backend

In the recipe-app folder, create another folder named backend.

Navigate to View -> Terminal in Visual Studio Code to open a terminal. Change your directory to the backend folder using the command cd backend.

Type npm init to initialize a new npm package, then hit Enter to move through the prompts. For the entry point, type ./src/index.ts and hit Enter.

Your folder structure should now look like this:

recipe-app
|-- backend
    |-- package.json

Step 3: Install the Dependencies

First, install the necessary dependencies using the following command:

npm install express prisma @prisma/client cors

Now, install the development dependencies:

npm install --save-dev ts-node typescript nodemon @types/cors @types/express @types/node

Your folder structure should now look like this:

recipe-app
|-- backend
    |-- node_modules
    |-- package.json
    |-- package-lock.json

Step 4: Setup Your Backend Code

In the backend folder, create a new folder named src. Inside src, create a file named index.ts.

Add the following code to index.ts:

import express from "express";
import cors from "cors";

const app = express();

app.use(express.json());
app.use(cors());

app.get("/api/recipe/search", async (req, res) => {
  res.json({ message: "success" });
});

app.listen(5000, () => {
  console.log("Server running on localhost:5000");
});

Step 5: Add the Start Script

First, open package.json in the backend folder. In the scripts section, replace the test script with a start script as follows:

"scripts": {
    "start": "npx nodemon ./src/index.ts"
}

Step 6: Run Your Backend

In the terminal, ensure you are in the backend folder, then type npm start to run your backend server.

Then open a browser and go to http://localhost:5000/api/recipe/search. You should see a response with the message success.

Congratulations! You have successfully set up and run your backend server. In the next part of this tutorial, we will focus on setting up the frontend and connecting to a database.

How to Setup the Database and Prisma

In this section, we'll focus on setting up a Postgres database using ElephantSQL and integrating Prisma to interact with our database effortlessly. Let's jump right in!

Step 1: Set Up the ElephantSQL Database

Start by navigating to ElephantSQL. Click on "Get a managed database today," followed by selecting the "Tiny Turtle" plan for a free instance.

Sign in or create an account to proceed to the "Create new instance" page.

Then enter a name for your database (for example, recipe-app-db), keep the plan on the free tier, and choose a region closest to you.

Click on "Review," verify the details, and then click on "Create instance."

Step 2: Retrieve the Database Credentials

Once your instance is created, click on it to view the details.

Locate and copy the URL under the "Details" section. This URL contains the credentials needed to connect to your database.

Step 3: Create an Environment File

Now, return to your code editor and open the backend folder.

Create a new file named .env. Inside the .env file, add the following line:

DATABASE_URL=<Your-Copied-Database-URL>

Replace <Your-Copied-Database-URL> with the URL you copied from ElephantSQL.

Step 4: Integrate Prisma

Stop your server if it's running by pressing Ctrl + C (or Cmd + C on Mac) in the terminal.

In the terminal, ensure you are in the backend directory, and type the following command to initialize Prisma:

npx prisma init

This command will create a new folder named prisma with a file named schema.prisma.

Step 5: Verify Prisma Integration

Now, open prisma/schema.prisma to ensure your DATABASE_URL has been detected correctly.

Start your server again with the command npm start. Then navigate to http://localhost:5000/api/recipe/search in your browser to ensure your API still works and returns the success message.

Your folder structure should now include the Prisma folder and look like this:

recipe-app
|-- backend
    |-- prisma
        |-- schema.prisma
    |-- .env
    |-- ...

How to Get and Secure a Spoonacular API Key

Step 1: Obtain an API Key from Spoonacular

To do this, navigate to Spoonacular and click on "Start Now." Sign up for an account and proceed to the dashboard.

Within the dashboard, click on “Profile” on the left-hand side, and find the section related to API keys. Generate a new API key, and copy it to your clipboard.

Step 2: Store the API Key Securely

Now, return to your code editor and open the .env file in the backend folder.

Add a new environment variable to store your API key as follows:

API_KEY=<Your-Copied-API-Key>

Replace <Your-Copied-API-Key> with the API key you copied from Spoonacular.

Step 3: Install and Setup Thunder Client

In Visual Studio Code, navigate to the extensions tab (square icon on the sidebar), and search for Thunder Client.

Install Thunder Client by clicking on the Install button. Once installed, you will see a new icon (a purple thunderbolt) on the sidebar.

Step 4: Test the API Key with Thunder Client

Now click on the Thunder Client icon, then click on “New Request.”

Copy the endpoint URL for searching recipes from Spoonacular's documentation. It should look something like this: https://api.spoonacular.com/recipes/complexSearch.

Paste this URL into the URL bar in Thunder Client.

Under the query tab, add two new parameters:

• apiKey with the value of your API key.
• query with a value of burgers or any other term you wish to search for.

Then hit "Send" to issue the request and observe the response. You should see a list of recipes related to the term you searched for, indicating that your API key and endpoint are working correctly.

How to Create the Search Endpoint

Step 1: Setup a New File for Recipe API Logic

First, navigate to your backend/src folder and create a new file named recipe-api.ts.

In recipe-api.ts, initiate a constant to store your API key from the environment variables:

const API_KEY = process.env.API_KEY;

Step 2: Create the searchRecipes Function

In recipe-api.ts, define a new asynchronous function searchRecipes that takes in a searchTerm and a page as parameters:

export const searchRecipes = async (searchTerm: string, page: number) => {
  if (!API_KEY) {
    throw new Error("API key not found");
  }

  const baseURL = "https://api.spoonacular.com/recipes/complexSearch";
  const url = new URL(baseURL);

  const queryParams = {
    apiKey: API_KEY,
    query: searchTerm,
    number: 10,
    offset: (page - 1) * 10,
  };

  url.search = new URLSearchParams(queryParams).toString();

  try {
    const searchResponse = await fetch(url.toString());
    const resultsJson = await searchResponse.json();
    return resultsJson;
  } catch (error) {
    console.error(error);
  }
};

Step 3: Import and Use searchRecipes in index.ts

Now, navigate back to index.ts in the backend/src folder.

Import the searchRecipes function from recipe-api.ts at the top of your file:

import * as RecipeAPI from "./recipe-api";

Locate the endpoint where you wish to utilize the searchRecipes function, and modify it to call searchRecipes with the appropriate arguments, then return the results:

app.get("/api/recipe/search", async (req, res) => {
  const searchTerm = req.query.searchTerm as string;
  const page = parseInt(req.query.page as string);

  const results = await recipeAPI.searchRecipes(searchTerm, page);
  return res.json(results);
});

Step 4: Test Your Endpoint

Now you can restart your server by stopping it (Ctrl + C or Cmd + C on Mac) and then running npm start.

Test your endpoint by sending a GET request with the appropriate query parameters. For example, navigate to http://localhost:5000/api/recipe/search?searchTerm=burgers&page=1 in your browser or use a REST client like Postman or Thunder Client.

You should now see a list of recipes returned in response to your request, indicating that your backend logic for calling the Recipe API and returning the results is functioning as expected.

How to Setup the Frontend

Before you get started on this section, make sure you're in the top-level directory of your project, which in this case is named recipe-app.

Step 1: Create a React App with Vite

Start by opening a terminal and ensuring you're in the top-level folder (recipe-app).

Then run the following command to install the latest version of Vite:

npm install vite@latest --save-dev

Now, initiate a new React project with Vite by running:

npx create-vite frontend --template react-ts

This command creates a new folder named frontend, sets it up as a React project, and specifies TypeScript as the language.

Step 2: Navigate to Your New React App

Change your directory to the frontend folder:

cd frontend

Then install any necessary dependencies:

npm install

Step 3: Start the Development Server

You can start the development server with the following command:

npm run dev

Your default web browser should now open displaying the initial setup of your React app, which includes a counter example.

Step 4: Clean Up and Personalize Your React App

Now you can head back to your code editor and navigate to frontend/src. Delete the index.css file as it won't be needed.

In main.tsx, remove the import statement for index.css.

Now, open App.tsx. Here, you'll see code for a counter. Delete all the content inside App.tsx.

Let’s start fresh by adding the following code to App.tsx:

// src/App.tsx
const App = () => {
  return <div>Hello from Recipe App</div>;
};

export default App;

Save App.tsx and check your browser to see the updated text: "Hello from Recipe App".

Step 5: Setup Your Stylesheet

Go to src and open App.css. Delete all the pre-filled styles but keep the .root class definition empty for now.

Add a font-family property to the .root class:

/* src/App.css */
.root {
  font-family: Helvetica, Arial, sans-serif;
}

Then head back to App.tsx and import your stylesheet:

// src/App.tsx
import "./App.css";

const App = () => {
  // ...
};

Then save App.tsx and check your browser to see the updated font.

Now you have a clean slate to start building out the frontend of your recipe app with React and TypeScript, using Vite as your build tool. As you progress, you can now start adding components, routing, and state management to build out your application's UI and functionality.

How to Call the Search API and Display Results on the Frontend

Now we are going to fetch data from an API and display the results on the UI. The API response is structured as follows:

{
  "results": [
    {
      "id": 650235,
      "title": "Loaded Turkey Burgers",
      "image": "https://spoonacular.com/recipeImages/650235-312x231.jpg",
      "imageType": "jpg"
    }
    // ... other recipes
  ],
  "offset": 10,
  "number": 10,
  "totalResults": 50
}

Each recipe object contains an id, title, image, and imageType. We will map through the results array and display each recipe on our UI.

Step 1: Setup State

In your App.tsx, setup state to store the searchTerm and recipes.

import React, { useState } from "react";

const App = () => {
  const [searchTerm, setSearchTerm] = useState("");
  const [recipes, setRecipes] = useState([]);

  // ... rest of your component
};

Step 2: Fetch Data from the API

Create a new file API.ts and set up a function to make the API call.

// src/API.ts
const searchRecipes = async (searchTerm: string, page: number) => {
  const baseURL = new URL("http://localhost:5000/api/recipes/search");
  baseURL.searchParams.append("searchTerm", searchTerm);
  baseURL.searchParams.append("page", page.toString());

  const response = await fetch(baseURL.toString());

  if (!response.ok) {
    throw new Error(`HTTP Error: ${response.status}`);
  }

  return response.json();
};

export { searchRecipes };

Step 3: Create a Handler Function

Back in App.tsx, import the searchRecipes function and create a handler function to be called when the form is submitted.

import React, { useState, FormEvent } from "react";
import { searchRecipes } from "./API";

const App = () => {
  // ... previous state setup

  const handleSearchSubmit = async (event: FormEvent) => {
    event.preventDefault();

    try {
      const { results } = await searchRecipes(searchTerm, 1);
      setRecipes(results);
    } catch (error) {
      console.error(error);
    }
  };

  // ... rest of your component
};

Step 4: Display the Data

Display the recipes data in your component's return statement.

const App = () => {
  // ... previous code

  return (
    <div>
      <form onSubmit={handleSearchSubmit}>
        <button type="submit">Submit</button>
      </form>
      {recipes.map((recipe) => (
        <div key={recipe.id}>
          Recipe Image Location: {recipe.image}
          <br />
          Recipe Title: {recipe.title}
        </div>
      ))}
    </div>
  );
};

export default App;

Step 5: Define the Recipe Type

Define a Recipe interface in a new file named types.ts.

// src/types.ts
export interface Recipe {
  id: number;
  title: string;
  image: string;
  imageType: string;
}

Back in App.tsx, import the Recipe interface and use it to type your state and map function.

import React, { useState, FormEvent } from 'react';
import { searchRecipes } from './API';
import { Recipe } from './types';

const App = () => {
  const [searchTerm, setSearchTerm] = useState('');
  const [recipes, setRecipes] = useState<Recipe[]>([]);

  // ... rest of your code

  return (
    <div>
      {/* ... rest of your return statement */}
      {recipes.map((recipe: Recipe) => (
        {/* ... rest of your map function */}
      ))}
    </div>
  );
};

export default App;

Step 6: Test Your Setup

Now, start both your frontend and backend servers. Open your browser, navigate to your app, and try submitting a search. You should see the recipes data displayed on the screen.

# In one terminal
cd frontend
npm run dev

# In another terminal
cd backend
npm start

This setup should now fetch and display recipe data based on the hardcoded searchTerm of "burgers". In a real-world scenario, you'd replace the hardcoded searchTerm with a dynamic value from a user input field.

How to Create the Search Input and Recipe Card Component

Step 1: Setup Your Project

Start by setting up a new React project or navigate to your existing project directory.

npx create-react-app recipe-search-ui
cd recipe-search-ui

Step 2: Create State Hooks for User Input and Data

In your src folder, create a new file named App.tsx and import the necessary dependencies:

import React, { useState, FormEvent } from "react";

function App() {
  const [searchTerm, setSearchTerm] = useState < string > "";
  const [recipes, setRecipes] = useState < Array < any >> [];

  // ... rest of the code
}

export default App;

Here, we have set up two state hooks: one for capturing the user's search term and another for holding the recipe data returned from the backend.

Step 3: Build a Form to Capture User Input

Within the App component, build a form with an input field and a submit button. We'll also create a function to handle the form submission, which will trigger the API call.

function App() {
  // ... rest of the code

  const handleSearchSubmit = async (event: FormEvent) => {
    event.preventDefault();
    // ... API call logic
  };

  return (
    <div>
      <form onSubmit={handleSearchSubmit}>
        <input
          type="text"
          required
          placeholder="Enter a search term"
          value={searchTerm}
          onChange={(event) => setSearchTerm(event.target.value)}
        />
        <button type="submit">Submit</button>
      </form>
      {/* ... rest of the code */}
    </div>
  );
}

Now, users can enter their search term, and upon form submission, handleSearchSubmit will be triggered.

Step 4: Fetch Recipe Data from the Backend

In the handleSearchSubmit function, use the fetch API to send a request to your backend, capture the returned data, and update the recipes state.

const handleSearchSubmit = async (event: FormEvent) => {
  event.preventDefault();
  try {
    const response = await fetch(
      `http://localhost:5000/api/recipes/search?searchTerm=${searchTerm}`
    );
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    setRecipes(data.results);
  } catch (error) {
    console.error(error);
  }
};

Step 5: Display Recipe Data

Create a new folder named components in your src directory. Inside this folder, create a file named RecipeCard.tsx. This component will display individual recipe data.

import { Recipe } from "../types";

interface Props {
  recipe: Recipe;
}

const RecipeCard = ({ recipe }: Props) => {
  return (
    <div className="recipe-card">
      <img src={recipe.image}></img>
      <div className="recipe-card-title">
        <h3>{recipe.title}</h3>
      </div>
    </div>
  );
};

export default RecipeCard;

Now, go back to App.tsx and import RecipeCard. Map over the recipes state to display each recipe using the RecipeCard component.

import RecipeCard from "./components/RecipeCard";

// ... rest of the code

return (
  <div>
    {/* ... rest of the code */}
    {recipes.map((recipe) => (
      <RecipeCard key={recipe.id} recipe={recipe} />
    ))}
  </div>
);

Now, when you submit a search term, the UI will display a list of recipe cards containing the images and titles of the recipes returned from the backend.

Step 6: Test Your UI

Run your React app, enter a search term such as "pasta" or "burgers", and submit the form. You should see a list of recipe cards displaying the relevant recipes from the backend.

npm start

Navigate to http://localhost:3000 in your browser and try out your new recipe search UI!

How to Build the Pagination and View More Functionality

Step 1: Backend Pagination

We added a page query parameter in the search endpoint. The page value is used to calculate the offset for the recipe data fetched from the database or external API.

Step 2: Add "View More" Button to the UI

Navigate to your App.tsx file. Scroll down to the JSX code where you map through the recipes array and add a "View More" button below it.

// ... other code
{
  recipes.map((recipe) => <RecipeCard key={recipe.id} recipe={recipe} />);
}
<button className="view-more" onClick={handleViewMoreClick}>
  View More
</button>;
// ... other code

Step 3: Create a useRef Hook to Store the Current Page Number

Above your component's return statement, create a useRef hook to keep track of the current page number without causing re-renders.

// ... other code
const pageNumber = useRef(1);
// ... other code

Step 4: Implement the handleViewMoreClick Function

Define a function called handleViewMoreClick to handle the logic for loading more recipes.

// ... other code
const handleViewMoreClick = async () => {
  try {
    const nextPage = pageNumber.current + 1;
    const nextRecipes = await api.searchRecipes(searchTerm, nextPage);
    setRecipes((prevRecipes) => [...prevRecipes, ...nextRecipes.results]);
    pageNumber.current = nextPage;
  } catch (error) {
    console.error(error);
  }
};
// ... other code

Step 5: Reset Page Number on New Search

Modify your handleSearchSubmit function to reset the page number back to 1 whenever a new search term is entered.

// ... other code
const handleSearchSubmit = async (event: FormEvent) => {
  // ... other code
  setRecipes(recipes.results);
  pageNumber.current = 1;
};
// ... other code

Step 6: Test Your Implementation

Run your app and perform a search. Click the "View More" button to load more results. Change the search term and ensure that the page number resets, and you get a fresh list of recipes.

npm start

Now, as you search for recipes and click "View More," you should see additional recipes being loaded and displayed in the UI.

How to Build the Recipe Summary Modal Component

I'll walk you through this process step-by-step. We'll create a model that displays a recipe summary using a specific endpoint from the provided API.

Step 1: Understanding the Recipe Summary Endpoint

You can understand where the summary data comes from by looking at your API documentation. The endpoint you need is called Summarize Recipe. This endpoint requires a recipe ID to generate a summary.

Step 2: Setup Backend Endpoint

Create a backend endpoint that interfaces with the Summarize Recipe endpoint.

// In your backend, create an endpoint to fetch recipe summary
// File: recipe-api.ts
export const getRecipeSummary = async (recipeId: string) => {
  if (!apiKey) {
    throw new Error("API key not found");
  }

  const url = new URL(
    `https://api.spoonacular.com/recipes/${recipeId}/summary`
  );
  const params = { apiKey: apiKey };
  url.search = new URLSearchParams(params).toString();

  const response = await fetch(url.toString());
  const json = await response.json();
  return json;
};

Step 3: Create a Backend Route

Create a route in your backend to handle requests to your new endpoint.

// File: index.ts
app.get("/api/recipe/:recipeId/summary", async (req, res) => {
  const recipeId = req.params.recipeId;
  const result = await recipeSummary(recipeId);
  res.json(result);
});

Step 4: Create the Recipe Modal Component

Create a React component for the recipe modal. We will use the useEffect hook to call the backend endpoint we just created, and store the Recipe Summary data in state.

First add a type for RecipeSummary to types.ts

export interface RecipeSummary {
  id: number;
  title: string;
  summary: string;
}

// File: RecipeModal.tsx
import React, { useState, useEffect } from "react";
import { RecipeSummary } from "../types";

interface Props {
  recipeId: string;
  onClose: () => void;
}

const RecipeModal: React.FC<Props> = ({ recipeId, onClose }) => {
  const [recipeSummary, setRecipeSummary] =
    (useState < RecipeSummary) | (null > null);

  useEffect(() => {
    const fetchRecipeSummary = async () => {
      try {
        const summary = await getRecipeSummary(recipeId);
        setRecipeSummary(summary);
      } catch (error) {
        console.error(error);
      }
    };
    fetchRecipeSummary();
  }, [recipeId]);

  return (
    <div className="overlay">
      <div className="modal">
        <div className="modal-content">
          <div className="modal-header">
            <h2>{recipeSummary?.title}</h2>
            <span className="close-button" onClick={onClose}>
              &times;
            </span>
          </div>
          <p dangerouslySetInnerHTML={{ __html: recipeSummary?.summary }} />
        </div>
      </div>
    </div>
  );
};

export default RecipeModal;

Step 5: Style the Modal

Add the following CSS to style the modal:

/* File: app.css */
.overlay {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-color: rgba(0, 0, 0, 0.7);
  z-index: 1;
}

.modal {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  z-index: 2;
  background-color: white;
  padding: 2em;
  border-radius: 4px;
  max-width: 500px;
}

.modal-header {
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: space-between;
}

Step 6: Render and Handle Modal Interactions

Modify your main component to handle rendering and interactions with the modal.

// File: App.tsx
const App: React.FC = () => {
  const [selectedRecipe, setSelectedRecipe] =
    (useState < Recipe) | (undefined > undefined);

  return (
    <div className="App">
      {/* Other components and logic */}
      {selectedRecipe && (
        <RecipeModal
          recipeId={selectedRecipe.id.toString()}
          onClose={() => setSelectedRecipe(undefined)}
        />
      )}
    </div>
  );
};

export default App;

Now, when a user clicks on a recipe, the modal will appear displaying the summary of the selected recipe. The modal can be closed by clicking the close button, which will set the selectedRecipe back to undefined, hiding the modal.

How to Create Endpoints to Get/Create/Delete Favorite Recipes

Step 1: Setup the Database

First, we need to extend our database schema to include a table for storing favorite recipes by their IDs.

First, navigate to the Prisma folder within the backend directory of your project. Then open the schema.prisma file.

Define a new model for favorite recipes as follows:

model FavoriteRecipe {
  id        Int    @id @default(autoincrement())
  recipeId  Int    @unique
}

Step 2: Synchronize the Database Schema

Now, let's synchronize the updated schema with our database.

cd backend
npx prisma db push

Step 3: Setup the Endpoints

We need to set up endpoints in our Node backend to handle creating, viewing, and deleting favorites. We'll use the prismaClient to help us perform crud operations on the database.

First, we'll create a new post endpoint like this:

// In backend/index.ts
import { PrismaClient } from "@prisma/client";

const prismaClient = new PrismaClient();

app.post("/api/recipes/favorite", async (req, res) => {
  const { recipeId } = req.body;
  try {
    const favoriteRecipe = await prismaClient.favoriteRecipe.create({
      data: { recipeId },
    });
    res.status(201).json(favoriteRecipe);
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Oops, something went wrong." });
  }
});

Next, we'll create the View endpoint. To do that, create a utility function to fetch recipe details by IDs:

// In backend/src/recipe-api.ts
export const getFavoriteRecipesByIds = async (ids: string[]) => {
  if (!apiKey) {
    throw new Error("API Key not found");
  }
  const url = new URL("https://api.spoonacular.com/recipes/informationBulk");
  url.search = new URLSearchParams({
    apiKey: apiKey,
    ids: ids.join(","),
  }).toString();

  const response = await fetch(url);
  const json = await response.json();
  return { results: json };
};

Now, create the endpoint to fetch all favorite recipes:

// In backend/index.ts
import { getFavoriteRecipesByIds } from "./src/recipe-api";

app.get("/api/recipes/favorite", async (req, res) => {
  try {
    const favoriteRecipes = await prismaClient.favoriteRecipe.findMany();
    const recipeIds = favoriteRecipes.map((recipe) =>
      recipe.recipeId.toString()
    );
    const favorites = await getFavoriteRecipesByIds(recipeIds);
    res.json(favorites);
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Oops, something went wrong." });
  }
});

Next up is the Delete endpoint:

// In backend/index.ts
app.delete("/api/recipes/favorite", async (req, res) => {
  const { recipeId } = req.body;
  try {
    await prismaClient.favoriteRecipe.delete({
      where: { recipeId },
    });
    res.status(204).send();
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Oops, something went wrong." });
  }
});

Step 4: Test the Endpoints

You can use tools like Postman or Thunder Client to test the endpoints. Make sure to adjust the request method and URL accordingly, and provide the necessary request body or parameters.

• Creating a Favorite: POST request to /api/recipes/favorite with recipeId in the body.
• Viewing Favorites: GET request to /api/recipes/favorite.
• Deleting a Favorite: DELETE request to /api/recipes/favorite with recipeId in the body.

Step 5: Verify the Database

Check the favoriteRecipes table in your ElephantSQL database to verify the actions performed through the endpoints.

How to Add Favorites Functionality to the Frontend

Step 1: Setup the Tab Functionality

Next, we'll look at how to integrate these endpoints on the frontend. We'll start by setting up tabs for 'Search' and 'Favorites' in our app.

First, define a new state to keep track of the selected tab.

import React, { useState } from "react";

type Tabs = "search" | "favorites";

function App() {
  const [selectedTab, setSelectedTab] = useState < Tabs > "search";

  // Rest of your code...
}

Step 2: Render Tabs

Now you'll render tabs in your JSX, and handle tab switching with the onClick event. This makes each <h1> element is clickable, and saves the tab the user clicked on in state. This helps conditionally render different UI elements depending on their selection.

// Inside your JSX...
<div className="tabs">
  <h1 onClick={() => setSelectedTab("search")}>Recipe Search</h1>
  <h1 onClick={() => setSelectedTab("favorites")}>Favorites</h1>
</div>

Step 3: Conditional Rendering

Based on the selected tab, you want to conditionally render either the search component or the favorites component. This will show/hide either the "search section" or the "favourites" section depending on the selectedTab state variable.

{selectedTab === 'search' && (
  // search component code...
)}
{selectedTab === 'favorites' && (
  // favorites component code...
)}

Step 4: Fetch Favorite Recipes

Next we need to populate the Favorite recipes tab with our favourite recipes. We want to do this when the App loads, for a quick user experience.

To do this, fetch the favorite recipes from the backend when the app loads using the useEffect hook, and store the fetched favorite recipes in a new state.

// api.ts
export const getFavouriteRecipes = async () => {
  const url = new URL("http://localhost:5000/api/recipes/favourite");
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }
  return response.json();
};

//App.tsx
import React, { useEffect, useState } from "react";

// ... Rest of your imports and code

function App() {
  // ... Rest of your state declarations

  const [favoriteRecipes, setFavoriteRecipes] = useState([]);

  useEffect(() => {
    const fetchFavoriteRecipes = async () => {
      try {
        const favouriteRecipes = await api.getFavouriteRecipes();
        setFavouriteRecipes(favouriteRecipes.results);
      } catch (error) {
        console.error(error);
      }
    };

    fetchFavoriteRecipes();
  }, []);

  // ... Rest of your code
}

Step 5: Render Favorite Recipes

Now you need to render the favorite recipes in the 'Favorites' tab.

{selectedTab === 'favorites' && (
  <div>
    {favoriteRecipes.map(recipe => (
      // Render each favorite recipe card...
    ))}
  </div>
)}

Step 6: Add a Heart Icon

Next we'll add a way for the user to add and remove favorites. We'll do this by adding a "heart" icon to each card.

Before diving into the code, ensure you are in the correct directory by navigating to your project's front-end directory in your terminal. Install the necessary package for icons by running:

npm install react-icons

Step 7: Import the Icon

Open the RecipeCard component, and import the heart icon at the top of your file:

import { AiOutlineHeart } from "react-icons/ai";

Step 8: Insert the icon

In the RecipeCard component, add the heart icon within a span element just above the h3 tag:

<span onClick={handleFavoriteClick}>
  <AiOutlineHeart size={25} />
</span>

Step 9: Add CSS Styling

In your App.css file, add the following CSS to style the icon and ensure it appears on the same line as the title. Using flex and align-items means the icon and title will be aligned nicely beneath the image:

.recipe-card-title {
  display: flex;
  align-items: center;
  gap: 0.5rem;
}

Step 10: Create an Add Favourite Event Handler

In App.tsx, create an event handler for favoriting a recipe. This is what will get called when the user clicks the heart icon on an recipe that hasn't yet been favorited:

const addfavoriteRecipe = async (recipe) => {
  try {
    await API.addFavoriteRecipe(recipe);
    setFavoriteRecipes([...favoriteRecipes, recipe]);
  } catch (error) {
    console.log(error);
  }
};

Step 11: API Logic

In a new file called API.ts, create a function to handle the API call to save a favorite recipe. This will call our endpoint which we created earlier in the backend:

export const addFavoriteRecipe = async (recipe) => {
  const body = {
    recipeId: recipe.id,
  };
  const response = await fetch("http://localhost:5000/api/recipes/favourite", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error("Failed to save favorite");
  }
};

Step 12: Hook Up the Event Handler

Pass the event handler to the RecipeCard component:

<RecipeCard
  //.. other props
  onFavoriteButtonClick={favoriteRecipe}
/>

Step 13: Create the Remove Favorite Event Handler

Similarly, create an event handler for un-favoriting a recipe in App.tsx:

const removeFavoriteRecipe = async (recipe) => {
  try {
    await API.removeFavoriteRecipe(recipe);
    const updatedRecipes = favoriteRecipes.filter(
      (favRecipe) => favRecipe.id !== recipe.id
    );
    setFavoriteRecipes(updatedRecipes);
  } catch (error) {
    console.log(error);
  }
};

Step 14: API Logic

In API.ts, create a function to handle the API call to remove a favorite recipe. Again, this will call the backend API to remove a recipe which we created earlier:

export const removeFavoriteRecipe = async (recipe) => {
  const body = {
    recipeID: recipe.id,
  };
  const response = await fetch("http://localhost:5000/api/recipes/favourite", {
    method: "DELETE",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error("Failed to remove favorite");
  }
};

Step 15: Conditional Event Handler

Depending on if the user is "favoriting" or "unfavoriting" a recipe, we want to conditionally call either addFavoriteRecipe or removeFavoriteRecipe based on the favorited state:

<RecipeCard
  //.. other props
  onFavoriteButtonClick={isFavorite ? removeFavoriteRecipe : favoriteRecipe}
/>

Step 16: Determine the Favorited State

Before we can display the heart icon a favorited/non-favorited state, we need to know if the recipe is already a or not.

To do this, we determine whether a recipe is favorited by checking if it exists in the favoriteRecipes state array. Pass this information to RecipeCard:

const isFavorite = favoriteRecipes.some(
  (favRecipe) => favRecipe.id === recipe.id
);
<RecipeCard
  // ...other props
  isFavorite={isFavorite}
/>;

Step 17: Display the Favorited State

In RecipeCard, conditionally render a filled or outlined heart icon based on the isFavorite prop:

{
  isFavorite ? (
    <AiFillHeart size={25} color="red" />
  ) : (
    <AiOutlineHeart size={25} />
  );
}

How to Add CSS/Styling

Step 1: Prepare the Hero Image

We've added some basic styling so far, so lets complete the CSS so that our app looks polished!

Firstly obtain an image from a source like Pexels or any other image repository. This will be used in the Hero section of our app at the top, and will have our title overlaid on it. Ensure the image has a horizontal orientation for better handling of aspect ratios.

Place the image in the public folder of your project.

project-folder
│
└───public
    │   hero-image.jpeg

Step 2: Structure the Header

Open app.tsx and locate the JSX markup. Add a className of app-container to the top div element.

Inside the app-container div, add a new div with a className of header. Within the header div, add an img element with a src attribute pointing to your image, and a div element with a className of title containing the app's title.

<div className="app-container">
  <div className="header">
    <img src="/hero-image.jpeg" alt="Hero" />
    <div className="title">My Recipe App</div>
  </div>
  {/* ...rest of your code */}
</div>

Step 3: Style the Header

Open app.css and scroll to the top. Add the following CSS to style the app-container, header, img, and title elements. This makes the title appear on top of the image, with a translucent background:

.app-container {
  display: flex;
  flex-direction: column;
  gap: 2em;
}

.header {
  position: relative;
}

.header img {
  width: 100%;
  height: 500px;
  object-fit: cover;
  object-position: center;
  opacity: 0.5;
  border-radius: 1em;
}

.title {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  color: white;
  font-size: 2em;
  text-align: center;
  background-color: black;
  opacity: 0.8;
  padding: 0.5em 1.5em 0.5em 1.5em;
}

Step 4: Adjust the Layout

Add padding to the body element and use a media query to add margins on larger screens. We do this so our app doesn't appear to narrow on mobile devices. When the screen size reaches 768px, the media query will kick in and add margin to the left and right of our app, so that the app doesn't appear too wide.

body {
  padding: 5em 0;
  height: 100vh;
  background-color: #f0f0f0; /* or any color you prefer */
}

@media (min-width: 768px) {
  body {
    margin-left: 10em;
    margin-right: 10em;
  }
}

Step 5: Style Tabs Underline

Currently its not clear which tab the user has selected. What we want to do is add an orange underline to the selected tab. To do this, we can use a combination of CSS classes and conditional rendering.

Within app.tsx, locate your h1 elements representing tabs, and dynamically apply a className of tab-active based on the selected tab.

<h1 className={selectedTab === 'search' ? 'tab-active' : ''}>Search</h1>
<h1 className={selectedTab === 'favorites' ? 'tab-active' : ''}>Favorites</h1>

In app.css, define the tab-active class:

.tab-active {
  border-bottom: 4px solid orange; /* or any color you prefer */
  padding-bottom: 0.5em;
}

Step 6: Style the Search Bar

We want our search bar to take up the width of the container, and we want to add an icon instead of the search button, which makes our UI more interesting.

In app.tsx, locate the form element within the Search tab. Replace the text "Submit" in the button element with an icon from a library like React Icons.

<button>
  <AiOutlineSearch size={40} />
</button>

In app.css, style the form, input, and button elements:

form {
  display: flex;
  background-color: white;
  align-items: center;
}

input {
  padding: 0.5em;
  font-size: 2em;
  flex: 1;
  border: none;
}

input:focus {
  outline: none;
}

button {
  background-color: white;
  border: none;
  cursor: pointer;
}

Step 7: Implement a Responsive Recipe Card Grid

Currently our Recipe Cards are stacked horizontally. We'll use CSS grid to make the recipe cards appear in a grid layout, which will also make things more responsive.

Within app.tsx, create a new div with a className of recipe-grid just above where you map over your recipes, and place the logic to rendering the recipes inside this div.

<div className="recipe-grid">
  {recipes.map((recipe) => {
    const isFavourite = favouriteRecipes.some((favRecipe) => favRecipe.id === recipe.id);

    return (
      <RecipeCard
        key={recipe.id}
        recipe={recipe}
        onFavouriteButtonClick={isFavourite ? removeFavouriteRecipe : addFavouriteRecipe}
        onClick={() => setSelectedRecipe(recipe)}
        isFavourite={isFavourite}
      />
    );
  })}
</div>

In app.css, style the recipe-grid and recipe-card elements:

.recipe-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(400px, 1fr));
  gap: 2em;
}

.recipe-card {
  display: flex;
  flex-direction: column;
  justify-content: space-evenly;
  background-color: white;
  padding: 1em;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  position: relative;
  cursor: pointer;
  gap: 1.5em;
}

.recipe-card h3 {
  font-size: 1.5em;
  margin: 0;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

Step 8: Final Touches

Style the "View More" button to make sure it matches the style of our app, and is centered beneath our recipe grid:

.view-more-button {
  font-size: 1.5em;
  padding: 1em;
  font-weight: bold;
  margin: auto;
}

Conclusion

Congrats on making it to the end! Hopefully you've learned a few things about full stack development using React and Node.

If you enjoyed this project, you can find more at CodeCoyotes.com, where you can also send me a message if you need to get in contact.

Thanks for reading, see you in the next one!

Hello folks! 👋 Recently, I have been learning about Node.js. So I decided to share my learnings with you here. 👨‍💻

In this tutorial, we'll take a high-level look at Node.js – what it is, and what you can do with it.

We will be covering all the important Node concepts with hands-on examples and a lot of code snippets. This will give you the foundational knowledge required to get started with backend development with NodeJS.

This article is heavily inspired by the NodeJS and Express - Full Course on freeCodeCamp taught by John Smilga. You can check that out here if you'd like.

Here's what we'll cover in this guide:

• What Is NodeJS?
• Global Variables
• Modules
• Short Note On module.exports
• Types Of Modules
• Event Driven Programming
• Creating our first server
• Let's Serve Something Interesting!
• Conclusion

What is Node?

Node is an environment in which you can run JavaScript code "Outside the web browser". Node be like – "Hey y'all, you give your JS code to me and I'll run it 😎". It uses Google's V8 Engine to convert the JavaScript code to Machine Code.

Since Node runs JavaScript code outside the web browser, this means that it doesn't have access to certain features that are only available in the browser, like the DOM or the window object or even the localStorage.

This means that at any point in your code, you can't type in document.querySelector() or alert() as these will produce errors (This is what is shown in the below image).

Remember: Node is meant for server-side programming, while those browser features are meant for client-side programming.

Front-end folks don't be sad – there's more to it! Node provides you with lots of API's and Modules with which you can perform a variety of operations like File Handling, Creating Servers, and much more. Before diving into the NodeJS, first let's install it in our machine.

How to Install NodeJS

Installing NodeJS is straightforward. If you already have Node installed in your machine, you can skip this section. If not, then follow along.

Here are the steps to download NodeJS on your machine:

1. Navigate to https://nodejs.org/
2. Download the LTS Version of NodeJS for your operating system
3. Run the installer and follow the installation wizard. Simply answer Yes to all the questions.
4. Once the installation is complete, open a new terminal or command prompt window and run the following command to verify that NodeJS is installed correctly: node -v. If you see the version of NodeJS printed in your terminal, Congratulations! You have now successfully installed NodeJS on your machine.

Note: If you encounter any issues during the installation process, you can refer to the official NodeJS documentation for more detailed instructions and troubleshooting tips.

Global Variables

Let's start this article by learning about some variables present in NodeJS called Global Variables. These are basically variables which store some data and can be accessed from anywhere in your code – doesn't matter how deeply nested the code is.

You should know about these commonly used Global variables:

• __dirname: This variable stores the path to the current working directory.
• __filename: This variable stores the path to the current working file.

Let's use them and see what value they contain. For this, let's create a new folder called NodeJSTut in your Desktop and open it up with your favorite text editor (In the entire tutorial, we will be using VS Code). Create a new file called app.js and open up a new integrated VS Code Terminal.

Paste the following code in the app.js file and save it:

// __dirname Global Variable
console.log(__dirname);

// __filename Global Variable
console.log(__filename);

To run this code using Node, type in the following command in the terminal and press Enter: node app.js. You will see the absolute path to the present working directory and the path to the current file is printed in the terminal. This is what the output looks like in my case:

C:\Desktop\NodeJSTut
C:\Desktop\NodeJSTut\app.js

You can go ahead and create your own global variables which can be accessed from anywhere in your code. You can do so, like this:

// Define a global variable in NodeJS
global.myVariable = 'Hello World';

// Access the global variable
console.log(myVariable); // Output: Hello World

Modules in NodeJS

In Node.js, a module is essentially a reusable block of code that can be used to perform a specific set of tasks or provide a specific functionality. A module can contain variables, functions, classes, objects, or any other code that can be used to accomplish a particular task or set of tasks.

The primary purpose of using modules in Node.js is to help organize code into smaller, more manageable pieces. A modules can then be imported at any time and used flexibly which helps in creating reusable code components that can be shared across multiple projects.

To understand this, consider this example: Let's say you have defined lots of functions in your code that works with a huge volume of JSON data.

Losing your sleep and increased anxiety levels are common side effects of keeping all this stuff (functions + data + some other logic) in one single file.

So you, being a clever programmer, thought of making a separate file for the JSON data and a separate file for storing all the functions. Now, you can simply import the data and the functions whenever you want and use them accordingly. This method increases efficiency as your file size reduces drastically. This is the concept of modules!

Let's see how we can make our own modules. For this, we are going to write some code where we will be defining a function called sayHello() in a file called hello.js. This function will accept a name as the parameter and simply print a greeting message in the console.

We will then import it in another file called app.js and use it there. How interesting, right 😂? Let's check out the code:

This is the code in hello.js file:

function sayHello(name){
    console.log(`Hello ${name}`);
}

module.exports = sayHello

This is the code in app.js file:

const sayHello = require('./hello.js');

sayHello('John');
sayHello('Peter');
sayHello('Rohit');

The file hello.js can be called the module in this case. Every module has an object called exports which should contain all the stuff you want to export from this module like variables or functions. In our case, we are defining a function in the hello.js file and directly exporting it.

The app.js file imports the sayHello() function from hello.js and stores it in the sayHello variable. To import something from a module, we use the require() method which accepts the path to the module. Now we can simply invoke the variable and pass a name as a parameter. Running the code in app.js file will produce the following output:

Hello John
Hello Peter
Hello Rohit

Short Note on module.exports

In the previous section of the article, we saw how to use module.exports but I felt that it is important to understand how it works in a bit more detail. Hence, this section of the article is like a mini tutorial where we will see how we can export one variable/function as well as multiple variables and functions using module.exports. So, Let's get started:

module.exports is a special object in NodeJS that allows you to export functions, objects, or values from a module, so that other modules can access and use them. Here's an example of how to use module.exports to export a function from a module:

// myModule.js

function myFunction() {
  console.log('Hello from myFunction!');
}

module.exports = myFunction;

In this example, we define a function myFunction and then export it using module.exports. Other modules can now require this module and use the exported function:

// app.js

const myFunction = require('./myModule');

myFunction(); // logs 'Hello from myFunction!'

Everything seems fine now and life is good. But the problem arises when we have to export multiple functions and variables from a single file. The point is when you use module.exports multiple times in a single module, it will replace the previously assigned value with the new one. Consider this code:

// module.js

function myFunction() {
  console.log('Hello from myFunction!');
}

function myFunction2() {
  console.log('Hello from myFunction2!');
}

// First Export
module.exports = myFunction;

// Second Export
module.exports = myFunction2;

In this example, we first export myFunction(). But we then overwrite module.exports with a new function - myFunction2(). As a result, only the second export statement will take effect, and the myFunction() function will not be exported.

This problem can be solved if you assign module.exports to an object which contains all the functions you want to export, like this:

// myModule.js

function myFunction1() {
  console.log('Hello from myFunction1!');
}

function myFunction2() {
  console.log('Hello from myFunction2!');
}

module.exports = {
  foo: 'bar',
  myFunction1: myFunction1,
  myFunction2: myFunction2
};

In this example, we export an object with three properties: foo, myFunction1, and myFunction2. Other modules can require this module and access these properties:

// app.js

const myModule = require('./myModule');

console.log(myModule.foo); // logs 'bar'
myModule.myFunction1(); // logs 'Hello from myFunction1!'
myModule.myFunction2(); // logs 'Hello from myFunction2!'

To summarize, you can use module.exports as many times as you want in your NodeJS code, but you should be aware that each new assignment will replace the previous one. You should use an object to group multiple exports together.

Types Of Modules in Node

There are 2 types of modules in NodeJS:

• Built In Modules: These are modules included in Node by default, so you can use them without installation. You just need to import them and get started.
• External Modules: These are modules created by other developers which are not included by default. So you need to install them first before using them.

Here is an image of popular built-in modules in NodeJS and what can you do using them:

Let's go over each of these in more detail so you can learn more about what they do.

The OS Module

The OS Module (as its name implies) provides you methods/functions with which you can get information about your Operating System.

To use this module, the first step is to import it like this:

const os = require('os');

This is how you can use the OS Module to get information about the Operating System:👇

const os = require('os')

// os.uptime()
const systemUptime = os.uptime();

// os.userInfo()
const userInfo = os.userInfo();

// We will store some other information about my WindowsOS in this object:
const otherInfo = {
    name: os.type(),
    release: os.release(),
    totalMem: os.totalmem(),
    freeMem: os.freemem(),
}

// Let's Check The Results:
console.log(systemUptime);
console.log(userInfo);
console.log(otherInfo);

This is the output of the above code:

Note that the output shows information about the Windows Operating System running on my system. The output could be different from yours.

521105
{
    uid: -1,
    gid: -1,
    username: 'krish',
    homedir: 'C:\\Users\\krish',
    shell: null
}
{
    name: 'Windows_NT',
    release: '10.0.22621',
    totalMem: 8215212032,
    freeMem: 1082208256
}

Let's break down the above code and output:

• os.uptime() tells the system uptime in seconds. This function returns the number of seconds the system has been running since it was last rebooted. If you check the first line of the output: 521105 is the number of seconds, my system has been running since it was last rebooted. Of course, it will be different for you.
• os.userInfo() gives the information about the current user. This function returns an object with information about the current user including the user ID, group ID, username, home directory, and default shell. Below is the breakdown of the output in my case:

    {
        uid: -1,
        gid: -1,
        username: 'krish',
        homedir: 'C:\\Users\\krish',
        shell: null
    }

The uid and gid is set to -1 in Windows, because Windows does not have the concept of user IDs like Unix-based systems. The username of my OS is krish and the home directory is 'C:\\Users\\krish'. The shell is set to null because the concept of a default shell does not exist on Windows. Windows has a default command interpreter program called Command Prompt (cmd.exe), which runs commands and manages the system.

The other methods related to OS Module like os.type(), os.release() and so on, which you saw in the above code has been used within the otherInfo object. Here is a breakdown of what these methods do:

• os.type() - Tells the name of the Operating System
• os.release() - Tells the release version of the Operating System
• os.totalMem() - Tells the total amount of memory available in bytes
• os.freeMem() - Tells the total amount of free memory available in bytes

This is the information which the above methods display about my OS:

{
    name: 'WindowsNT', // Name of my OS
    release: '10.0.22621', // Release Version of my OS
    totalMem: 8215212032, // Total Memory Available in bytes (~ 8 GB)
     freeMem: 1082208256 // Free Memory Available in bytes (~ 1 GB) 
}

The PATH Module

The PATH module comes in handy while working with file and directory paths. It provides you with various methods with which you can:

• Join path segments together
• Tell if a path is absolute or not
• Get the last portion/segment of a path
• Get the file extension from a path, and much more!

You an see the PATH Module in action in the code below.

Code:

// Import 'path' module using the 'require()' method:
const path = require('path')

// Assigning a path to the myPath variable
const myPath = '/mnt/c/Desktop/NodeJSTut/app.js'

const pathInfo = {
    fileName: path.basename(myPath),
    folderName: path.dirname(myPath),
    fileExtension: path.extname(myPath),
    absoluteOrNot: path.isAbsolute(myPath),
    detailInfo: path.parse(myPath),
}

// Let's See The Results:
console.log(pathInfo);

Output:

{
  fileName: 'app.js',
  folderName: '/mnt/c/Desktop/NodeJSTut',
  fileExtension: '.js',
  absoluteOrNot: true,
  detailInfo: {
    root: '/',
    dir: '/mnt/c/Desktop/NodeJSTut',
    base: 'app.js',
    ext: '.js',
    name: 'app'
  }
}

Let's have a detailed breakdown of the above code and its output:

The first and foremost step to work with path module is to import it in the app.js file using the require() method.

Next, we are assigning a path of some file to a variable called myPath. This can be a path to any random file. For the purpose of understanding the path module, I chose this: /mnt/c/Desktop/NodeJSTut/app.js.

Using the myPath variable, we will understand the path module in detail. Let's check out the functions which this module has to offer and what can we do with it:

• path.basename(myPath): The basename() function accepts a path and returns the last part of that path. In our case, the last part of myPath is: app.js.
• path.dirname(myPath): The dirname() function selects the last part of the path provided to it and returns the path to it's parent's directory. In our case, since the last part of myPath is app.js. The dirname() function returns the path to the parent directory of app.js (the folder inside which app.js file lies), i.e, /mnt/c/Desktop/NodeJSTut. It can be also thought as: the dirname() function simply excludes the last part of the path provided to it and returns the leftover path.
• path.extname(myPath): This function checks for any extension on the last part of the provided path and it returns the file extension (if it exists), otherwise it returns an empty string: ''. In our case, since the last part is app.js and a file extension exists, we get '.js' as the output.
• path.isAbsolute(myPath): This tells whether the provided path is absolute or not. On Unix-based systems (such as macOS and Linux), an absolute path always starts with the forward slash (/). On Windows systems, an absolute path can start with a drive letter (such as C:) followed by a colon (:), or with two backslashes (\\). Since the value stored in myPath variable starts with /, therefore isAbsolute() returns true.

However, if you just change the myPath variable to this: Desktop/NodeJSTut/app.js (converting it to a relative path), isAbsolute() returns false.

• path.parse(myPath): This function accepts a path and returns an object which contains a detailed breakdown of the path provided to it. Here is what it returns when we provide the myPath variable to it:
• root: The root of the path (in this case, /).
• dir: The directory of the file (in this case, /mnt/c/Desktop/NodeJSTut).
• base: The base file name (in this case, app.js).
• ext: The file extension (in this case, .js).
• name: The base name of the file, without the extension (in this case, app).

Before continuing with the other functions of the path module, we need to understand something called path separator and the path structure.

You must have seen that the path to a same file looks different in different Operating Systems. For example, consider the path to a file named example.txt located in a folder called Documents on the desktop of a Windows user:

C:\Users\username\Desktop\Documents\example.txt

On the other hand, the file path to the same file for a user on a macOS system would look like this:

/Users/username/Desktop/Documents/example.txt

2 differences are to be noted here:

1. Difference in path separators: In Windows, file paths use the backslash (\) as the separator between directories, while in macOS/Linux (which is a Unix-based system), file paths use the forward slash (/) as the separator.
2. Difference in root directory of the users files: On Windows, the root directory for a user's files is commonly found at C:\Users\username, whereas on macOS and Linux, it is located at /Users/username/. While this holds true for most Windows, macOS, and Linux systems, there may be some variations in the exact location of the user's home directory based on the system's configuration.

With this in mind, let's move ahead and understand some other functions provided by the path module:

• path.sep: sep is a variable which contains the system specific path separator. For Windows machine: console.log(path.sep) prints \ in the console while in case of macOS or Linux, path.sep returns a forward slash ( / ).
• path.join(<paths>): The path.join() function accepts path(s) as strings. It then joins those paths using the system specific path separator and returns the joined path. For example, consider this code:

console.log(path.join('grandParentFolder', 'parentFolder', 'child.txt'))

The above code prints different results for different Operating Systems.
In Windows, it will give this output: grandParentFolder\parentFolder\child.txt while in macOS/Linux, it will give this output: grandParentFolder/parentFolder/child.txt. Note that the difference is only in the path separators - backward slash and forward slash.

• path.resolve(<paths>): This function works in a similar way as compared to path.join(). The path.resolve() function just joins the different paths provided to it using the system specific path separator and then appends the final output to the absolute path of the present working directory.

Suppose you are a Windows user and the absolute path to your present working directory is this: C:\Desktop\NodeJSTut, If you run this code:

console.log(path.resolve('grandParentFolder', 'parentFolder', 'child.txt'));

You will see the following output in the console:

C:\Desktop\NodeJSTut\grandParentFolder\parentFolder\child.txt

The same is applicable to a macOS or a Linux user. It's just the difference in the absolute path of the present working directory and the path separator.

The FS Module

This module helps you with file handling operations such as:

• Reading a file (sync or async way)
• Writing to a file (sync or async way)
• Deleting a file
• Reading the contents of a director
• Renaming a file
• Watching for changes in a file, and much more

Let's perform some of these tasks to see the fs (File System) module in action below:

How to create a directory using fs.mkdir()

The fs.mkdir() function in Node.js is used to create a new directory. It takes two arguments: the path of the directory to be created and an optional callback function that gets executed when the operation is complete.

• path: Here, path refers to the location where you want to create a new folder. This can be an absolute or a relative path. In my case, the path to the present working directory (the folder I am currently in), is: C:\Desktop\NodeJSTut. So, Let's create a folder in the NodeJSTut directory called myFolder.
• callback function: The purpose of the callback function is to notify that the directory creation process has completed. This is necessary because the fs.mkdir() function is asynchronous, meaning that it does not block the execution of the rest of the code while the operation is in progress. Instead, it immediately returns control to the callback function, allowing it to continue executing other tasks. Once the directory has been created, the callback function is called with an error object (if any) and any other relevant data related to the operation. In the below code, we are just using it to display a success message in the console or any error.

// Import fs module
const fs = require('fs');

// Present Working Directory: C:\Desktop\NodeJSTut
// Making a new directory called ./myFolder:

fs.mkdir('./myFolder', (err) => {
    if(err){
        console.log(err);
    } else{
        console.log('Folder Created Successfully');
    }
})

After executing the above code, you will see a new folder called myFolder created in the NodeJSTut directory.

How to create and write to a file asynchronously using fs.writeFile()

After the myFolder directory is created successfully, it's time to create a file and write something to it by using the fs module.

There are basically 2 ways of doing this:

• Synchronous Approach: In this approach, we create a file and write the data to it in a blocking manner, which means that NodeJS waits for the creation and write operation to complete before moving on to the next line of code. If an error occurs during this process, it throws an exception that must be caught using try...catch.
• Asynchronous Approach: In this approach, we create and write data to a file in a non-blocking manner, which means that NodeJS does not wait for the write operation to complete before moving on to the next line of code. Instead, it takes a callback function that gets called once the entire process is completed. If an error occurs during the write operation, the error object is passed to the callback function.

In this tutorial, we will be using the fs.writeFile() function which follows the asynchronous approach.

writeFile() is a method provided by the fs (file system) module in Node.js. It is used to write data to a file asynchronously. The method takes three arguments:

1. The path of the file to write to (including the file name and extension)
2. The data to write to the file (as a string or buffer)
3. An optional callback function that is called once the write operation is complete or an error occurs during the write operation.

When writeFile() is called, Node.js creates a new file or overwrites an existing file at the specified path. It then writes the provided data to the file and closes it. Since the method is asynchronous, the write operation does not block the event loop, allowing other operations to be performed in the meantime.

Below is the code where we create a new file called myFile.txt in the myFolder directory and write this data to it: Hi,this is newFile.txt.

const fs = require('fs');

const data = "Hi,this is newFile.txt";

fs.writeFile('./myFolder/myFile.txt', data, (err)=> {
    if(err){
        console.log(err);
        return;
    } else {
        console.log('Writen to file successfully!');
    }
})

Since newFile.txt didn't exist previously, Hence the writeFile() function created this file for us on the provided path and then wrote the value in the data variable to the file. Suppose this file already existed. In that case, writeFile() will just open the file, erase all the existing text present in it and then write the data to it.

The problem with this code is: when you run the same code multiple times, it erases the previous data that is already present in newFile.txt and writes the data to it.

In case you do not want the original data to get deleted and just want the new data to be added/appended at the end of the file, you need to make a little change in the above code by adding this "options object": {flag: 'a'} as the third parameter to writeFile() – like this:

const fs = require('fs');

const data = 'Hi,this is newFile.txt';

fs.writeFile('./myFolder/myFile.txt', data, {flag: 'a'}, (err) => {
    if(err){
        console.log(err);
        return;
    } else {
        console.log('Writen to file successfully!');
    }
})

Once you run the above code again and again, you will see that the myFile.txt has the value of the data variable written to it multiple times. This is because the object (3rd parameter): {flag: 'a'} indicates the writeFile() method to append the data at the end of the file instead of erasing the previous data present in it.

How to read a file asynchronously using fs.readFile()

After creating and writing to the file, it's time we learn how to read the data present in the file using the fs module.

Again there are 2 ways of doing this: Synchronous approach and the Asynchronous approach (just like the previous function). Here we are going to use the readFile() function provided by fs module which performs the reading operation asynchronously.

The readFile() function takes 3 parameters:

1. The path to the file which is to be read.
2. The encoding of the file.
3. The callback function that gets executed once the reading operation is completed or if any error occurs during the reading operation. It accepts 2 parameters: first parameter stores the file data (if read operation is successful) and the second parameter stores the error object (if read operation fails due to some error).

The readFile() function is very intuitive and once called, it reads the data present in the provided file according to the given encoding. If the read operation is successful, it returns the data to the callback function and if not, it will return the error occurred.

In the below code, we read the contents of the file - myFile.txt which we had created while learning the previous function and then log the data stored in it in the console.

const fs = require('fs');

fs.readFile('./myFolder/myFile.txt', {encoding: 'utf-8'}, (err, data) => {
    if(err){
        console.log(err);
        return;
    } else {
        console.log('File read successfully! Here is the data');
        console.log(data);
    }
})

It is to be noted here that the encoding property is set to 'utf-8'. At this point, some of you may not know about the encoding property, So Let's understand it in a bit more detail:

The encoding parameter in the fs.readFile() method of Node.js is used to specify the character encoding used to interpret the file data. By default, if no encoding parameter is provided, the method returns a raw buffer.

If the readFile() method is called without providing an encoding parameter, you will see a result similar to this printed in the console:

<Buffer 54 68 69 73 20 69 73 20 73 6f 6d 65 20 64 61 74 61 20 69 6e 20 61 20 66 69 6c 65>

This raw buffer is difficult to read and interpret as it represents the contents of the file in binary form. To convert the buffer to a readable string, you can specify an encoding parameter when calling readFile().

In our case, we specified the 'utf8' encoding as the second parameter of the readFile() method. This tells Node.js to interpret the file contents as a string using the UTF-8 character encoding, thus you see the original data printed in the console. Other common encodings that can be used with readFile() include:

• 'ascii': Interpret the file contents as ASCII-encoded text.
• 'utf16le': Interpret the file contents as 16-bit Unicode text in little-endian byte order.
• 'latin1': Interpret the file contents as ISO-8859-1 (also known as Latin-1) encoded text.

Reading and Writing to a File Synchronously

Up until now, you have learned how to write to and read the data from a file asynchronously. But there are synchronous alternatives to the 2 functions we learnt above, namely: readFileSync() and writeFileSync().

Note that since these are synchronous operations, they need to be wrapped in a try...catch block. In case the operations fail for some reason, the errors thrown will be caught by the catch block.

In the below code, we first create a new file: ./myFolder/myFileSync.txt and write to it using the writeFileSync() method. Then we read the contents of the file using the readFileSync() method and print the data in the console:

const fs = require('fs');

try{
    // Write to file synchronously
    fs.writeFileSync('./myFolder/myFileSync.txt', 'myFileSync says Hi');
    console.log('Write operation successful');

    // Read file synchronously
    const fileData = fs.readFileSync('./myFolder/myFileSync.txt', 'utf-8');
    console.log('Read operation successful. Here is the data:');
    console.log(fileData);

} catch(err){
    console.log('Error occurred!');
    console.log(err);
}

When you run the above code, a new file called myFileSync.txt is created in the myFolder directory and it contains the following text in it: myFileSync says Hi. This is the output printed in the console:

Write operation successful
Read operation successful. Here is the data:
myFileSync says Hi

How to read the contents of a directory using fs.readdir()

If you have been following along until now, you will see that we currently have 2 files in the myFolder directory, i.e, myFile.txt and myFileSync.txt. The fs module provides you with readdir() function using which you can read the contents of a directory (the files and folders present in the directory).

The readdir() function accepts 2 parameters:

• The path of the folder whose contents are to be read.
• Callback function which gets executed once the operation is completed or if any error occurs during the operation. This function accepts 2 parameters: The first one which accepts the error object (if any error occurs) and the second parameter which accepts an array of the various files and folders present in the directory whose path has been provided.

In the code below, we are reading the contents of the myFolder directory and printing the result in the console.

const fs = require('fs');

fs.readdir('./myFolder', (err, files) => {
    if(err){
        console.log(err);
        return;
    }
    console.log('Directory read successfully! Here are the files:');
    console.log(files);
})

This is what we get as output when we run the above code:

[ 'myFile.txt', 'myFileSync.txt' ]

How to rename a file using fs.rename()

The fs.rename() method in Node.js is used to rename a file or directory. The method takes two arguments, the current file path and the new file path, and a callback function that is executed when the renaming is complete.

Here's the syntax for the fs.rename() method:

fs.rename(oldPath, newPath, callback);

where:

• oldPath (string) - The current file path
• newPath (string) - The new file path
• callback (function) - A callback function to be executed when the renaming is complete. This function takes an error object as its only parameter.

Let's rename the newFile.txt file to newFileAsync.txt:

const fs = require('fs');

fs.rename('./newFolder/newFile.txt', './newFolder/newFileAsync.txt', (err)=>{
    if(err){
        console.log(err);
        return;
    }
    console.log('File renamed successfully!')
})

Once you run the above code, you will see that the newFile.txt gets renamed to newFileAsync.txt.

Note that you should only provide valid paths (absolute or relative) to the rename() function and not just the names of the files. Remember it's oldPath and newPath and NOT oldName and newName.

For example, consider this code: fs.rename('./newFolder/newFile.txt', 'newFileAsync.txt', ...rest of the code). In this case, since we did not provide a proper path in the 2nd parameter, rename() assumes that the path to the newly named file should be: ./newFileAsync.txt. Thus, it basically removes the newFile.txt from the newFolder directory, renames the file to newFileAsync.txt and moves it to the current working directory.

How to delete a file using fs.unlink()

Last but not the least, we have the fs.unlink() function which is used to delete a file. It takes in 2 parameters:

• The path of the file which you want to delete, and
• The callback function which gets executed once the delete operation is over or if any error occurs during the operation.

Running the following code deletes the newFileSync.txt file present in the myFolder directory:

const fs = require('fs');

fs.unlink('./myFolder/myFileSync.txt', (err) => {
    if(err){
        console.log(err);
        return;
    }
    console.log('File Deleted Successfully!')
})

Event-Driven Programming

Ok, before we move forward to learn the HTTP Module and create our own servers, it's important to know about something called "Event driven programming".

Event-driven programming is a programming paradigm where program flow is largely determined by events or user actions, rather than by the program's logic.

In this type of programming, the program listens for events, and when they occur, it executes some code/function that should run in response to that event.

An event could be anything from a mouse click or a button press to the arrival of new data in the system.

The below image demonstrates how event driven programming works. In this form of programming, we write some code which constantly listens for a particular event and once that event occurs, we run some code in response to it.

In this section of the tutorial we will be learning about events in NodeJS. Although we may not be using events directly for our day-to-day coding tasks, but a lot of NodeJS modules use the concept of events under the hood. This is why it becomes important to be aware about it.

To implement Event Driven Programming in NodeJS, You need to remember 2 things:

• There is a function called emit() which causes an event to occur.
  For example, emit('myEvent') emits/causes an event called myEvent.

• There is another function called on() which is used to listen for a particular event and when this event occurs, the on() method executes a listener function in response to it. For example, Consider this code: on('myEvent', myFunction): Here we are listening for an event called myEvent and when this event takes place, we run the myFunction listener function in response to it.

We can access the on() and emit() functions by creating an instance of the EventEmitter class. The EventEmitter class can be imported from a built-in package called events.

In the below code, we are listening for the userJoined event and once this event takes place, we run the welcomeUser() function using the on() method and we emit the userJoined event using the emit() method:

// Importing 'events' module and creating an instance of the EventEmitter Class
const EventEmitter = require('events');
const myEmitter = new EventEmitter();

// Listener Function - welcomeUser()
const welcomeUser = () => {
    console.log('Hi There, Welcome to the server!');
}

// Listening for the userJoined event using the on() method
myEmitter.on('userJoined', welcomeUser);

// Emitting the userJoined event using the emit() method
myEmitter.emit('userJoined');

Points to Note:

There are 3 points you should note while working with events in Node.
Each point in shown in action in the corresponding code snippets:

• There can be multiple on()'s for a single emit():

Check out the following code, where multiple on() functions are listening for a single event to happen (userJoined event) and when this event is emitted in the last line of the code using the emit() function, you will see that the all the listener functions which were attached to the on() function get's executed:

// Importing `events` module and creating an instance of EventEmitter class
const EventEmitter = require('events');
const myEmitter = new EventEmitter();

// Listener Function 1: sayHello
const sayHello = () => {
    console.log('Hello User');
}

// Listener Function 2: sayHi
const sayHi = () => {
    console.log('Hi User');
}

// Listener Function 3: greetNewYear
const greetNewYear = () => {
    console.log('Happy New Year!');
}

// Subscribing to `userJoined` event
myEmitter.on('userJoined', sayHello);
myEmitter.on('userJoined', sayHi);
myEmitter.on('userJoined', greetNewYear);

// Emiting the `userJoined` Event
myEmitter.emit('userJoined');

You can think of it this way: Each time the userJoined event is emitted, a notification is sent to all the on() functions listening for the event and then all of them will run their corresponding listener functions: sayHello, sayHi, greetNewYear.

Thus, when you run the code, you will see the following output printed in the console:

Hello User
Hi User
Happy New Year!

• The emit() can also contain arguments which will be passed to the listener functions:

In the following code, We are using the on() method to subscribe to an event called birthdayEvent and when this event is emitted, we run the greetBirthday() function in response to it.

The extra parameters mentioned in the emit() function, gets passed as parameters to all the listener functions which will run in response to the birthdayEvent. Therefore John and 24 gets passed as parameters to the greetBirthday() function.

const EventEmitter = require('events');
const myEvent = new EventEmitter();

// Listener function
const greetBirthday = (name, newAge) => {
    // name = John
    // newAge = 24
    console.log(`Happy Birthday ${name}. You are now {newAge}!`);
}

// Listening for the birthdayEvent
myEmitter.on('birthdayEvent', greetBirthday);

// Emitting the birthdayEvent with some extra parameters
myEmitter.emit('birthdayEvent', 'John', '24');

The following output will be seen printed in the console: Happy Birthday John, You are now 24!.

• The emit() function should always be defined after the on() function(s):

The entire process of communication between on() and emit() works like this: Before emitting any event, you need to make sure that all the listener functions have subscribed/registered to that event. Any function which is registered as a listener after the event has been emitted, will not be executed.

Check out the following code where this process is studied in detail:

const EventEmitter = require('events');
const myEmitter = new EventEmitter();

// Listener Function 1 - sayHi
const sayHi = () => {
    console.log('Hi User');
}

// Listener Function 2 - sayHello
const sayHello = () => {
    console.log('Hello User');
}

// Registering sayHi function as listener
myEmitter.on('userJoined', sayHi);

// Emitting the event
myEmitter.emit('userJoined');

// Registering sayHello function as listener
myEmitter.on('userJoined', sayHello);

When the above code is executed, we see Hi User printed in the console but Hello User is not printed.

The reason behind this is: First we had registered the sayHi function as the listener using myEmitter.on('userJoined', sayHi). Next we emit the userJoined event which results in execution of the sayHi function. In the next line we are registering the sayHello function as the listener, but it's already too late to do this because userJoined event has been emitted. This signifies the importance of defining all the on() functions before we emit the event using emit().

You can also think of it this way: When you use emit() to trigger an event, NodeJS looks for any corresponding on() methods that have been defined in your code above the emit() method. If it finds any, it will execute them in order to handle the event.

The HTTP Module

Let's move forward and learn the HTTP Module which helps you create Web Servers.

HTTP stands for Hypertext Transfer Protocol. It is used to transfer data over the internet which allows communication between clients and servers.

Suppose you want to watch some YouTube videos, you go to your web browser and type in: https://youtube.com, and then YouTube's home page gets displayed on your screen. This entire process happened because of communication between your machine (client) and YouTube's Server. The client, in this case, your machine requested for YouTube's home page and the server sent back the HTML, CSS and JS Files as the response.

The client sends a request to the server in the form of a URL with some additional information, such as headers and query parameters.

The server processes the request, performs necessary operations, and sends a response back to the client. The response contains a status code, headers, and the response body with the requested data.

_Source: https://course-api.com/slides/_

Components Of Request-Response

Both the Request (sent by client to the server) and the Response (sent by server to the client) comprises of 3 parts:

1. The Status Line: This is the first line of the request or response. It contains information about the message, such as the method used, URL, protocol version, and so on.
2. The Header: This is a collection of key-value pairs, separated by colon.
   The headers include additional information about the message such as the content type, content length, caching information, and so on.
3. The Body: The Body contains the actual data being sent or received. In the case of requests, it might contain form data or query parameters. In the case of responses, it could be HTML, JSON, XML, or any other data format.

The 3 components of a Request and Response are described in much more detail in the below image:

_Source: https://course-api.com/slides/_

What are HTTP Methods?

HTTP methods, also known as HTTP verbs, are actions that a Client can perform on a Server. The 4 HTTP Methods are:

• GET: Retrieves a resource from the server
• POST: Inserts a resource in the server
• PUT: Updates an existing resource in the server
• DELETE: Deletes a resource from the server

This might sound complicated, but let's try to understand these methods with the help of an example:

1. GET: Retrieves a resource from the server
   When you enter http://www.google.com in your web browser's address bar and press enter, your browser sends a HTTP GET request to the Google server asking for the HTML content of the Google homepage. That's then rendered and displayed by your browser.
2. POST: Inserts a resource in the server
   Imagine you're filling out a registration form to create an account on Google. When you submit the form, your browser sends a POST request to Google's server with the data you typed in the form fields like: Username, Age, Birthdate, Address, Phone Number, Email, Gender and so on.

The server will then create a new user account in its database storing all the information sent to it using the POST Request. So a POST request is used to add/insert a resource in the server.

3. PUT: Updates an existing resource in the server
   Now imagine you want to update your Google account's password. You would send a PUT request to the server with the new password. The server would then update your user account in its database with the new password.
4. DELETE: Deletes a resource from the server
   Finally, imagine you want to delete your Google user account. You would send a DELETE request to the server indicating that you want your account to be deleted. The server would then delete your user account from its database.

Note that these are just examples. The actual requests and their purposes may vary.

To see more examples of HTTP Methods, you can refer this image:

_Source: https://course-api.com/slides/_

What is a Status Code?

HTTP status codes are three-digit numbers that indicate the status of a HTTP request made to a server. They are server responses that provide information about the request's outcome. Here are some of the most common HTTP status codes and what they represent:

Let's Create a Server

Finally let's move to the good part 🥳🔥 and learn how to create a Web Server using the http module:

Step 1: Import the http module like this:

const http = require('http');

Step 2: The http module provides you with http.createServer() function which helps you create a server. This function accepts a callback function with 2 parameters – req (which stores the incoming request object) and res which stands for the response to be sent by the server. This callback function gets executed every time someone hits the server.

This is how we can create a server using the createServer() function:

const http = require('http');

const server = http.createServer((req, res) => {
    res.end('Hello World');
})

Note: res.send() is a function attached on the res object using which we can send some data back to the client. Here once we are done setting up the server, you will see a Hello World message in your web browser.

Step 3: Listening the server at some port using the listen() method.

The listen() function in Node.js http module is used to start a server that listens for incoming requests. It takes a port number as an argument and binds the server to that port number so that it can receive incoming requests on that port.

In the below code, we use the listen() function to start the server and bind it to port 5000. The second argument to the listen() function is a callback function that is executed when the server starts listening on the specified port. We are using this callback function just to display a success message in the console.

const http = require('http');

const server = http.createServer((req, res) => {
    res.end('Hello World');
})

server.listen(5000, () => {
    console.log('Server listening at port 5000');
})

You are likely to see a Hello World message when you visit this URL: http://localhost:5000/.

If you try to visit some other port like 5001 (http://localhost:5001/), which is not bound to your server, you won't see any response because your server is not listening on that port. You will likely receive an error message stating that the connection to the server could not be established.

At this point, we've made a server that renders a simple Hello World message every time someone tries to access it. This is quite good but there is a problem....

The problem is that for every route, the server sends the same message. For example, if I try to access the about page or the contact page, still the server shows the same message:

• http://localhost:5000/ -> Hello World
• http://localhost:5000/about -> Hello World
• http://localhost:5000/contact -> Hello World

There is a simple way to fix this: there's a property called url in the req object which gives the URL of the request or in other words it tells you about the resource the client is trying to access.

Suppose if I type in: http://localhost:5000/about in my web browser's search bar, this means I am performing a GET Request on the server and I am trying to access the /about page. So In this case the value of req.url will be /about.

Similarly for the below requests, the value of req.url will be:

We can use some conditionals if...else along with the req.url property to make our server respond to different requests differently. This is how we can achieve this:

const http = require('http');

const server = http.createServer((req, res) => {
    if(req.url === '/'){
        res.end('This is my Home Page');
    } else if(req.url === '/about'){
        res.end('This is my About Page');
    } else if(req.url === '/contact'){
        res.end('This is my Contact Page');
    } else {
        res.end('404, Resource Not Found');
    }
})

server.listen(5000, () => {
    console.log('Server listening at port 5000');
})

Now we have a perfect server that responds to different requests differently. We are sending back responses using a method called res.end(). But there is an even better way of sending back a response in which we can add on 2 more methods along with res.end():

1. res.writeHead() – This method is used to send the response headers to the client. The status code and headers like content-type can be set using this method.
2. res.write() – This method is used to send the response body to the client.
3. res.end() – This method is used to end the response process.

Below is the modified code where we added the writeHead() and write() methods along with end() method:

const http = require('http');

const server = http.createServer((req, res) => {
    if(req.url === '/'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write('<h1>Home Page</h1>');
        res.end();
    } else if(req.url === '/about'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write('<h1>About Page</h1>');
        res.end();
    } else if(req.url === '/contact'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write('<h1>Contact Page</h1>');
        res.end();
    } else {
        res.writeHead(404, {'content-type': 'text/html'});
        res.write('<h1>404, Resource Not Found <a href="/">Go Back Home</a></h1>');
        res.end();
    }
})

server.listen(5000, () => {
    console.log('Server listening at port 5000');
})

The below image shows what the server sends back as response when we visit multiple URL's:

Let's break down what's happening in the above code:

1. Here we are responding differently to different incoming requests by using the req.url property.
2. In every response, we are doing 3 things:
   – Setting the response header using the res.writeHead() method. Here we provide 2 parameters to res.writeHead(): the status code and an object which has the content-type property set to text/html
   – Setting the response body using the res.write() method. Note that instead of sending simple messages, we are actually sending some HTML code in this case,
   – And closing the response process using the res.end() method.
3. In case of resources like: /, /about and /contact the status code is set to 200 which means that the request to access a resource was successful. But if the client tries to access some other resource, they simply get back an error message and the status code is set to 404.
4. Here the 'content-type': 'text/html' is a way of telling the browser how it should interpret and display the response. In this case, we are telling the browser to interpret the response as some HTML code. There are different content-type's for different types of responses:
   – To send back JSON data as a response, we need to set the content-type to application/json
   – To send back CSS as a response, the content-type should be text/css
   – To send back JavaScript code as a response, the content-type should be text/javascript, and so on...

Setting the content type is very important as it determines how the web browser interprets the response. For example: if we just change the content-type from text/html to text/plain, this is how the response will be displayed in the web browser:

Let's Serve Something Interesting

Up until now you've learned how to set up web servers but we haven't built anything interesting. So let's add some fun to our lives.

In the last section of this tutorial, we will be serving this navbar:

Since this is not a front-end related tutorial, we will not be building this navbar from scratch. Instead, you can head over to this GitHub repo and copy the contents of the navbar-app directory and set it up locally: John Smilga's GitHub repo. The idea is to:

1. Set up the navbar-app folder locally
2. Use the fs module to read the contents of the HTML, CSS, JS file and the Logo
3. Using the http Module to render the files when someone tries to access the / route or the home page. So Let's Get Started:

In the below code, we are using the fs module's readFileSync() method to read the contents of the HTML, CSS, JS file and the Logo.

Note that we are going to serve the contents of the file and not the file itself. So readFileSync() comes into picture.

Then, we serve the contents of the HTML file (stored in homePage variable) using the res.write() method. Remember to set the content-type as text/html as we are serving HTML content. We have also set up responses for /about route and also a 404 page.

const http = require('http');
const fs = require('fs');

// Get the contents of the HTML, CSS, JS and Logo files
const homePage = fs.readFileSync('./navbar-app/index.html');
const homeStyles = fs.readFileSync('./navbar-app/style.css');
const homeLogo = fs.readFileSync('./navbar-app/logo.svg');
const homeLogic = fs.readFileSync('./navbar-app/browser-app.js');

// Creating the Server
const server = http.createServer((req, res) => {
    const url = req.url;
    if(url === '/'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write(homePage);
        res.end();
    } else if(url === '/about'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write(<h1>About Page</h1>);
        res.end();
    } else{
        res.writeHead(200, {'content-type': 'text/html'});
        res.write(<h1>404, Resource Not Found</h1>);
        res.end();
    }
})

server.listen(5000, () => {
    console.log('Server listening at port 5000');
})

When you run this code using node app.js command, you will see these responses sent by the server for the following routes:

We see that the other routes work fine, but the home page doesn't look as we expected. The problem is that we only see the HTML Structure of the navbar being displayed and not the other stuff like the CSS, logo, and JavaScript.

Let's see what the bug is. We can check what requests are being made by the web browser to the server by modifying the above code like this:

// ... above code
const server = http.createServer((req, res) => {
    const url = req.url;
    console.log(url);

    // ... rest of the code
})

Here we are simply printing the url of the request being made by the client to the server.

Once we refresh the page, we see that initially the browser asks for the home page and makes a GET request with the / URL. Afterward it makes 3 more requests:

• /style.css – asking for the CSS file
• /browser-app.js – asking for the JS file
• /logo.svg – asking for the logo

From this, we can infer how browsers work.

The browser makes request for the contents of the / path and the server just sends back the HTML content. Once the browser receives the HTML content, it interprets it and starts displaying the elements. While parsing HTML, if the browser encounters any additional resource like a CSS page or JS page, it will make a request to the server for the same.

Since we are not sending the CSS, JS and Logo in the response, we do not see them on the screen. We can fix this by adding some more if()s in the code and sending those resources which the browser asks for and BOOM – this bug is fixed.

const http = require('http');
const fs = require('fs');

// Get the contents of the HTML, CSS, JS and Logo files
const homePage = fs.readFileSync('./navbar-app/index.html');
const homeStyles = fs.readFileSync('./navbar-app/style.css');
const homeLogo = fs.readFileSync('./navbar-app/logo.svg');
const homeLogic = fs.readFileSync('./navbar-app/browser-app.js');

// Creating the Server
const server = http.createServer((req, res) => {
    const url = req.url;
    if(url === '/'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write(homePage);
        res.end();
    } else if(url === '/style.css'){
        res.writeHead(200, {'content-type': 'text/css'});
        res.write(homeStyles);
        res.end();
    } else if(url === '/browser-app.js'){
        res.writeHead(200, {'content-type': 'text/javascript'});
        res.write(homeLogic);
        res.end();
    } else if(url === '/logo.svg'){
        res.writeHead(200, {'content-type': 'image/svg+xml'});
        res.write(homeLogo);
        res.end();
    } else if(url === '/about'){
        res.writeHead(200, {'content-type': 'text/html'});
        res.write(<h1>About Page</h1>);
        res.end();
    } else{
        res.writeHead(200, {'content-type': 'text/html'});
        res.write(<h1>404, Resource Not Found</h1>);
        res.end();
    }
})

server.listen(5000, () => {
    console.log('Server listening at port 5000');
})

Now we can see the HTML, CSS, Logo and the JS Functionality present:

Conclusion

With this we come to the end of this tutorial – I hope you liked it and learned a lot about Node.

Do share your learnings from this guide on Twitter and LinkedIn (#LearnInPublic) and follow freeCodeCamp for more such informative coding articles.

Connect with me on Twitter: Twitter - Krish4856, DMs Open.

See you next time 👋 ❤️ ✨

I recently wrote this article where I explained the main differences between common API types nowadays. And this tutorial aims to show you an example of how you can fully implement a GraphQL API.

We'll cover basic setup and architecture with Node and Apollo GraphQL, unit testing with Supertest, seeing how we can consume the API from a React front-end app using Apollo client and finally documenting the API using Apollo sandbox.

Keep in mind we won't go too deep into how each technology works. The goal here is to give you a general overview of how a GraphQL API works, how its pieces interact, and what a full implementation might consist of.

Let's go!

Table of Contents

• What is GraphQL?

• Core GraphQL concepts

  • Object Types

  • Queries

  • Mutations

  • Resolvers

  • Schemas

  • TLDR and comparison with equivalent REST concepts

• How to Build a GraphQL API with Node and Apollo GraphQL

• How to Test a GraphQL API with Supertest

• How to Consume a GraphQL API on a Front-end React App

• How to Document a GraphQL API with Apollo sandbox

• Wrapping up

What is GraphQL?

GraphQL is a query language and runtime for APIs that was developed by Facebook in 2012. It was released to the public in 2015 and has since gained popularity as an alternative to REST APIs.

GraphQL was originally developed by Facebook as a way to simplify data fetching for their mobile applications. They needed a way to make complex data requests from the server without causing performance issues or over-fetching data. GraphQL was born out of the need to solve these problems.

GraphQL was released as an open-source project in 2015 and has since gained popularity in the developer community. It is now supported by many development tools and frameworks, including Apollo, Prisma, and Hasura.

Main Characteristics:

1. Strongly Typed: GraphQL APIs are strongly typed, which means that each field has a specific data type. This makes it easier to validate and handle data on the client and server sides.

2. Query Language: GraphQL has its own query language that allows clients to specify exactly what data they need. This reduces over-fetching of data and improves performance.

3. Single Endpoint: GraphQL APIs have a single endpoint, which means that clients can fetch all the data they need from a single request.

4. Declarative: GraphQL APIs are declarative, which means that clients specify what they want, not how to get it. This allows for more efficient and flexible data fetching.

5. Schema-Driven: GraphQL APIs are schema-driven, which means that the schema defines the structure of the data and the available queries and mutations. This makes it easier for developers to understand and work with the API.

Pros:

• Efficient Data Fetching: GraphQL APIs allow clients to fetch only the data they need, reducing over-fetching and improving performance.

• Strongly Typed: GraphQL APIs are strongly typed, making it easier to validate and handle data.

• Single Endpoint: GraphQL APIs have a single endpoint, reducing the complexity of the API and making it easier to work with.

• Schema-Driven: GraphQL APIs are schema-driven, which makes it easier for developers to understand and work with the API.

Cons:

• Complexity: GraphQL APIs can be more complex to set up and work with compared to REST APIs.

• Caching: Caching can be more challenging with GraphQL APIs due to the flexible nature of the API.

• Learning Curve: GraphQL requires a learning curve for both developers and clients, as it has its own query language and approach to data fetching.

Best for:

• Efficient and flexible needs: GraphQL is well-suited for building applications that require efficient and flexible data fetching, such as mobile and web applications.

• Complex data requirements: It is particularly useful in situations where there are complex data requirements and where over-fetching data can cause performance issues.

So to recap, GraphQL is a query language and runtime for APIs that provides efficient and flexible data fetching capabilities.

While it can be more complex to set up and work with compared to REST APIs, it offers benefits such as strongly typed data, single endpoints, and schema-driven development. It is well-suited for building applications with complex data requirements and where efficient data fetching is important.

Core GraphQL Concepts

Before we jump into building stuff, there are some core GraphQL concepts you need to understand in order to know what you're doing and how the code will work.

Object Types

In GraphQL, an Object Type is a complex type that represents a collection of fields. Object Types are used to define the structure of data that can be queried and mutated through a GraphQL API.

Each Object Type has a unique name and a set of fields, where each field has a name and a type. The type of a field can be a scalar type (such as Int, String, or Boolean), another Object Type, or a list of another type.

If you're familiar with Typescript and interfaces, this might ring a bell or two for you.

Here's an example of an Object Type that represents a "User" in a social media application:

type User {
  id: ID!
  name: String!
  email: String!
  friends: [User!]!
}

The ! sign means the field is mandatory.

In this example, the "User" Object Type has four fields: "id", "name", "email", and "friends". The "id" field has a type of ID, which is a built-in scalar type in GraphQL that represents a unique identifier. The "name" and "email" fields have a type of String, and the "friends" field has a type of a list of "User" Objects.

Here's another example of an Object Type that represents a "Book" in a library application:

type Book {
  id: ID!
  title: String!
  author: Author!
  genre: String!
  published: Int!
}

In this example, the "Book" Object Type has five fields: "id", "title", "author", "genre", and "published". The "id" field has a type of ID, the "title" and "genre" fields have a type of String, the "published" field has a type of Int, and the "author" field has a type of an "Author" Object.

Object Types can be used to define the structure of data that is returned from a query or mutation in a GraphQL API. For example, a query that returns a list of users might look like this:

query {
  users {
    id
    name
    email
    friends {
      id
      name
    }
  }
}

In this query, the "users" field returns a list of "User" Objects, and the query specifies which fields to include in the response.

Queries

In GraphQL, a query is a request for specific data from the server. The query specifies the shape of the data that the client wants to receive, and the server responds with the requested data in the same shape.

A query in GraphQL follows a similar structure to the shape of the data it expects to receive. It consists of a set of fields that correspond to the properties of the data the client wants to retrieve. Each field can also have arguments that modify the data returned.

Here's an example of a simple query in GraphQL:

query {
  user(id: "1") {
    name
    email
    age
  }
}

In this example, the query is requesting information about a user with the ID of "1". The fields specified in the query are "name", "email", and "age", which correspond to the properties of the user object.

The response from the server would be in the same shape as the query, with the requested data returned in the corresponding fields:

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "johndoe@example.com",
      "age": 25
    }
  }
}

Here, the server has returned the requested data about the user in the "name", "email", and "age" fields. The data is contained in a "data" object to differentiate it from any errors or other metadata that may be included in the response.

Mutations

In GraphQL, mutations are used to modify or create data on the server. Like queries, mutations specify the shape of the data being sent to and received from the server. The main difference is that while queries only read data, mutations can both read and write data.

Here's an example of a simple mutation in GraphQL:

mutation {
  createUser(name: "Jane Doe", email: "janedoe@example.com", age: 30) {
    id
    name
    email
    age
  }
}

In this example, the mutation is creating a new user on the server with the name "Jane Doe", email "janedoe@example.com", and age 30. The fields specified in the mutation are "id", "name", "email", and "age", which correspond to the properties of the user object.

The response from the server would be in the same shape as the mutation, with the newly created user data returned in the corresponding fields:

{
  "data": {
    "createUser": {
      "id": "123",
      "name": "Jane Doe",
      "email": "janedoe@example.com",
      "age": 30
    }
  }
}

Here, the server has returned the data about the newly created user in the "id", "name", "email", and "age" fields.

Mutations can also be used to update or delete data on the server. Here's an example of a mutation that updates a user's name:

mutation {
  updateUser(id: "123", name: "Jane Smith") {
    id
    name
    email
    age
  }
}

In this example, the mutation is updating the user with the ID of "123" to have the name "Jane Smith". The fields specified in the mutation are the same as in the previous example.

The response from the server would be the updated user data:

{
  "data": {
    "updateUser": {
      "id": "123",
      "name": "Jane Smith",
      "email": "janedoe@example.com",
      "age": 30
    }
  }
}

Mutations in GraphQL are designed to be composable, meaning that multiple mutations can be combined into a single request. This allows clients to perform complex operations with a single network round-trip.

Resolvers

In GraphQL, a resolver is a function responsible for fetching the data for a specific field defined in a GraphQL schema. Resolvers are the bridge between the schema and the data source. The resolver function receives four parameters: parent, args, context, and info.

• parent: The parent object for the current field. In nested queries, it refers to the parent field's value.

• args: The arguments passed to the current field. It is an object with key-value pairs of the argument names and their values.

• context: An object shared across all resolvers for a particular request. It contains information about the request such as the currently authenticated user, database connection, etc.

• info: Contains information about the query including the field name, alias, and the query document AST.

Here's an example of a resolver function for a User type's posts field:

const resolvers = {
  User: {
    posts: (parent, args, context, info) => {
      return getPostsByUserId(parent.id);
    },
  },
};

In this example, User is a GraphQL object type with a posts field. When the posts field is queried, the resolver function is called with the parent object User, any arguments passed, the context object, and query information. In this example, the resolver function calls a function getPostsByUserId to fetch the posts for the current user.

Resolvers can also be used for mutations to create, update or delete data. Here's an example of a resolver function for a createUser mutation:

const resolvers = {
  Mutation: {
    createUser: (parent, args, context, info) => {
      const user = { name: args.name, email: args.email };
      const createdUser = createUser(user);
      return createdUser;
    },
  },
};

In this example, Mutation is a GraphQL object type with a createUser mutation field. When the mutation is invoked, the resolver function is called with the parent object, arguments passed, context object, and query information. In this example, the resolver function calls a function createUser to create a new user with the given name and email, and returns the newly created user.

Schemas

In GraphQL, a schema is a blueprint that defines the structure of the data that can be queried in the API. It defines the available types, fields, and operations that can be performed on those types.

GraphQL schemas are written in the GraphQL Schema Definition Language (SDL), which uses a simple syntax to define the types and fields available in the API. The schema is typically defined in the server-side code and then used to validate and execute incoming queries.

Here's an example of a simple GraphQL schema definition:

type Book {
  id: ID!
  title: String!
  author: String!
  published: Int!
}

type Query {
  books: [Book!]!
  book(id: ID!): Book
}

type Mutation {
  addBook(title: String!, author: String!, published: Int!): Book!
  updateBook(id: ID!, title: String, author: String, published: Int): Book
  deleteBook(id: ID!): Book
}

In this schema, we have three types: Book, Query, and Mutation. The Book type has four fields: id, title, author, and published. The Query type has two fields: books and book, which can be used to retrieve a list of books or a specific book by ID, respectively. The Mutation type has three fields: addBook, updateBook, and deleteBook, which can be used to create, update, or delete books.

Note that each field has a type, which can be a built-in scalar type like String or Int, or a custom type like Book. The ! after a type indicates that the field is non-nullable, meaning it must always return a value (that is, it cannot be null).

TLDR and Comparison with Equivalent REST Concepts

• Object Types: In GraphQL, Object Types are used to define the data that can be queried from an API, similar to how the response data model is defined in REST APIs. However, unlike REST, where data models are often defined in different formats (for example, JSON or XML), GraphQL Object Types are defined using a single language-agnostic syntax.

• Queries: In GraphQL, queries are used to fetch data from an API, similar to HTTP GET requests in REST APIs. However, unlike REST APIs, where multiple requests may be required to fetch nested data, GraphQL queries can be used to fetch nested data in a single request.

• Mutations: In GraphQL, mutations are used to modify data in an API, similar to HTTP POST, PUT, and DELETE requests in REST APIs. However, unlike REST APIs, where different endpoints may be required to perform different modifications, GraphQL mutations are performed through a single endpoint.

• Resolvers: In GraphQL, resolvers are used to specify how to fetch data for a particular field in a query or mutation. Resolvers are similar to controller methods in REST APIs, which are used to fetch data from a database and return it as a response.

• Schemas: In GraphQL, a schema is used to define the data that can be queried or mutated from an API. It specifies the types of data that can be requested, how they can be queried, and what mutations are allowed. In REST APIs, schemas are often defined using OpenAPI or Swagger, which specify the endpoints, request and response types, and other metadata for an API.

Overall, GraphQL and REST APIs differ in how they handle data fetching and modification.

REST APIs rely on multiple endpoints and HTTP methods to fetch and modify data, whereas GraphQL uses a single endpoint and queries/mutations to accomplish the same.

GraphQL's use of a single schema to define the data model of an API makes it easier to understand and maintain compared to REST APIs, which often require multiple documentation formats to describe the same data model.

How to Build a GraphQL API with Node and Apollo GraphQL

Our Tools

Node.js is an open-source, cross-platform, back-end JavaScript runtime environment that allows developers to execute JavaScript code outside of a web browser. It was created by Ryan Dahl in 2009 and has since become a popular choice for building web applications, APIs, and servers.

Node.js provides an event-driven, non-blocking I/O model that makes it lightweight and efficient, allowing it to handle large amounts of data with high performance. It also has a large and active community, with many libraries and modules available to help developers build their applications more quickly and easily.

Apollo GraphQL is a full-stack platform for building GraphQL APIs. It provides tools and libraries that simplify the process of building, managing, and consuming GraphQL APIs.

The core of the Apollo GraphQL platform is the Apollo Server, a lightweight and flexible server that makes it easy to build scalable and performant GraphQL APIs. The Apollo Server supports a wide range of data sources, including databases, REST APIs, and other services, making it easy to integrate with existing systems.

Apollo also provides a number of client libraries, including the Apollo Client for web and mobile, which simplifies the process of consuming GraphQL APIs. The Apollo Client makes it easy to query and mutate data, and provides advanced features like caching, optimistic UI, and real-time updates.

In addition to the Apollo Server and Apollo Client, Apollo provides a number of other tools and services, including a schema management platform, a GraphQL analytics service, and a set of developer tools for building and debugging GraphQL APIs.

If you're new to GraphQL or to Apollo itself, I really recommend you check out their docs. They're some of the best out there in my opinion.

Our Architecture

For this project we'll follow a layers architecture in our codebase. Layers architecture is about dividing concerns and responsibilities into different folders and files, and allowing direct communication only between certain folders and files.

The matter of how many layers should your project have, what names should each layer have, and what actions should it handle is all a matter of discussion. So let's see what I think is a good approach for our example.

Our application will have five different layers, which will be ordered in this way:

Application layers

• The application layer will have the basic setup of our server and the connection to our schema and resolvers (the next layer).

• The schema and resolvers layer will have the type definitions for our data and the connection to our queries and mutations (the next layer).

• The queries and mutations layer will have the actual logic we want to perform in each of our queries and mutations and the connection to the model layer (the next layer, you get the idea...)

• The model layer will hold the logic for interacting with our mock database.

• Finally, the persistence layer is where our database will be.

An important thing to keep in mind is that in these kinds of architectures, there's a defined communication flow between the layers that has to be followed for it to make sense.

This means that a request first has to go through the first layer, then the second, then the third and so on. No request should skip layers because that would mess with the logic of the architecture and the benefits of organization and modularity it gives us.

If you'd like to know some other API architecture options, I recommend this software architecture article I wrote a while ago.

The Code

Before jumping to the code, let's mention what we'll actually build. We'll be building an API for a pet shelter business. This pet shelter needs to register the pets that are staying in the shelter, and for that we'll perform basic CRUD operations (create, read, update and delete).

We're using the exact same example we used in my article about fully implementing a REST API. If you're interested in reading that too, this should help to compare concepts between REST and GraphQL, and understand its differences and similarities. ;)

Now let's get this thing going. Create a new directory, hop in to it and start a new Node project by running npm init -y. For our GraphQL server we'll need two more dependencies, so run npm i @apollo/server and npm i graphql too.

App.js

In the root of your project, create an app.js file and drop this code in it:

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { typeDefs, resolvers } from './pets/index.js'

// The ApolloServer constructor requires two parameters: your schema
// definition and your set of resolvers.
const server = new ApolloServer({
    typeDefs,
    resolvers
})

// Passing an ApolloServer instance to the `startStandaloneServer` function:
//  1. creates an Express app
//  2. installs your ApolloServer instance as middleware
//  3. prepares your app to handle incoming requests
const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 }
})

console.log(`🚀  Server ready at: ${url}`)

Here we're setting up our Apollo server, by passing it our typeDefs and resolvers (we'll explain those in a sec), and then starting the server in port 4000.

Next, go ahead and create this folder structure in your project:

Our folder structure

index.js

Within the index.js file put this code:

import { addPet, editPet, deletePet } from './mutations/pets.mutations.js'
import { listPets, getPet } from './queries/pets.queries.js'

// A schema is a collection of type definitions (hence "typeDefs")
// that together define the "shape" of queries that are executed against your data.
export const typeDefs = `#graphql
  # OBJECT TYPES
  # This "Pet" type defines the queryable fields for every pet in our data source.
  type Pet {
    id: ID!
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  # INPUT TYPES
  # Define the input objects for addPet and editPet mutations
  input PetToEdit {
    id: ID!
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  input PetToAdd {
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "pets" query returns an array of zero or more pets.
  # QUERY TYPES
  type Query {
    pets: [Pet],
    pet(id: ID!): Pet
  }

  # MUTATION TYPES
  type Mutation {
    addPet(petToAdd: PetToAdd!): Pet,
    editPet(petToEdit: PetToEdit!): Pet,
    deletePet(id: ID!): [Pet],
  }
`

export const resolvers = {
    // Resolvers for Queries
    Query: {
        pets: () => listPets(),
        pet: (_, { id }) => getPet(id)
    },

    // Resolvers for Mutations
    Mutation: {
        addPet: (_, { petToAdd }) => addPet(petToAdd),
        editPet: (_, { petToEdit }) => editPet(petToEdit),
        deletePet: (_, { id }) => deletePet(id)
    }
}

Here we have two main things: typeDefs and resolvers.

typeDefs defines the types for the data that can be queried in our API (in our case that's the pet object), as well as the input for queries/mutations (in our case that's PetToEdit and PetToAdd).

Lastly, it also defines the available queries and mutations for our API, declaring their names, as well as their input and return values. In our case we have two queries (pets and pet) and three mutations (addPet, editPet and deletePet).

resolvers contain the actual implementation of our queries and mutations types. Here we're declaring each query and mutation, and indicating what each should do. In our case, we're linking them with the queries/mutations we're importing from our queries/mutations layer.

pets.queries.js

In your pets.queries.js file drop this:

import { getItem, listItems } from '../models/pets.models.js'

export const getPet = id => {
    try {
        const resp = getItem(id)
        return resp
    } catch (err) {
        return err
    }
}

export const listPets = () => {
    try {
        const resp = listItems()
        return resp
    } catch (err) {
        return err
    }
}

As you can see, this file is very simple. It declares the functions that are imported in the index.js file and links them to the functions declared in the models layer.

pets.mutations.js

Same goes for our pets.mutations.js file, but with mutations now.

import { editItem, addItem, deleteItem } from '../models/pets.models.js'

export const addPet = petToAdd => {
    try {
        const resp = addItem(petToAdd)
        return resp
    } catch (err) {
        return err
    }
}

export const editPet = petToEdit => {
    try {
        const resp = editItem(petToEdit?.id, petToEdit)
        return resp
    } catch (err) {
        return err
    }
}

export const deletePet = id => {
    try {
        const resp = deleteItem(id)
        return resp
    } catch (err) {
        return err
    }
}

pets.models.js

Now go to the models folder and create a pets.models.js file with this code in it:

import db from '../../db/db.js'

export const getItem = id => {
    try {
        const pet = db?.pets?.filter(pet => pet?.id === parseInt(id))[0]
        return pet
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const listItems = () => {
    try {
        return db?.pets
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const editItem = (id, data) => {
    try {
        const index = db.pets.findIndex(pet => pet.id === parseInt(id))

        if (index === -1) throw new Error('Pet not found')
        else {
            data.id = parseInt(data.id)
            db.pets[index] = data
            return db.pets[index]
        }
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const addItem = data => {
    try {
        const newPet = { id: db.pets.length + 1, ...data }
        db.pets.push(newPet)
        return newPet
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const deleteItem = id => {
    try {
        // delete item from db
        const index = db.pets.findIndex(pet => pet.id === parseInt(id))

        if (index === -1) throw new Error('Pet not found')
        else {
            db.pets.splice(index, 1)
            return db.pets
        }
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

These are the functions responsible for interacting with our data layer (database) and returning the corresponding information to our controllers.

Database

We wont use a real database for this example. Instead we'll just use a simple array that will work just fine for example purposes, though our data will of course reset every time our server does.

In the root of our project, create a db folder and a db.js file with this code in it:

const db = {
    pets: [
        {
            id: 1,
            name: 'Rex',
            type: 'dog',
            age: 3,
            breed: 'labrador',
        },
        {
            id: 2,
            name: 'Fido',
            type: 'dog',
            age: 1,
            breed: 'poodle',
        },
        {
            id: 3,
            name: 'Mittens',
            type: 'cat',
            age: 2,
            breed: 'tabby',
        },
    ]
}

export default db

As you can see, our db object contains a pets property whose value is an array of objects, each object being a pet. For each pet, we store an id, name, type, age and breed.

Now go to your terminal and run nodemon app.js. You should see this message confirming your server is alive: 🚀 Server ready at: [http://localhost:4000/](http://localhost:4000/).

How to Test a GraphQL API with Supertest

Now that our server is up and running, let's implement a simple test suit to check if our queries and mutations behave as expected.

If you're not familiar with automated testing, I recommend you read this introductory article I wrote a while ago.

Our Tools

SuperTest is a JavaScript library that is used for testing HTTP servers or web applications that make HTTP requests. It provides a high-level abstraction for testing HTTP, allowing developers to send HTTP requests and make assertions about the responses received, making it easier to write automated tests for web applications.

SuperTest works with any JavaScript testing framework, such as Mocha or Jest, and can be used with any HTTP server or web application framework, such as Express.

SuperTest is built on top of the popular testing library Mocha, and uses the Chai assertion library to make assertions about the responses received. It provides an easy-to-use API for making HTTP requests, including support for authentication, headers, and request bodies.

SuperTest also allows developers to test the entire request/response cycle, including middleware and error handling, making it a powerful tool for testing web applications.

Overall, SuperTest is a valuable tool for developers who want to write automated tests for their web applications. It helps ensure that their applications are functioning correctly and that any changes they make to the codebase do not introduce new bugs or issues.

The Code

First we'll need to install some dependencies. To save up terminal commands, go to your package.json file and replace your devDependencies section with the code below. Then run npm install.

  "devDependencies": {
    "@babel/core": "^7.21.4",
    "@babel/preset-env": "^7.21.4",
    "babel-jest": "^29.5.0",
    "jest": "^29.5.0",
    "jest-babel": "^1.0.1",
    "nodemon": "^2.0.22",
    "supertest": "^6.3.3"
  }

Here we're installing the supertest and jest libraries, which we need for our tests to run, plus some babel stuff we need for our project to correctly identify which files are test files.

Still in your package.json, add this script:

  "scripts": {
    "test": "jest"
  },

To end with the boilerplate, in the root of your project, create a babel.config.cjs file and drop this code in it:

//babel.config.cjs
module.exports = {
    presets: [
      [
        '@babel/preset-env',
        {
          targets: {
            node: 'current',
          },
        },
      ],
    ],
  };

Now let's write some actual tests! Within your pets folder, create a pets.test.js file with this code in it:

import request from 'supertest'

const graphQLEndpoint = 'http://localhost:4000/'

describe('Get all pets', () => {
    const postData = {
        query: `query Pets {
            pets {
                id
                name
                type
                age
                breed
            }
        }`
    }

    test('returns all pets', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.pets).toEqual([
                    {
                        id: '1',
                        name: 'Rex',
                        type: 'dog',
                        age: 3,
                        breed: 'labrador'
                    },
                    {
                        id: '2',
                        name: 'Fido',
                        type: 'dog',
                        age: 1,
                        breed: 'poodle'
                    },
                    {
                        id: '3',
                        name: 'Mittens',
                        type: 'cat',
                        age: 2,
                        breed: 'tabby'
                    }
                ])
            })
    })
})

describe('Get pet detail', () => {
    const postData = {
        query: `query Pet {
            pet(id: 1) {
                id
                name
                type
                age
                breed
            }
        }`
    }

    test('Return pet detail information', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.pet).toEqual({
                    id: '1',
                    name: 'Rex',
                    type: 'dog',
                    age: 3,
                    breed: 'labrador'
                })
            })
    })
})

describe('Edit pet', () => {
    const postData = {
        query: `mutation EditPet($petToEdit: PetToEdit!) {
            editPet(petToEdit: $petToEdit) {
                id
                name
                type
                age
                breed
            }
        }`,
        variables: {
            petToEdit: {
                id: 1,
                name: 'Rexo',
                type: 'dogo',
                age: 4,
                breed: 'doberman'
            }
        }
    }

    test('Updates pet and returns it', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.editPet).toEqual({
                    id: '1',
                    name: 'Rexo',
                    type: 'dogo',
                    age: 4,
                    breed: 'doberman'
                })
            })
    })
})

describe('Add pet', () => {
    const postData = {
        query: `mutation AddPet($petToAdd: PetToAdd!) {
            addPet(petToAdd: $petToAdd) {
                id
                name
                type
                age
                breed
            }
        }`,
        variables: {
            petToAdd: {
                name: 'Salame',
                type: 'cat',
                age: 6,
                breed: 'pinky'
            }
        }
    }

    test('Adds new pet and returns the added item', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.addPet).toEqual({
                    id: '4',
                    name: 'Salame',
                    type: 'cat',
                    age: 6,
                    breed: 'pinky'
                })
            })
    })
})

describe('Delete pet', () => {
    const postData = {
        query: `mutation DeletePet {
            deletePet(id: 2) {
                id,
                name,
                type,
                age,
                breed
            }
        }`
    }

    test('Deletes given pet and returns updated list', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.deletePet).toEqual([
                    {
                        id: '1',
                        name: 'Rexo',
                        type: 'dogo',
                        age: 4,
                        breed: 'doberman'
                    },
                    {
                        id: '3',
                        name: 'Mittens',
                        type: 'cat',
                        age: 2,
                        breed: 'tabby'
                    },
                    {
                        id: '4',
                        name: 'Salame',
                        type: 'cat',
                        age: 6,
                        breed: 'pinky'
                    }
                ])
            })
    })
})

This a test suite for our GraphQL API. It uses the supertest library to make HTTP requests to the API endpoint (http://localhost:4000/) and verifies that the API responds correctly to various queries and mutations.

The code has five different test cases:

1. Get all pets: This test queries the API for all pets and verifies that the response matches an expected list of pets.

2. Get pet detail: This test queries the API for the details of a specific pet and verifies that the response matches the expected details for that pet.

3. Edit pet: This test performs a mutation to edit the details of a specific pet and verifies that the response matches the expected edited details for that pet.

4. Add pet: This test performs a mutation to add a new pet and verifies that the response matches the expected details for the newly added pet.

5. Delete pet: This test performs a mutation to delete a specific pet and verifies that the response matches the expected list of pets after the deletion.

Each test case includes a postData object that contains the GraphQL query or mutation to be sent to the API endpoint as well as any necessary variables.

The actual HTTP request is made using the request function from the supertest library, which sends a POST request to the API endpoint with the postData object in the request body. The response is then parsed as JSON and the test case verifies that the response matches the expected result using the expect function from the Jest testing framework.

Now go to your terminal, run npm test, and you should see all your tests passing:

> jest

 PASS  pets/pets.test.js
  Get all pets
    ✓ returns all pets (15 ms)
  Get pet detail
    ✓ Return pet detail information (2 ms)
  Edit pet
    ✓ Updates pet and returns it (1 ms)
  Add pet
    ✓ Adds new pet and returns the added item (1 ms)
  Delete pet
    ✓ Deletes given pet and returns updated list (1 ms)

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        0.607 s, estimated 1 s
Ran all test suites.

How to Consume a GraphQL API on a Front-end React App

Now we know our server is running and behaving as expected. Let's see some more realistic example of how our API might be consumed by a front end app.

For this example, we'll use a React application, and Apollo client to send and process our requests.

Our Tools

React is a popular JavaScript library for building user interfaces. It allows developers to create reusable UI components and efficiently update and render them in response to changes in application state.

Regarding Apollo client, we've introduced it already.

Side comment – we're using Apollo client here since it's a very popular tool and it makes sense to use the same set of libraries both in front and back-end. If you're interested in other possible ways a GraphQL API can be consumed from a front-end React App, Reed Barger has a pretty cool article on this topic.

The Code

Let's create our React app by running yarn create vite and following the terminal prompts. Once that's done, run yarn add react-router-dom (which we'll use to setup basic routing in our app).

App.jsx

Put this code within your App.jsx file:

import { Suspense, lazy, useState } from 'react'
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import './App.css'

const PetList = lazy(() => import('./pages/PetList'))
const PetDetail = lazy(() => import('./pages/PetDetail'))
const EditPet = lazy(() => import('./pages/EditPet'))
const AddPet = lazy(() => import('./pages/AddPet'))

function App() {
    const [petToEdit, setPetToEdit] = useState(null)

    return (
        <div className='App'>
            <Router>
                <h1>Pet shelter</h1>

                <Routes>
                    <Route
                        path='/'
                        element={
                            <Suspense fallback={<></>}>
                                <PetList />
                            </Suspense>
                        }
                    />

                    <Route
                        path='/:petId'
                        element={
                            <Suspense fallback={<></>}>
                                <PetDetail setPetToEdit={setPetToEdit} />
                            </Suspense>
                        }
                    />

                    <Route
                        path='/:petId/edit'
                        element={
                            <Suspense fallback={<></>}>
                                <EditPet petToEdit={petToEdit} />
                            </Suspense>
                        }
                    />

                    <Route
                        path='/add'
                        element={
                            <Suspense fallback={<></>}>
                                <AddPet />
                            </Suspense>
                        }
                    />
                </Routes>
            </Router>
        </div>
    )
}

export default App

Here we're just defining our routes. We'll have 4 main routes in our app, each corresponding to a different view:

• One to see the whole list of pets.

• One to see the detail of a single pet.

• One to edit a single pet.

• One to add a new pet to the list.

Besides, we have a button to add a new pet and a state that will store the information of the pet we want to edit.

Next, create a pages directory with these files in it:

Folder structure

main.js

Before jumping into our pages, we have to set up the Apollo client library. Run yarn add @apollo/client and yarn add graphql to install the necessary dependencies.

The go to the main.js file and drop this code in it:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client'

const client = new ApolloClient({
  uri: 'http://localhost:4000/',
  cache: new InMemoryCache(),
})

ReactDOM.createRoot(document.getElementById('root')).render(
  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>
)

Here we're initializing the ApolloClient, passing its constructor a configuration object with the uri and cache fields:

• uri specifies the URL of our GraphQL server.

• cache is an instance of InMemoryCache, which Apollo Client uses to cache query results after fetching them.

Then we wrap our App component with our ApolloProvider. This allows any component in our component tree to use the hooks provided by Apollo client, much like React Context works. ;)

Mutations and queries

In the root of your project, create this folder structure:

Folder structure

In these two files we'll declare the request bodies we'll use for our queries and mutations. I like to separate this into different files because it gives use a clear view of the different kinds of request we have in our app, and it also keeps our component's code cleaner.

In the queries.js file drop this:

import { gql } from '@apollo/client'

export const GET_PETS = gql`
    query Pets {
        pets {
            id
            name
            type
            breed
        }
    }
`

export const GET_PET = gql`
    query Pet($petId: ID!) {
        pet(id: $petId) {
            id
            name
            type
            age
            breed
        }
    }
`

And in the mutations.js file drop this:

import { gql } from '@apollo/client'

export const DELETE_PET = gql`
    mutation DeletePet($deletePetId: ID!) {
        deletePet(id: $deletePetId) {
            id
        }
    }
`

export const ADD_PET = gql`
    mutation AddPet($petToAdd: PetToAdd!) {
        addPet(petToAdd: $petToAdd) {
            id
            name
            type
            age
            breed
        }
    }
`

export const EDIT_PET = gql`
    mutation EditPet($petToEdit: PetToEdit!) {
        editPet(petToEdit: $petToEdit) {
            id
            name
            type
            age
            breed
        }
    }
`

As you can see, the syntax for queries and mutations is fairly similar. Request bodies are written in GraphQL query language, which is used to define the structure and data types of data that can be requested from a GraphQL API.

• GraphQL Query Syntax:

export const GET_PETS = gql`
    query Pets {
        pets {
            id
            name
            type
            breed
        }
    }
`

This query is named Pets and it requests data from the pets field. The fields id, name, type, and breed are requested from each Pet object returned by the API.

In GraphQL, queries always start with the keyword query and are followed by the name of the query, if provided. The fields requested are enclosed in curly braces and can be nested to request data from related fields.

• GraphQL Mutation Syntax:

export const ADD_PET = gql`
    mutation AddPet($petToAdd: PetToAdd!) {
        addPet(petToAdd: $petToAdd) {
            id
            name
            type
            age
            breed
        }
    }
`

This mutation is named AddPet and sends a new Pet object to be added to the API via the addPet mutation. The $petToAdd variable is defined as a required input of type PetToAdd. When the mutation is executed, the input variable will be passed in as an argument to the addPet mutation. The mutation then returns the id, name, type, age, and breed fields for the newly created Pet object.

In GraphQL, mutations always start with the keyword mutation and are followed by the name of the mutation, if provided. The fields requested in the mutation response are also enclosed in curly braces.

Note that both queries and mutations in GraphQL can accept variables as input, which are defined in the query or mutation body using a special syntax ($variableName: variableType!). These variables can be passed in when the query or mutation is executed, allowing for more dynamic and reusable queries and mutations.

PetList.jsx

Let's start with the file responsible for rendering the whole list of pets:

import { Link } from 'react-router-dom'
import { useQuery } from '@apollo/client'
import { GET_PETS } from '../api/queries'

function PetList() {
    const { loading, error, data } = useQuery(GET_PETS)

    return (
        <>
            <h2>Pet List</h2>

            <Link to='/add'>
                <button>Add new pet</button>
            </Link>

            {loading && <p>Loading...</p>}
            {error && <p>Error: {error.message}</p>}

            {data?.pets?.map(pet => {
                return (
                    <div key={pet?.id}>
                        <p>
                            {pet?.name} - {pet?.type} - {pet?.breed}
                        </p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detail</button>
                        </Link>
                    </div>
                )
            })}
        </>
    )
}

export default PetList

This code defines a React functional component called PetList that fetches a list of pets from a GraphQL API using the useQuery hook provided by the @apollo/client library. The query used to fetch the pets is defined in a separate file called queries.js, which exports a GraphQL query called GET_PETS.

The useQuery hook returns an object with three properties: loading, error, and data. These properties are destructured from the object and used to conditionally render different UI elements depending on the status of the API request.

If loading is true, a loading message is displayed on the screen. If error is defined, an error message is displayed with the specific error message returned by the API. If data is defined and contains an array of pets, each pet is displayed in a div with their name, type, and breed. Each pet div also contains a link to view more details about the pet.

The useQuery hook works by executing the GET_PETS query and returning the result as an object with the loading, error, and data properties. When the component first renders, loading is true while the query is being executed. If the query is successful, loading is false and data is populated with the results. If the query encounters an error, error is populated with the specific error message.

As you can see, managing requests with Apollo client is really nice and simple. And the hooks it provides, save us quite a bit of code normally used to execute requests, store it's response and handle errors.

Remember that to make calls to our server, we must have it up and running by running nodemon app.js in our server project terminal.

Just to show there's no weird magic going on here, if we go to our browser, open the dev tools and go to the network tab, we could see our app is making a POST request to our server endpoint. And that the payload is our request body in the form of a string.

The POST request

Request body

This means that if we wanted to, we could also consume our GraphQL API by using fetch, like following:

import { Link } from 'react-router-dom'
import { useEffect, useState } from 'react'

function PetList() {

    const [pets, setPets] = useState([])

    const getPets = () => {
        fetch('http://localhost:4000/', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                query: `
                query Pets {
                    pets {
                    id
                    name
                    type
                    breed
                    }
                }
                `
            })
        })
            .then(response => response.json())
            .then(data => setPets(data?.data?.pets))
            .catch(error => console.error(error))
    }

    useEffect(() => {
        getPets()
    }, [])

    return (
        <>
            <h2>Pet List</h2>

            <Link to='/add'>
                <button>Add new pet</button>
            </Link>

            {pets?.map(pet => {
                return (
                    <div key={pet?.id}>
                        <p>
                            {pet?.name} - {pet?.type} - {pet?.breed}
                        </p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detail</button>
                        </Link>
                    </div>
                )
            })}
        </>
    )
}

export default PetList

If you check your network tab again, you should see still the same POST request with the some request body.

Of course this approach is not very practical as it requires more lines of code to perform the same thing. But it's important to know that libraries like Apollo only give us a declarative API to work with and simplify our code. Beneath it all we're still working with regular HTTP requests.

PetDetail.jsx

Now let's go to the PetDetail.jsx file:

import { useEffect } from 'react'
import { useParams, Link } from 'react-router-dom'
import { useQuery, useMutation } from '@apollo/client'
import { GET_PET } from '../api/queries'
import { DELETE_PET } from '../api/mutations'

function PetDetail({ setPetToEdit }) {
    const { petId } = useParams()

    const { loading, error, data } = useQuery(GET_PET, {
        variables: { petId }
    })

    useEffect(() => {
        if (data && data?.pet) setPetToEdit(data?.pet)
    }, [data])

    const [deletePet, { loading: deleteLoading, error: deleteError, data: deleteData }] = useMutation(DELETE_PET, {
        variables: { deletePetId: petId }
    })

    useEffect(() => {
        if (deleteData && deleteData?.deletePet) window.location.href = '/'
    }, [deleteData])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Pet Detail</h2>

            <Link to='/'>
                <button>Back to list</button>
            </Link>

            {(loading || deleteLoading) && <p>Loading...</p>}

            {error && <p>Error: {error.message}</p>}
            {deleteError && <p>deleteError: {deleteError.message}</p>}

            {data?.pet && (
                <>
                    <p>Pet name: {data?.pet?.name}</p>
                    <p>Pet type: {data?.pet?.type}</p>
                    <p>Pet age: {data?.pet?.age}</p>
                    <p>Pet breed: {data?.pet?.breed}</p>

                    <div style={{ display: 'flex', justifyContent: 'center', aligniItems: 'center' }}>
                        <Link to={`/${data?.pet?.id}/edit`}>
                            <button style={{ marginRight: 10 }}>Edit pet</button>
                        </Link>

                        <button style={{ marginLeft: 10 }} onClick={() => deletePet()}>
                            Delete pet
                        </button>
                    </div>
                </>
            )}
        </div>
    )
}

export default PetDetail

This component loads the detail info of the pet by executing a query in a very similar way than the previous component.

Moreover, it executes the mutation needed to delete the pet register. You can see that for this we're using the useMutation hook. It's quite similar to useQuery, but besides the loading, error and data values it also provides a function to execute our query after a given event.

You can see that for this mutation hook we're passing an object as second parameter, containing the variables this mutation requires. In this case, it's the id of the pet register we want to delete.

const [deletePet, { loading: deleteLoading, error: deleteError, data: deleteData }] = useMutation(DELETE_PET, {
    variables: { deletePetId: petId }
})

Remember that when we declared our mutation in mutations.js we had already declared the variables this mutation would use.

export const DELETE_PET = gql`
    mutation DeletePet($deletePetId: ID!) {
        deletePet(id: $deletePetId) {
            id
        }
    }
`

AddPet.jsx

This is the file responsible for adding a new pet to our register:

import React, { useState, useEffect } from 'react'
import { Link } from 'react-router-dom'
import { useMutation } from '@apollo/client'
import { ADD_PET } from '../api/mutations'

function AddPet() {
    const [petName, setPetName] = useState()
    const [petType, setPetType] = useState()
    const [petAge, setPetAge] = useState()
    const [petBreed, setPetBreed] = useState()

    const [addPet, { loading, error, data }] = useMutation(ADD_PET, {
        variables: {
            petToAdd: {
                name: petName,
                type: petType,
                age: parseInt(petAge),
                breed: petBreed
            }
        }
    })

    useEffect(() => {
        if (data && data?.addPet) window.location.href = `/${data?.addPet?.id}`
    }, [data])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Add Pet</h2>

            <Link to='/'>
                <button>Back to list</button>
            </Link>

            {loading || error ? (
                <>
                    {loading && <p>Loading...</p>}
                    {error && <p>Error: {error.message}</p>}
                </>
            ) : (
                <>
                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet name</label>
                        <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
                    </div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet type</label>
                        <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
                    </div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet age</label>
                        <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
                    </div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet breed</label>
                        <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
                    </div>

                    <button
                        style={{ marginTop: 30 }}
                        disabled={!petName || !petType || !petAge || !petBreed}
                        onClick={() => addPet()}
                    >
                        Add pet
                    </button>
                </>
            )}
        </div>
    )
}

export default AddPet

Here we have a component that loads a form to add a new pet and performs a mutation when the data is sent. It accepts the new pet info as parameter, in a similar way that the deletePet mutation accepted the pet id.

EditPet.jsx

Finally, the file responsible for editing a pet register:

import React, { useState, useEffect } from 'react'
import { Link } from 'react-router-dom'
import { useMutation } from '@apollo/client'
import { EDIT_PET } from '../api/mutations'

function EditPet({ petToEdit }) {
    const [petName, setPetName] = useState(petToEdit?.name)
    const [petType, setPetType] = useState(petToEdit?.type)
    const [petAge, setPetAge] = useState(petToEdit?.age)
    const [petBreed, setPetBreed] = useState(petToEdit?.breed)

    const [editPet, { loading, error, data }] = useMutation(EDIT_PET, {
        variables: {
            petToEdit: {
                id: parseInt(petToEdit.id),
                name: petName,
                type: petType,
                age: parseInt(petAge),
                breed: petBreed
            }
        }
    })

    useEffect(() => {
        if (data && data?.editPet?.id) window.location.href = `/${data?.editPet?.id}`
    }, [data])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Edit Pet</h2>

            <Link to='/'>
                <button>Back to list</button>
            </Link>

            {loading || error ? (
                <>
                    {loading && <p>Loading...</p>}
                    {error && <p>Error: {error.message}</p>}
                </>
            ) : (
                <>
                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet name</label>
                        <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
                    </div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet type</label>
                        <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
                    </div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet age</label>
                        <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
                    </div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet breed</label>
                        <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
                    </div>

                    <button
                        style={{ marginTop: 30 }}
                        disabled={!petName || !petType || !petAge || !petBreed}
                        onClick={() => editPet()}
                    >
                        Save changes
                    </button>
                </>
            )}
        </div>
    )
}

export default EditPet

Last, we have a component to edit a pet register through a form. It performs a mutation when the data is sent, and as parameters it accepts the new pet info.

And that's it! We're using all of our API queries and mutations in our front end app. =)

How to Document a GraphQL API with Apollo Sandbox

One of Apollo's coolest features is that it comes with a built-in sandbox you can use to test and document your API.

Apollo Sandbox is a web-based GraphQL IDE that provides a sandbox environment for testing GraphQL queries, mutations, and subscriptions. It is a free, online tool provided by Apollo that allows you to interact with your GraphQL API and explore its schema, data, and capabilities.

Here are some of the main features of Apollo Sandbox:

1. Query Editor: A feature-rich GraphQL query editor that provides syntax highlighting, autocompletion, validation, and error highlighting.

2. Schema Explorer: A graphical interface that allows you to explore your GraphQL schema and see its types, fields, and relationships.

3. Mocking: Apollo Sandbox allows you to easily generate mock data based on your schema, which is useful for testing your queries and mutations without connecting to a real data source.

4. Collaboration: You can share your sandbox with others, collaborate on queries, and see real-time changes.

5. Documentation: You can add documentation to your schema and query results to help others understand your API.

To use our sandbox, simply open your browser at http://localhost:4000/. You should see something like this:

Apollo sandbox

From here you can see the API data schema and available mutations and queries, and also execute them and see how your API responds. For example, by executing the pets query, we can see that response on the right side panel.

Executing a query

If you hop on to the schema section you could see a whole detail of the available queries, mutations object and input types in our API.

The schema section

Apollo sandbox is a great tool that can be used both as self-documentation for our API and a great development and testing tool.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

In some previous tutorials, I covered how to upload files using HTML and JavaScript. It requires sending HTTP requests with the [Content-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) header set to multipart/form-data.

Today, we are going to the back end to receive those multipart/form-data requests and access the binary data from those files.

Some Background

Most of the concepts in this tutorial should broadly apply across frameworks, runtimes, and languages, but the code examples will be more specific.

I’ll be working within a Nuxt.js project that runs in a Node.js environment. Nuxt has some specific ways of defining API routes which require calling a global function called defineEventHandler.

/**
 * @see https://nuxt.com/docs/guide/directory-structure/server
 * @see https://nuxt.com/docs/guide/concepts/server-engine
 * @see https://github.com/unjs/h3
 */
export default defineEventHandler((event) => {
  return { ok: true };
});

The event argument provides access to work directly with the underlying Node.js request object (a.k.a. IncomingMessage) through event.node.req. So we can write our Node-specific code in an abstraction, like a function called doSomethingWithNodeRequest that receives this Node request object and does something with it.

export default defineEventHandler((event) => {
  const nodeRequestObject = event.node.req;

  doSomethingWithNodeRequest(event.node.req);

  return { ok: true };
});

/**
 * @param {import('http').IncomingMessage} req
 */
function doSomethingWithNodeRequest(req) {
  // Do not specific stuff here
}

Working directly with Node in this way means the code and concepts should apply regardless of whatever higher-level framework you’re working with. Ultimately, finish things up working in Nuxt.js.

How to Deal with multipart/form-data in Node.js

In this section, we’ll dive into some low-level concepts that are good to understand, but not strictly necessary. Feel free to skip this section if you are already familiar with chunks and streams and buffers in Node.js.

Uploading a file requires sending a multipart/form-data request. In these requests, the browser will split the data into little “chunks” and send them through the connection, one chunk at a time. This is necessary because files can be too large to send in as one massive payload.

Chunks of data being sent over time make up what’s called a “stream”. Streams are kind of hard to understand the first time around, at least they were for me. They deserve a full article (or many) on their own, so I’ll share web.dev’s excellent guide in case you want to learn more.

Basically, a stream is sort of like a conveyor belt of data, where each chunk can be processed as it comes in. In terms of an HTTP request, the backend will receive parts of the request, one bit at a time.

Node.js provides us with an event handler API through the request object’s on method, which allows us to listen to “data” events as they are streamed into the backend.

/**
 * @param {import('http').IncomingMessage} req
 */
function doSomethingWithNodeRequest(req) {
  req.on("data", (data) => {
    console.log(data);
  }
}

For example, when I upload a photo of Nugget making a cute yawny face, then look at the server’s console, I’ll see some weird things that look like this:

I used a screenshot here to prevent assistive technology from reading that gibberish out loud. Could you imagine?

These two pieces of garbled nonsense are called “buffers” and they represent the two chunks of data that made up the request stream containing the cute photo of Nugget.

A buffer is a storage in physical memory used to temporarily store data while it is being transferred from one place to another. – MDN

Buffers are another weird, low-level concept I have to explain when talking about working with files in JavaScript.

JavaScript doesn’t work directly on binary data, so we get to learn about buffers. It’s also OK if these concepts still feel a little vague. Understanding everything completely is not the important part right now, and as you continue to learn about file transfers, you’ll gain a better knowledge of how it all works together.

Working with one partial chunk of data is not super useful. What we can do instead is rewrite our function into something we can work with:

1. Return a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to make the async syntax easy to work with.
2. Provide an [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) to store the chunks of data to use later on.
3. Listen for the “data” event and add the chunks to our collection as they arrive.
4. Listen to the “end” event and convert the chunks into something we can work with.
5. Resolve the Promise with the final request payload.
6. We should also remember to handle “error” events.

/**
 * @param {import('http').IncomingMessage} req
 */
function doSomethingWithNodeRequest(req) {
  return new Promise((resolve, reject) => {
    /** @type {any[]} */
    const chunks = [];
    req.on('data', (data) => {
      chunks.push(data);
    });
    req.on('end', () => {
      const payload = Buffer.concat(chunks).toString()
      resolve(payload);
    });
    req.on('error', reject);
  });
}

And every time that the request receives some data, it pushes that data into the array of chunks.

So with that function set up, we can actually [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await) that returned Promise until the request has finished receiving all the data from the request stream, and log the resolved value to the console.

export default defineEventHandler((event) => {
  const nodeRequestObject = event.node.req;

  const body = await doSomethingWithNodeRequest(event.node.req);
  console.log(body)

  return { ok: true };
});

This is the request body. Isn’t it beautiful?

I honestly don’t even know what a screen reader would do with if this was plain text.

If you upload an image file, it’ll probably look like an alien has hacked your computer. Don’t worry, it hasn’t. That’s literally what the text contents of that file look like. You can even try opening up an image file in a basic text editor and see the same thing.

If I upload a more basic example, like a .txt file with some plain text in it, the body might look like this:

Content-Disposition: form-data; name="file"; filename="dear-nugget.txt"
Content-Type: text/plain

I love you!
------WebKitFormBoundary4Ay52hDeKB5x2vXP--

Notice that the request is broken up into different sections for each form field. The sections are separated by the “form boundary”, which the browser will inject by default.

I’ll skip going into excess details, so if you want to read more, check out [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) on MDN. The important thing to know is that multipart/form-data requests are much more complex than just key/value pairs.

Most server frameworks provide built-in tools to access the body of a request. So we’ve actually reinvented the wheel. For example, Nuxt provides a global readBody function. So we could have accomplished the same thing without writing our own code:

export default defineEventHandler((event) => {
  const nodeRequestObject = event.node.req;

  const body = await readBody(event.node.req);
  console.log(body)

  return { ok: true };
});

This works fine for other content types, but for multipart/form-data, it has issues. The entire body of the request is being read into memory as one giant string of text. This includes the Content-Disposition information, the form boundaries, and the form fields and values. Never mind the fact that the files aren’t even being written to disk.

The big issue here is if a very large file is uploaded, it could consume all the memory of the application and cause it to crash.

The solution is, once again, working with streams.

When our server receives a chunk of data from the request stream, instead of storing it in memory, we can pipe it to a different stream. Specifically, we can send it to a stream that writes data to the file system using [createWriteStream](https://nodejs.org/api/fs.html#filehandlecreatewritestreamoptions). As the chunks come in from the request, that data gets written to the file system, then released from memory.

That’s about as far down as I want to go into the low-level concepts. Let’s go back up to solving the problem without reinventing the wheel.

How to Use a Library to Stream Data onto Disk

Probably my best advice for handling file uploads is to reach for a library that does all this work for you:

• Parse multipart/form-data requests
• Separate the files from the other form fields
• Stream the file data into the file system
• Provide you with the form field data as well as useful data about the files

Today, I’m going to be using this library called formidable. You can install it with npm install formidable, then import it into your project.

import formidable from 'formidable';

Formidable works directly with the Node request object, which we conveniently already grabbed from the Nuxt event (“Wow, what amazing foresight!!” 🤩).

So we can modify our doSomethingWithNodeRequest function to use formidable instead. It should still return a promise because formidable uses callbacks, but promises are nicer to work with. Otherwise, we can mostly replace the contents of the function with formidable.

We’ll need to create a formidable instance and use it to parse the request object. As long as there isn’t an error, we can resolve the promise with a single object that contains both the form fields and the files.

/**
 * @param {import('http').IncomingMessage} req
 */
function doSomethingWithNodeRequest(req) {
  return new Promise((resolve, reject) => {
    /** @see https://github.com/node-formidable/formidable/ */
    const form = formidable({ multiples: true })
    form.parse(req, (error, fields, files) => {
      if (error) {
        reject(error);
        return;
      }
      resolve({ ...fields, ...files });
    });
  });
}

This provides us with a handy function to parse multipart/form-data using promises and access the request’s regular form fields, as well as information about the files that were written to disk using streams.

Now, we can examine the request body:

export default defineEventHandler((event) => {
  const nodeRequestObject = event.node.req;

  const body = await doSomethingWithNodeRequest(event.node.req);
  console.log(body)

  return { ok: true };
});

We should see an object containing all the form fields and their values, but for each file input, we’ll see an object that represents the uploaded file, and not the file itself. This object contains all sorts of useful information including its path on disk, name, mimetype, and more.

{
  file-input-name: PersistentFile {
    _events: [Object: null prototype] { error: [Function (anonymous)] },
    _eventsCount: 1,
    _maxListeners: undefined,
    lastModifiedDate: 2023-03-21T22:57:42.332Z,
    filepath: '/tmp/d53a9fd346fcc1122e6746600',
    newFilename: 'd53a9fd346fcc1122e6746600',
    originalFilename: 'file.txt',
    mimetype: 'text/plain',
    hashAlgorithm: false,
    size: 13,
    _writeStream: WriteStream {
      fd: null,
      path: '/tmp/d53a9fd346fcc1122e6746600',
      flags: 'w',
      mode: 438,
      start: undefined,
      pos: undefined,
      bytesWritten: 13,
      _writableState: [WritableState],
      _events: [Object: null prototype],
      _eventsCount: 1,
      _maxListeners: undefined,
      [Symbol(kFs)]: [Object],
      [Symbol(kIsPerformingIO)]: false,
      [Symbol(kCapture)]: false
    },
    hash: null,
    [Symbol(kCapture)]: false
  }
}

You’ll also notice that the newFilename is a hashed value. This is to ensure that if two files are uploaded with the same name, you will not lose data. You can, of course, modify how files are written to disk.

Note that in a standard application, it’s a good idea to store some of this information in a persistent place, like a database, so you can easily find all the files that have been uploaded. But that’s not the point of this post.

Now there’s one more thing I want to fix. I only want to process multipart/form-data requests with formidable. Everything else can be handled by a built-in body parser like the one we saw above.

So I’ll create a “body” variable first, then check the request headers, and assign the value of the body based on the “Content-Type”. I’ll also rename my function to parseMultipartNodeRequest to be more explicit about what it does.

Here’s what the whole thing looks like (note that getRequestHeaders is another built-in Nuxt function):

import formidable from 'formidable';

/**
 * @see https://nuxt.com/docs/guide/concepts/server-engine
 * @see https://github.com/unjs/h3
 */
export default defineEventHandler(async (event) => {
  let body;
  const headers = getRequestHeaders(event);

  if (headers['content-type']?.includes('multipart/form-data')) {
    body = await parseMultipartNodeRequest(event.node.req);
  } else {
    body = await readBody(event);
  }
  console.log(body);

  return { ok: true };
});

/**
 * @param {import('http').IncomingMessage} req
 */
function parseMultipartNodeRequest(req) {
  return new Promise((resolve, reject) => {
    /** @see https://github.com/node-formidable/formidable/ */
    const form = formidable({ multiples: true })
    form.parse(req, (error, fields, files) => {
      if (error) {
        reject(error);
        return;
      }
      resolve({ ...fields, ...files });
    });
  });
}

This way, we have an API that is robust enough to accept multipart/form-data, plain text, or URL-encoded requests.

📯📯📯 Finishing up

There’s no emoji rave horn, so those will have to do. We covered kind of a lot, so let’s do a little recap.

When we upload a file using a multipart/form-data request, the browser will send the data one chunk at a time, using a stream. That’s because we can’t put the entire file in the request object at once.

In Node.js, we can listen to the request’s “data” event to work with each chunk of data as it arrives. This gives us access to the request stream.

Although we could capture all of that data and store it in memory, that’s a bad idea. A large file upload could consume all the server’s memory, causing it to crash.

Instead, we can pipe that stream somewhere else, so each chunk is received, processed, then released from memory. One option is to use [fs.createWriteStream](https://nodejs.org/api/fs.html#fscreatewritestreampath-options) to create a [WritableStream](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) that can write to the file system.

Instead of writing our own low-level parser, we should use a tool like formidable. But we need to confirm that the data is coming from a multipart/form-data request. Otherwise, we can use a standard body parser.

We covered a lot of low-level concepts, and landed on a high-level solution. Hopefully, it all made sense and you found this useful.

If you have any questions or if something was confusing, please go ahead and reach out to me. I’m always happy to help.

Thank you so much for reading. If you liked this article, and want to support me, the best ways to do so are to share it, sign up for my newsletter, and follow me on Twitter.

But managing your cloud infrastructure manually can be exhausting. You might start wondering, "how are the enterprise companies doing it?"

Well, they automate their cloud infrastructure management via code. And that's what AWS CloudFormation offers – a way to manage your cloud infrastructure as code.

In this tutorial, we'll explore the basics of AWS CloudFormation and how it can help you automate your cloud infrastructure management. Let's dive into the world of infrastructure as code.

What is CloudFormation?

AWS CloudFormation is a service that helps you automate creating and managing your cloud resources.

Imagine you're building a house, and you want to ensure everything is in the right place – the walls, the roof, the doors, and the windows. Before you build, you would create a blueprint for your house, and specify exactly what you want and where you want it.

Similarly, CloudFormation allows you to create a blueprint for your cloud infrastructure. You can specify what resources you want to create (for example EC2 servers, databases, storage, and so on) and how they should be configured. CloudFormation takes care of creating and managing those resources for you automatically.

CloudFormation can be helpful in many cases. I'll list a few of them here:

1. Managing the infrastructure changes in multiple environments (Development, Staging, Production)
2. Re-creating the same infrastructure in a different region / account
3. Re-creating a resource that's been accidentally deleted with the exact configuration in seconds (not manually, as you have all configurations in your code)

The best part is that CloudFormation makes updating your infrastructure super simple and automatic. If you want to add a new resource, change a configuration, or delete a resource, you can update your blueprint, and CloudFormation will handle the changes for you.

How CloudFormation Works

You may wonder how CloudFormation works. It's simple: we'll upload our CloudFormation templates in Amazon S3 (behind the scenes) which will be pulled by CloudFormation.

One important point to note is we cannot edit the template once uploaded. We'd need to re-upload the updated template to AWS which CloudFormation compares with the existing infrastructure and makes the necessary changes.

One awesome feature is that you can delete all resources created by CloudFormation in one click by deleting the stack. The CloudFormation stack is nothing but a collection of AWS resources that you can manage as a single unit.

You define a stack by creating a CloudFormation template that describes the resources you want to create, and run the template to create the stack.

How to Deploy CloudFormation Templates

We can deploy the CloudFormation template in two ways. One is using CloudFormation Designer and the other is writing the code in a YAML/JSON file.

If you're not familiar with YAML/JSON then you can go for CloudFormation Designer. This is what I'd recommended for those who don't know how to code. It allows you to create and edit templates graphically, making it easier to visualize your infrastructure and simplify the template creation process. But in this tutorial we'll be writing YAML code to deploy our app.

How to Create a CloudFormation Template to Deploy a NodeJS App

You can create a CloudFormation Template using either a YAML or JSON file – but we're going to use a YAML file in the tutorial.

In this template, we'll be creating an EC2 instance, we'll configure a Security Group for EC2, and add a script to deploy a simple NodeJS app.

CloudFormation Template to Create an EC2 Instance

There are over 224 types of resources, but we need to create an EC2 resource. Resources represent the different AWS Components that will be created and configured. We'll define the Resource type identifiers in the below format:

AWS::aws-product-name::data-type-name

The resource format for the EC2 instance is Aws::EC2::Instance. To learn more about AWS resources and syntax, checkout the AWS official documentation and play with it. Look at the EC2 documentation to understand the declaration of EC2 instance. Both JSON and YAML syntax is available but we'll stick with YAML for this tutorial.

There are a lot of properties available to customize the creation of our EC2 instances. To make things simple, we'll be configuring AvailabilityZone, ImageId, and InstanceType which are basic properties needed to create an EC2 instance.

Resources:
  SampleNodejsDeploy:
    Type: AWS::EC2::Instance
    Properties:
      AvailabilityZone: us-east-1a
      ImageId: ami-a4c7edb2
      InstanceType: t2.micro

Here SampleNodejsDeploy refers to the name of the resource we'll be creating. You can name your resource as your wish.

Let's see the process to deploy the NodeJS app.

How to Deploy a NodeJS App using a CloudFormation Template

We're going to deploy the NodeJS app using the UserData property in the EC2 resource.

If you don't know about EC2 user data, it is a feature of AWS EC2 which allows us to pass information during the launch of the EC2 instance. You can use it to perform custom actions, such as installing software and executing the script.

Let's write the bash script to deploy the NodeJS app and attach it to the user data.

Here is the simple script to deploy the NodeJS app:

#!/bin/bash 
set -e
curl -sL https://deb.nodesource.com/setup_16.x | bash -
sudo apt install nodejs
node -v
npm -v
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn
yarn --version
sudo -i -u ubuntu bash << EOF
set -e
cd /home/ubuntu
sudo npm install -g pm2
git clone https://github.com/5minslearn/node_with_docker.git
cd node_with_docker
yarn install 
pm2 start yarn --time --interpreter bash --name sample_node -- start -p 8000
EOF

The above script installs NodeJS, Yarn, and PM2. It clones a NodeJS project from Git, installs the dependencies, and starts the app with PM2.

Our next step is to attach this script to the CloudFormation template.

How to Attach UserData to the CloudFormation Template

Resources:
  SampleNodejsDeploy:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t2.micro
      ImageId: ami-014d05e6b24240371
      UserData: 
        Fn::Base64:
          |
          #!/bin/bash 
          set -e
          curl -sL https://deb.nodesource.com/setup_16.x | bash -
          sudo apt install nodejs
          node -v
          npm -v
          curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
          echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
          sudo apt update && sudo apt install yarn
          yarn --version
          sudo -i -u ubuntu bash << EOF
          set -e
          cd /home/ubuntu
          sudo npm install -g pm2
          git clone https://github.com/5minslearn/node_with_docker.git
          cd node_with_docker
          yarn install 
          pm2 start yarn --time --interpreter bash --name sample_node -- start -p 8000
          EOF

You'll notice that the UserData property is added to the EC2 block. Fn::Base64 is a function in AWS CloudFormation that allows users to encode a string to base64 format. This function can be used to pass sensitive information, such as credentials, to AWS resources in a secure manner. Since EC2 user data is not encrypted it's always best practice to encode it.

Right below that line, you can see a small vertical bar (|). It is used for multi-line string support as our script is more than 1 line.

Alright. Now we have a script to deploy the NodeJS app. But, we have to remember one super important item. By default NodeJS applications run on port 8000. We should expose port 8000 from EC2. Now we need to create a security group configuration for our EC2 instance.

How to Create a Security Group using a CloudFormation Template

This process is similar to creating an EC2 instance, except we'll replace the type from Instance to SecurityGroup.

SampleNodejsDeploySG:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: for the app nodes that allow ssh, http, 8000
      SecurityGroupIngress:
      - IpProtocol: tcp
        FromPort: '80'
        ToPort: '80'
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: '22'
        ToPort: '22'
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: '8000'
        ToPort: '8000'
        CidrIp: 0.0.0.0/0

The above code should be pretty self explanatory – we defined a Security group, allowing ports 22 (SSH port), 80 (HTTP port), and 8000 (NodeJS). We named the Resource as SampleNodejsDeploySG.

How to Attach the Security Group to EC2

You may be wondering – "We've created a template for creating a Security group but how will this be linked to the EC2 instance?"

The solution is simple. CloudFormation provides an intrinsic function called !Ref that allows us to reference a resource or parameter within a CloudFormation template.

Resources:
  SampleNodejsDeploy:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t2.micro
      ImageId: ami-014d05e6b24240371
      SecurityGroups:
        - !Ref SampleNodejsDeploySG
      UserData: 
        Fn::Base64:
          |
          #!/bin/bash 
          set -e
          curl -sL https://deb.nodesource.com/setup_16.x | bash -
          sudo apt install nodejs
          node -v
          npm -v
          curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
          echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
          sudo apt update && sudo apt install yarn
          yarn --version
          sudo -i -u ubuntu bash << EOF
          set -e
          cd /home/ubuntu
          sudo npm install -g pm2
          git clone https://github.com/5minslearn/node_with_docker.git
          cd node_with_docker
          yarn install 
          pm2 start yarn --time --interpreter bash --name sample_node -- start -p 8000
          EOF

  SampleNodejsDeploySG:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: for the app nodes that allow ssh, http 
      SecurityGroupIngress:
      - IpProtocol: tcp
        FromPort: '80'
        ToPort: '80'
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: '22'
        ToPort: '22'
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: '8000'
        ToPort: '8000'
        CidrIp: 0.0.0.0/0

You can see that the SecurityGroups property is added to the EC2 instance and the created Security Group configuration is linked to the EC2 instance by using the !Ref parameter.

Now we have the CloudFormation template. But we're not yet finished. We're still missing one more thing. Can you figure it out? We created an EC2 instance, and we allowed an SSH port...but to log in using SSH we need to attach a key-value pair, right? Let's do that.

We can attach the key-value pair name directly to the template. For example, let's assume your key-value pair name is 5minslearn you can attach the property KeyName directly to the EC2 resource block like what's shown below or we can pass it in via parameters.

Resources:
  SampleNodejsDeploy:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t2.micro
      ImageId: ami-014d05e6b24240371
      KeyName: 5minslearn
      SecurityGroups:
        - !Ref SampleNodejsDeploySG

How to use parameters in the CloudFormation template

We can use parameters to get the name of the key-value pair from the user while creating the stack. Basically, parameters allow us to pass input values into CloudFormation templates at runtime. Let's see how to do that.

Parameters:
  SSHKey:
    Type: AWS::EC2::KeyPair::KeyName
    Description: name of the key pair to ssh into the instance
Resources:
  SampleNodejsDeploy:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t2.micro
      ImageId: ami-014d05e6b24240371
      KeyName: !Ref SSHKey
      SecurityGroups:
        - !Ref SampleNodejsDeploySG
      UserData: 
        Fn::Base64:
          |
          #!/bin/bash 
          set -e
          curl -sL https://deb.nodesource.com/setup_16.x | bash -
          sudo apt install nodejs
          node -v
          npm -v
          curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
          echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
          sudo apt update && sudo apt install yarn
          yarn --version
          sudo -i -u ubuntu bash << EOF
          set -e
          cd /home/ubuntu
          sudo npm install -g pm2
          git clone https://github.com/5minslearn/node_with_docker.git
          cd node_with_docker
          yarn install 
          pm2 start yarn --time --interpreter bash --name sample_node -- start -p 8000
          EOF

  SampleNodejsDeploySG:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupDescription: for the app nodes that allow ssh, http 
      SecurityGroupIngress:
      - IpProtocol: tcp
        FromPort: '80'
        ToPort: '80'
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: '22'
        ToPort: '22'
        CidrIp: 0.0.0.0/0
      - IpProtocol: tcp
        FromPort: '8000'
        ToPort: '8000'
        CidrIp: 0.0.0.0/0

In the above template, we added a parameter to get the key pair name and referenced it to KeyName property.

Great! We successfully created a CloudFormation template to create an EC2 instance and security group. In addition to that, we also added a script to deploy the NodeJS app. Now it's time to create a CloudFormation stack.

How to Create a CloudFormation Stack

The first step is to log in to the AWS console and search for CloudFormation in the search bar (see the below screenshot). Click on stacks in the left sidebar to get started with CloudFormation.

CloudFormation Getting Started

Click on the create stack button to create the CloudFormation stack.

Create CloudFormation Stack

As we have our template ready, select "Template is ready" and choose "Upload a template file" in the Template source section, and upload the template file.

Deploying CloudFormation Template

Once you upload the file, the "View in Designer" button will be enabled. Click on it to view your template design.

How to Validate the CloudFormation Template

Validate CloudFormation Template

To validate our template click on the "Tick" icon on top left in the designer. It will validate and show us errors if any. Once the validation is done, click on the "Cloud" icon to the left of "Tick" icon. It will take you to the create stack page.

In the stack details page, enter the stack name and select your key-value pair. If you don't have key-value pair, create one and select it.

Specify CloudFormation stack details

Leave the Configure stack options section as it is, and click continue since we don't need any IAM permissions or advanced options.

Finally, review the page and submit the template. The template will start creating the resources.

CloudFormation stack creating resources

Once that's done, click on the resources tab. You'll be able to see the resources we created (EC2 and Security group resources).

Resources created by CloudFormation Template

Click on the EC2 instance, and you can see that our instance will be up and running. Copy the public IPv4 address.

EC2 instance up and running

Open your browser and hit http://<ip_address>:8000 (In my case it is http://54.176.19.18:8000/). You should be able to see a page similar to the one below:

NodeJS app running

This represents that our NodeJS app is successfully deployed!

Note: EC2 user data will take some time to install dependencies. So for the first time, the page will take long time to load. Just be patient until the site is loaded.

How to Delete the CloudFormation Stack

If you no longer need the stack, you can delete it from the CloudFormation console.

Select the stack you want to delete, click "Delete Stack," and confirm the action. This action will delete all resources created using this stack. In our case, it'll delete both EC2 and Security Group. You don't need to delete the EC2 instance and Security Group individually.

Deleting CloudFormation stack

Conclusion

In this article, we learned about CloudFormation, how it works, and how to create and delete a template stack.

Hope you enjoyed reading this article! If you are stuck at any point feel free to drop your queries to me at my email. I’ll be happy to help you.

If you wish to learn more about AWS, subscribe to my newsletter (https://5minslearn.gogosoon.com/) and follow me on social media.

The Docker logo actually symbolizes software that brings together a huge amount of organized information, hinting at its convenience.

Many enterprise applications use Docker-based deployments (also called containerized deployments) these days. So it's a good skill to have as a developer.

This tutorial will be the best fit for those who know nothing apart from the term "Docker".

In this article, you'll learn about the fundamentals of Docker, build your own Docker image, and publish it to the Docker Hub.

Why Do You Need Docker?

Let's understand why we need Docker with a simple example.

Let's assume you're joining a new company and you have been assigned to an extremely huge project to work on. You received a brand new laptop and are ready to put on your development shoes.

The first step whenever you are onboarded into a project is to set up the development environment. Since it's a huge enterprise project, it consumes a bunch of time to set up the development environment. You may need to install project-specific dependencies, tools, and many more.

In the middle, you may face errors that you can mostly solve by following the README guide, but a couple of them might happen for the first time (might happen due to laptop configuration) and you have to solve them on your own.

Imagine if you have to follow the same process for large teams with tons of members. It would be horrible to handle right?

This is where Docker comes in really handy. Docker will create containerized applications that run on any type of environment that have all the dependencies within it. So setting up the development environment is just one command away. Docker has many use cases – this scenario is just one of them.

By using Docker we can standardize application operations, ship code faster, and seamlessly deploy to production.

How Does Docker Work?

Docker provides a standardized way to develop, test, and deploy code.

You can think about Docker as a super-powered advanced virtual machine. Let’s learn more about it with an example.

Comparison between Virtual Machine and Docker

Before getting started to work on Docker, we should understand some fundamentals of how it works. They are:

1. Docker Engine
2. Docker Container
3. Docker Image

What is Docker Engine?

The Docker engine is an open-source containerization technology you can use to build a containerizing application. W

e can use the Docker engine on a variety of platforms through Docker Desktop or Binary Installation. To simplify, the software that hosts the containers is called Docker Engine.

What is a Docker Container?

A container is a standard unit of software that packages up the code and all required dependencies needed to run an application on different platforms or computing environments.

Containers are fully isolated from the computing environment, so applications run quickly and reliably from one computing environment to another.

Docker containers are built from container images.

What is a Docker image?

A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application. It includes code, runtime, system tools, system libraries, and settings.

As we discussed, containers are built from images. Images become containers when they starts running on a Docker Engine.

Use Cases for Docker

Docker gives you the ability to run an application in any type of environment which is completely isolated from the current environment. This isolated environment is called a container.

This isolation and security allow us to run as many containers as we want in a host. Docker helps developers to work in a standardized environment using local containers which provide all the packages and dependencies to run an application.

Let's see a few use cases of Docker:

1. Developers can write code locally and share their work using Docker containers
2. You can use Docker to deploy your applications into a test/production environment and execute automated and manual tests
3. When developers need to fix something, they can easily make the changes and push the Docker image to the testing or production environment

Just like Git, we can use Docker when we're making changes to our projects. If we make any changes we can just push the Docker images and pull them into the host machine. No more changes need to be done in the host server.

Here are the deployment steps you'd go through if you're not using Docker:

1. Pull/clone the code from Git
2. Install dependencies, run migrations, and so on in the host machine.
3. Start the application

These steps have to be repeated on every server whether it is a testing or production environment.

Here is the deployment steps using Docker:

1. Pull the docker image (docker pull)
2. Run the container in the host machine (docker run)

What is Docker Hub?

Docker Hub is the largest community for Docker images. It allows you to share the container images among your team, or the Docker community. Docker Hub is sort of like GitHub. Here, Docker images reside instead of the project's code.

You can pull the open-source Docker images also. To use this you have to create an account in Docker hub.

Now that you know a bit about how Docker works and why it's useful, let's learn how to containerize an application.

How to Containerize a NodeJS Application using Docker

Prerequisites:

1. A Basic understanding of NodeJS Applications
2. Docker desktop application

You can install the Docker Desktop application by following their original documentation.

You can verify if Docker is installed on your machine by querying it's version like this:

docker -v

Find Docker Version

Let's start our implementation.

Instead of starting over from scratch, I have created a super simple Express API that exposes only one endpoint. I pushed the code to a public repo on GitHub. You can clone the repo by running the below command:

git clone https://github.com/5minslearn/node_with_docker.git

This is the project's structure:

Simple NodeJS Project Structure

I have created only one endpoint ("/") and calling it will return "Greeting from 5minslearn". I've simplified this as much as possible to allow us to focus more on Docker.

How to Create a Dockerfile

Now, you'll need to create a file named "Dockerfile" in the root directory. It is the default file name for the Docker engine. Paste the following code into the file:

FROM node:latest
WORKDIR /app
COPY . /app
RUN npm install
EXPOSE 8000
CMD ["npm","start"]

Let's understand these commands line by line.

Defining the parent image is the first step of Docker engine. You have to define the parent image from which you're building the project. In our case it's Node.

There are a lot of parent images available in Docker Hub. You have to define the Image Variant next to the parent image. I always prefer to use the latest node image.

FROM node:latest

The second step is to define the working directory in Docker. Let's define our working directory as the app directory.

WORKDIR /app

Copy the project to the app directory. Make sure you exclude the node_modules directory. We will see how to ignore files/folders in the upcoming steps.

COPY . /app

In the above command, the . indicates that all the files and directories are to be copied to the app folder.

The next step is to install the required dependencies with this command:

RUN npm install

RUN is an image build step. The state of the container after a RUN command will be committed to the container image. A Dockerfile can have many RUN steps that can layer on top of one another to build the image.

Expose the port in which application should run.

EXPOSE 8000

The EXPOSE instruction informs Docker that the container listens on the specified network ports at runtime.

Finally run the execution command:

CMD ts-node src/index.ts

CMD is the command the container executes by default when we launch the built image.

Tip: I recommend that you install the Docker extension if you're using VS Code. It'll help you with its solid suggestions.

VS Code Docker extension

How to Ignore Files So They're Not Copied into the Docker Container

You have to exclude the unwanted files from being copied into the container. The .dockerignore file helps you with that. It works like .gitignore for Git.

You can define all the files you have to ignore and don't want to copy.

Using .dockerignore to exclude the unwanted files from being copied to the container

Great! You've completed the Docker configuration. Let's run the application.

How to Build Docker Images

You can build a Docker image by running the docker build command. Here's the syntax for it:

docker build -t image_name:version_number .

image_name indicates the container image name and version_number indicates the image version. Did you notice the dot (.) at the end of the command? It indicates that the Docker image should be built from the current directory.

I decided to set the image name as node_with_docker. Remember that the image name has to be prefixed with the Docker hub username. I've created my Docker hub account with the aanandggs username. So, my image name is aanandggs/node_with_docker. You may choose to enter whatever you want.

docker build -t aanandggs/node_with_docker:0.0.1 .

Sample output of building docker image

Once you've built your Docker image, you'll be able to see it on your Docker Desktop.

Docker Image in Docker Desktop

How to Run the Docker Image

After we build the Docker image, the next step is to run it. When an image starts running on a Docker Engine, it'll become a container.

Let's run our image which we built in the previous step:

docker container run -d --name <name_of_app> -p <local_port>:<docker_port> <image_name>:<version>

docker container run -d --name docker_with_node -p 8000:8000 aanandggs/node_with_docker:0.0.1

Docker Command to create and run a container

Let's understand the above command.

We use the docker container run command to create and run a new container from an image.

The -d flag instructs the container to run in the background (detach). It prints the container id.

The --name parameter gives a name to our container.

We use the -p parameter to publish a container’s port to the host. It'll bind the port 8000 of your local machine with the port 8000 of the Docker container.

image_name:version indicates the image and its version that this container should run.

You can have a look at the running containers in the Docker Desktop app.

Running Container in Docker Desktop

The Dashboard shows that our app is running. Let's check the output on the browser by trying to access the "/" endpoint. Hit locahost:8000/ on your browser. You should see a message similar to the one in the below screenshot:

NodeJS App running output

You have successfully run an app with a Docker container.

Note: You can bind any local port to the Docker port. Ensure your local port is not used by any other process.

How to Push the Image to the Docker Hub

Create your profile on Docker Hub. Come back to terminal and run the below command to login to Docker CLI:

docker login

If you face any issues with login, follow this doc to login to the Dockerhub on your machine.

After a successful login, you can push the image to Docker hub.

docker push <docker_image>:<image_version>

docker push aanandggs/node_with_docker:0.0.1

Sample output of pushing image to docker

Hurray! Docker images are uploaded to Docker hub.

You'll be able to see them in the Docker hub console.

Pushed Docker image in DockerHub

Since our image is public, anyone on the internet can pull the image and run it on their machines without any third-party installation.

Conclusion

In this article, we have learnt the very basics of Docker. Docker is an ocean of information. To fully learn it, you'll need to do more than just reading – you'll need to practice working with it.

Hope you folks enjoyed reading this one. Will see you in another interesting tutorial. Feel free to reach out to me on LinkedIn if you have any queries.

To learn more about Docker, subscribe to my email newsletter on my site (https://5minslearn.gogosoon.com) and follow me on social media.

As you continue to develop your software, you must also continue to integrate it with previous code and deploy it to servers.

Manually doing this is a time-consuming process that can occasionally result in errors. So we need to do this in a continuous and automated manner – which is what you will learn in this article.

We'll go over how you can improve your MERN (MongoDB, Express, React, and NodeJs) app development process by setting up a CI/CD pipeline with Jenkins. You'll see how to automate deployment for faster, more efficient releases.

Let's Get Started

Prerequisites

• Basic understanding of MERN stack technologies.
• Basic understanding of Docker.
• Get source code from GitHub

The Problem

Consider this productivity app – it's a MERN project that we are going to use in this article. There are numerous steps we must complete, from building the application to pushing it to the Docker hub.

First, we must run tests with a command to determine whether all tests pass or not. If all tests pass, we build the Docker images and then push those images to Docker Hub. If your application is extremely complex, you may need to take additional steps.

Now, imagine that we're doing everything manually, which takes time and can lead to mistakes.

Waiting for deployment without devops meme

The Solution

To address this problem, we can create a CI/CD Pipeline. So, whenever you add a feature or fix a bug, this pipeline gets triggered. This automatically performs all of the steps from testing to deploying.

What is CI/CD and Why is it Important?

Continuous Integration and Continuous Deployment is a series of steps performed to automate software integration and deployment. CI/CD is the heart of DevOps.

CI/CD steps

From development to deployment, our MERN app goes through four major stages: testing, building Docker images, pushing to a registry, and deploying to a cloud provider. All of this is done manually by running various commands. And we need to do this every time a new feature is added or a bug is fixed.

But this will significantly reduce developer productivity, which is why CI/CD can be so helpful in automating this process. In this article, we will cover the steps up until pushing to the registry.

CI/CD meme

The Project

The project we are going to use in this tutorial is a very simple full-stack MERN application.

Project demo

It contains two microservices.

1. Frontend
2. Backend

You can learn more about the project here.

Both of these applications contains a Dockerfile. You can learn how to dockerize a MERN application here.

What is Jenkins?

To run a CI/CD pipeline, we need a CI/CD server. This is where all of the steps written in a pipeline run.

There are numerous services available on the market, including GitHub Actions, Travis CI, Circle CI, GitLab CI/CD, AWS CodePipeline, Azure DevOps, and Google Cloud Build. Jenkins is one of the popular CI/CD tools, and it's what we'll use here.

How to Set Up Jenkins Server on Azure

Because Jenkins is open source and it doesn't provide a cloud solution, we must either run it locally or self-host on a cloud provider. Now, running locally can be difficult, particularly for Windows users. As a result, I've chosen to self-host it on Azure for this demo.

If you want to run locally or self-host somewhere other than Azure (follow these guides by Jenkins), skip this section and proceed to the How to Configure Jenkins section.

First, you'll need to sign in to your Azure account (Create one if you don't have one already). Open Azure Cloud Shell.

Opening Azure Cloud Shell

Then create a directory called jenkins to store all the Jenkins config, and switch to that directory:

mkdir jenkins
cd jenkins

Create a file called cloud-init-jenkins.txt. Open with nano or vim,

touch cloud-init-jenkins.txt
nano cloud-init-jenkins.txt

and paste this code into it:

#cloud-config
package_upgrade: true
runcmd:
  - sudo apt install openjdk-11-jre -y
  - wget -qO - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -
  - sh -c 'echo deb https://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
  - sudo apt-get update && sudo apt-get install jenkins -y
  - sudo service jenkins restart

Here, we'll use this file to install Jenkins after creating a virtual machine. First, we install openjdk, which is required for Jenkins to function. The Jenkins service is then restarted after we install it.

Next, create a resource group. (A resource group in Azure is like a container that holds all the related resources of a project in one group. Learn more about resource groups here.)

az group create --name jenkins-rg --location centralindia

Note: make sure to change the location to the one closest to you.

Now, create a virtual machine.

az vm create \
--resource-group jenkins-rg \
--name jenkins-vm \
--image UbuntuLTS \
--admin-username "azureuser" \
--generate-ssh-keys \
--public-ip-sku Standard \
--custom-data cloud-init-jenkins.txt

You can verify the VM installation with this command:

az vm list -d -o table --query "[?name=='jenkins-vm']"

Don't be confused. This command simply displays JSON data in a tabular format for easy verification.

Jenkins server runs on port 8080, so we need to expose this port on our VM. You can do that like this:

az vm open-port \
--resource-group jenkins-rg \
--name jenkins-vm  \
--port 8080 --priority 1010

Now we can access the Jenkins dashboard in the browser with the URL http://<your-vm-ip>:8080. Use this command to get the VM IP address:

az vm show \
--resource-group jenkins-rg \
--name jenkins-vm -d \
--query [publicIps] \
--output tsv

You can now see the Jenkins application in your browser.

Jenkins dashboard

As you'll notice, Jenkins is asking us to provide an admin password which is automatically generated during its installation.

But first let's SSH into our virtual machine where Jenkins is installed.

ssh azureuser@<ip_address>

Now, type in the below command to get the password:

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Copy and paste it. Then click Continue.

How to Configure Jenkins

First, you'll need to click Install suggested plugins. It will take some time to install all the plugins.

Installing suggested plugins

An admin user is needed to restrict access to Jenkins. So go ahead and create one. After finishing, click Save and continue.

Create an admin user

Now you will be presented with the Jenkins dashboard.

The first step is to install the "Blue Ocean" plugin. Jenkins has a very old interface, which may make it difficult for some people to use. This blue ocean plugin provides a modern interface for some Jenkins components (like creating a pipeline).

To install plugins, go to Manage Jenkins -> click Manage Plugins under "System Configuration" -> Available plugins. Search for "Blue Ocean" -> check the box and click Download now and install after restart.

Blue ocean

Great, we're all set. Now let's create a pipeline.

How to Write a Jenkinsfile

To create a pipeline, we need a Jenkinsfile. This file contains all the pipeline configurations – stages, steps, and so on. Jenkinsfile is to Jenkins as a Dockerfile is to Docker.

Jenkinsfile uses the Groovy syntax. The syntax is very simple. You can understand everything by just looking at it.

Let's start by writing:

pipeline {

}

The word 'agent' should be the first thing you mention in the pipeline. An agent is similar to a container or environment in which jobs run. You can use multiple agents to run jobs in parallel. You can find more information about Jenkins agents can here.

pipeline {
    agent any
}

Here we are telling Jenkins to use any available agent.

We have a total of 5 stages in our pipeline:

CI/CD pipeline stages

Stage 1: Checkout code

Different CI/CD tools use different naming conventions. In Jenkins, these are referred to as stages. In each stage we write various steps.

Our first stage is checking out code from a source code management system (in our case, GitHub).

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
    }
}

Commit the changes and push to your GitHub repo.

Since we haven't created any pipelines yet, let's do that now.

Before we begin, we must ensure that Git is installed on our system. If you followed my previous steps to install Jenkins on an Azure VM, Git is already installed.

You can test it by running the following command (make you are still SSHed into the VM):

git --version

If it isn't already installed, you can do so with:

sudo apt install git

Open blue ocean. Click Create new pipeline.

Creating new pipeline

Then select your source code management system. If you chose GitHub, you must provide an access token for Jenkins to access your repository. I recommend clicking on Create an access token here because it is a template with all of the necessary permissions. Then click Connect.

Selecting scm

After that, a pipeline will be created. Since our repository already contains a Jenkinsfile, Jenkins automatically detects it and runs the stages and steps we mentioned in the pipeline.

If everything went well, the entire page will turn green. (Other colors: blue indicates that the pipeline is running, red indicates that something went wrong in the pipeline, and gray indicates that we stopped the pipeline.)

Stage one successful

Stage 2: Run frontend tests

In general, all the CI/CD pipelines contains some tests that needs to be run before deploying. So I added simple tests to both the frontend and backend. Let's start with the frontend tests.

stage('Client Tests') {
    steps {
        dir('client') {
            sh 'npm install'
            sh 'npm test'
        }
    }
}

We're changing the directory to client/ because that's where the frontend code is. And then install the dependencies with npm install and run the tests with npm test in a shell.

Again, before we restart the pipeline, we have to make sure node and npm are installed or not. Install node and npm with these commands in the virtual machine:

curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -

After that, run the following:

sudo apt-get install -y nodejs

Now, commit the code and restart the pipeline.

Run client tests

Stage 3: Run backend tests

Now do the same thing for the backend tests.

But there is one thing we need to do before we proceed. If you take a look at the codebase and activity.test.js, we are using a few environment variables. So let's add these environment varibales in Jenkins.

How to add environment variables in Jenkins

To add environment variables, go to Manage Jenkins -> click Manage Credentials under "Security" -> System -> Global credentials (unrestricted) -> click + Add Credentials.

For Kind select "Secret text", leave Scope default, and for Secret write the secret value and ID. This is what we use when using these environment variables in the Jenkinsfile.

Add the following env variables:

Environment variables

Then in the Jenkinsfile, use these env variables:

environment {
    MONGODB_URI = credentials('mongodb-uri')
    TOKEN_KEY = credentials('token-key')
    EMAIL = credentials('email')
    PASSWORD = credentials('password')
}

Add a stage to install dependencies, set these variables in the Jenkins environment, and run the tests:

stage('Server Tests') {
    steps {
        dir('server') {
            sh 'npm install'
            sh 'export MONGODB_URI=$MONGODB_URI'
            sh 'export TOKEN_KEY=$TOKEN_KEY'
            sh 'export EMAIL=$EMAIL'
            sh 'export PASSWORD=$PASSWORD'
            sh 'npm test'
        }
    }
}

Again, commit the code and restart the pipeline.

Run server tests

Stage 4: Build Docker images

Now, we have to specify a step to build the Docker images from the Dockerfiles.

Before we proceed, install Docker in the VM (if you don't already have it installed).

To install Docker:

sudo apt install docker.io

Add the user jenkins to the docker group so that Jenkins can access the Docker daemon – otherwise you'll get a permission denied error.

sudo usermod -a -G docker jenkins

Then restart the jenkins service.

sudo systemctl restart jenkins

Add a stage in the Jenkinsfile.

stage('Build Images') {
    steps {
        sh 'docker build -t rakeshpotnuru/productivity-app:client-latest client'
        sh 'docker build -t rakeshpotnuru/productivity-app:server-latest server'
    }
}

Commit the code and restart the pipeline.

Build docker images

Stage 5: Push images to the registry

As a final stage, we will push the images to Docker hub.

Before that, add your docker hub username and password to the Jenkins credentials manager, but for Kind choose "Username with password".

Username with password type credential

Add the final stage where we login and push images to Docker hub.

stage('Push Images to DockerHub') {
    steps {
        withCredentials([usernamePassword(credentialsId: 'dockerhub', passwordVariable: 'DOCKER_PASSWORD', usernameVariable: 'DOCKER_USERNAME')]) {
            sh 'docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD'
            sh 'docker push rakeshpotnuru/productivity-app:client-latest'
            sh 'docker push rakeshpotnuru/productivity-app:server-latest'
        }
    }
}

Push images to dockerhub

Here is the complete Jenkinsfile:

// This is a Jenkinsfile. It is a script that Jenkins will run when a build is triggered.
pipeline {
    // Telling Jenkins to run the pipeline on any available agent.
    agent any

    // Setting environment variables for the build.
    environment {
        MONGODB_URI = credentials('mongodb-uri')
        TOKEN_KEY = credentials('token-key')
        EMAIL = credentials('email')
        PASSWORD = credentials('password')
    }

    // This is the pipeline. It is a series of stages that Jenkins will run.
    stages {
        // This state is telling Jenkins to checkout the source code from the source control management system.
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        // This stage is telling Jenkins to run the tests in the client directory.
        stage('Client Tests') {
            steps {
                dir('client') {
                    sh 'npm install'
                    sh 'npm test'
                }
            }
        }

        // This stage is telling Jenkins to run the tests in the server directory.
        stage('Server Tests') {
            steps {
                dir('server') {
                    sh 'npm install'
                    sh 'export MONGODB_URI=$MONGODB_URI'
                    sh 'export TOKEN_KEY=$TOKEN_KEY'
                    sh 'export EMAIL=$EMAIL'
                    sh 'export PASSWORD=$PASSWORD'
                    sh 'npm test'
                }
            }
        }

        // This stage is telling Jenkins to build the images for the client and server.
        stage('Build Images') {
            steps {
                sh 'docker build -t rakeshpotnuru/productivity-app:client-latest client'
                sh 'docker build -t rakeshpotnuru/productivity-app:server-latest server'
            }
        }

        // This stage is telling Jenkins to push the images to DockerHub.
        stage('Push Images to DockerHub') {
            steps {
                withCredentials([usernamePassword(credentialsId: 'dockerhub', passwordVariable: 'DOCKER_PASSWORD', usernameVariable: 'DOCKER_USERNAME')]) {
                    sh 'docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD'
                    sh 'docker push rakeshpotnuru/productivity-app:client-latest'
                    sh 'docker push rakeshpotnuru/productivity-app:server-latest'
                }
            }
        }
    }
}

Pipeline ran successfully

Conclusion

In summary, let's review what we've covered:

• We explored the significance of implementing Continuous Integration and Continuous Deployment (CI/CD) in software development.
• We delved into the fundamentals of Jenkins and acquired knowledge on how to deploy a Jenkins server on the Azure cloud platform.
• We customized Jenkins to meet our specific requirements.
• Lastly, we wrote a Jenkinsfile and built a pipeline utilizing the user-friendly interface of Jenkins Blue Ocean.

That's all for now! Thanks for reading 🙂.

Connect with me on twitter.

Node.js callbacks are a special type of function passed as an argument to another function.

They're called when the function that contains the callback as an argument completes its execution, and allows the code in the callback to run in the meantime.

Callbacks help us make asynchronous calls. Even Node.js APIs are written in a way that supports callbacks.

Here's the syntax of a callback in Node:

function function_name(argument, callback)

How to Use Callbacks in Node

The callback is used to define what happens when the function containing the callback as an argument completes its execution.

For example, we can define a callback to print the error and result after the function execution.

function function_name(argument, function (error, result){ if(error){ console.log(error) } else { console.log(result) } })

How to Write Callbacks

You can write a callback function in two ways: as an arrow function, and as a standard function without a name. Both ways will give you the same result.

How to write a callback as a standard function without a name

You can write a callback as a regular function. You do that using a function keyword then the argument inside round brackets. Then you use curly brackets where you can define the callback body. It is not required to define the function name since it is automatically called.

Syntax:

function function_name(argument, function (callback_argument){
    // callback body 
})

Let’s see an example of a callback using the setTimeout function. You can use this method to define a callback function that runs after a definite time.

setTimeout(function () { 
    console.log('Callback as Standard Function'); 
}, 1000);

Here we define a callback that runs after 1000 milliseconds which is equivalent to 1 second.

Output:

How to write a callback as an arrow function

It may be confusing to have multiple function keywords in a block of code. To eliminate the function keyword in the callback, you can use an arrow function. The arrow function was introduced in ES6 and helps you write cleaner code by removing the function keyword.

Syntax:

function function_name(argument, (callback_argument) => { 
    // callback body 
})

Let’s rewrite the same example we wrote in the above section using an arrow function. Here we change the string to "Callback as Arrow Function".

setTimeout(() => { 
    console.log('Callback as Arrow Function'); 
}, 1000);

Output:

Asynchronous Programming Using Callbacks

Asynchronous programming is an approach to running multiple processes at a time without blocking the other part(s) of the code.

By using callbacks, we can write asynchronous code in a better way. For example, we can define a callback that prints the result after the parent function completes its execution. Then there is no need to block other blocks of the code in order to print the result.

Let’s take the example of a file system module which used to interact with files in Node.js. For reading a file, we can use the readFileSync method.

const fs = require('fs');

const data = fs.readFileSync('hello.txt', 'utf-8'); console.log(data);

Output:

But this way our code holds up the execution of the rest of the program until it finishes its execution and prints the result.

Luckily, we can use a callback to write the code asynchronously without blocking the rest of the execution using the readFile method. When the reading of the file is done, then the callback gets triggered and prints the result.

const fs = require('fs'); 

const data = fs.readFile('hello.txt', 'utf-8', function(err, result){ 
    if(err){ 
        console.log(err) 
    } else { 
        console.log(result) 
    } 
});

Output:

Summary

NodeJS callbacks are a special type of function you can use to write asynchronous code. They give you a way to execute a block of code in the meantime after the execution of a function. You can define whether it prints a result, error, or performs the extra operation of the function result.

There are two ways to write a function: without a function name, or in the form of an arrow function. The arrow function is more convenient and results in cleaner code by removing the use of annoying function keywords.

I hope this article helps you understand Node.js callbacks.

You can have a look at the docs here if you want to learn more.

Whether you're an established retailer or an aspiring entrepreneur, an ecommerce site can provide you with a platform to reach a global audience and sell your products or services around the clock.

Building an ecommerce site may seem like a daunting task, but with the right tools and guidance, anyone can create a professional and functional online store.

In this tutorial, you'll learn how to build your own e-commerce site with Medusa.

What is Medusa?

Medusa is an open source, composable commerce platform that's perfect for developers who want to create a customized ecommerce solution. With its flexible architecture and powerful features, Medusa offers a seamless and straightforward way to build a robust and scalable ecommerce site.

Medusa offers a variety of features, including order management with automated swaps, returns, and claims. It also enables customer management and assignment to customer groups, along with product customization and collection sorting.

With the ability to manage multiple regions and currencies, users can integrate various plugins and third-party services, create advanced pricing and discount rules, configure taxes, and set up multiple sales channels.

Additionally, Medusa offers bulk import and export strategies, and complete customization capabilities to create custom endpoints, services, subscribers, batch job strategies, and more.

In just over a year since its launch, this platform has quickly risen to become the #1 Node.js ecommerce solution, garnering over 17K+ stars on GitHub due to its immense popularity.

Architecture of Medusa

With a composable architecture, Medusa's frontend and backend components are loosely coupled. The platform consists of three different components: the headless backend, the admin dashboard, and the storefront.

You can choose to use the complete Medusa platform or just the parts that you require for your store.

Additionally, with the backend decoupled from the frontend, developers can focus on their respective areas of expertise. Backend developers can concentrate on the Medusa server, while frontend developers can focus on either the storefront or admin.

Medusa Architecture

In the upcoming sections, you will see how Medusa delivers most ecommerce store functionalities right out of the box, with the ability to configure these features to your specific use case.

Medusa Server

The Medusa server, which is a Node.js ecommerce backend, serves as a core component of the platform. It contains all the store's data and logic, and the other two components use its REST APIs to create, retrieve, and modify data.

The server provides most of the features related to an ecommerce workflow. These functionalities include managing products, carts, and orders, as well as integrating with shipping and payment providers and managing users.

In addition to that, you can configure your store including your store’s region, tax rules, discounts, gift cards, and more.

Since Medusa is highly extensible, it allows developers to build custom features such as automating customer group assignments and integrating ChatGPT to automate writing product descriptions.

In addition to that, you can also integrate third-party services into Medusa using Plugins. You can find both official and community plugins to assist you with your common needs. Learn more about these plugins here.

Medusa also allows you to extend its functionalities with new endpoints, business logic, and database entities. Additionally, you can create subscribers that listen to events and trigger specific actions.

Medusa Storefront

The storefront serves as the main presentation layer or frontend of your ecommerce store where customers can view and purchase your products. These storefronts can be in the form of progressive web applications or mobile apps.

Medusa offers two storefront starters built with Next.js and Gatsby, respectively. The storefront includes several features such as product listing and detail pages, customer authentication and profile functionalities, and a full checkout flow supporting shipping details and methods. It also comes with search capabilities ready for integration with top solutions like Algolia and MeiliSearch.

Below is a demonstration of what the Next.js storefront looks like:

In addition to the provided storefront starters, you have the freedom to create your own custom storefront using the Storefront REST APIs.

Medusa Admin

An ecommerce store's essential component is the Admin dashboard, which enables merchants to view, create, and modify data such as products and orders.

With the Medusa Admin dashboard, Medusa provides functionalities for store management, including product management, order management, and user management. You can manage your orders from various regions and channels using a single dashboard.

For merchants migrating their stores from other platforms, the admin dashboard provides easy import and export functionalities for large datasets of products, orders, and customers. The dashboard also offers customer-group functionality to create customized pricing lists, discounts, and gift cards.

This is what the Medusa Admin Dashboard looks like:

However, if you are not satisfied with the existing admin dashboard, you can utilize the Admin REST APIs to extend it beyond.

How to Set Up an Ecommerce Store Using Medusa

In this section, you'll set up the three components of your Medusa ecommerce store.

Prerequisites

Before you get started with the tutorial, you should have installed:

• Node.js(V14 or later)
• Git
• Medusa CLI

How to Set Up the Medusa Server

Creating a new Medusa server is a simple process using the Medusa CLI. Navigate to the directory where you want to create your Medusa server and run the following command to create a new Medusa server with the name my-medusa-store:

medusa new my-medusa-store --seed

This command will create a new Medusa server with the specified name. The --seed option tells the Medusa CLI to seed the data after creating the server. The seed data includes sample data such as products, categories, and more.

Once the command finishes executing, navigate to the my-medusa-store directory and start the server by running the following command:

cd my-medusa-store
medusa develop

In a couple of minutes, the server will start running on the default 9000 port. You can test it out by sending a request using a tool like Postman or through the command line:

curl localhost:9000/store/products

If your server is successfully set up, you will see a list of products and other details as below:

Output of cURL command

How to Set Up the Next.js Storefront

Now that your Medusa server is up and running, it's time to configure your storefront. In this section, you'll set up the Next.js storefront.

Create a new Next.js project using the Medusa Next.js starter template:

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront

Navigate to the newly created directory my-medusa-storefront folder and rename the template environment variable file to use environment variables in development:

cd my-medusa-storefront
mv .env.template .env.local

Make sure the Medusa server is running, then run the local Next.js server:

npm run dev

Your Next.js storefront will now be running on its default port 8000.

Note: Medusa also provides you with the Gatsby starter template to create the storefront.

How to Set Up the Medusa Admin Dashboard

Since the Medusa Admin uses the Medusa server, make sure your server is up and running.

Start by cloning the Admin GitHub repository:

git clone https://github.com/medusajs/admin my-medusa-admin

Navigate to the cloned my-medusa-admin folder and install all the dependencies:

cd my-medusa-admin
npm install

Run the development server:

npm run start

In a couple of minutes, the admin will start running on the default 7000 port. So, in your browser, go to localhost:7000 to view your admin.

Medusa Admin Login

If you had already seeded the data in your Medusa server, you can use the email admin@medusa-test.com and password supersecret to log in. If you hadn't, you can create a new admin user.

How to Set Up Medusa with create-medusa-app

Up to this point, you have seen how to set up individual components of a Medusa project. But in this section, you will learn how to set up a complete Medusa project with all three components using a single command.

Medusa now provides you with a create-medusa-app command to set up a project. This command provides an interactive prompt that guides you through the setup process.

To use create-medusa-app, simply run the following command:

npx create-medusa-app

Creating Medusa Project Using create-medusa-app

In this interactive setup, you will be prompted to enter the name of the directory where you want to install the Medusa project. The default name is my-medusa-store, but you can choose to name it something else.

Next, you will be asked to select a Medusa server starter from the available options, which include the default starter, the Contentful starter, and the option to enter a custom starter URL. The server will be installed in the backend directory of your project, and a demo SQLite database will be created within it.

Following the Medusa server setup, you will be prompted to choose a storefront starter from the available options. If you choose to install a storefront, it will be installed in the storefront directory of your project. If you choose "None", no storefront will be installed.

The admin is set up automatically inside the admin directory of your project.

Once the setup is complete, you will receive instructions on how to start each component of the Medusa project.

Your project is ready. The available commands are:

Medusa API
cd my-medusa-store/backend
yarn start

Admin
cd my-medusa-store/admin
yarn start

Storefront
cd my-medusa-store/storefront
yarn develop # for Gatsby storefront
yarn dev # for Next.js storefront

Just keep in mind that the commands can differ based on your choices in previous prompts.

Project Directory Structure

Inside the root project directory (which was specified at the beginning of the installation process – my-medusa-store in this case) you’ll find the following directory structure:

my-medusa-store
  ├── admin
  ├── backend
  └── storefront

Conclusion

In this tutorial, we've explored Medusa, an open-source e-commerce platform that provides a robust set of features for building online stores. We've looked at the architecture of Medusa, its key features, and how to set up the server, admin dashboard, and storefront.

One of the strengths of Medusa is its flexibility and extensibility. With a variety of plugins and extensions, you can customize your e-commerce site to meet your specific needs. You can also create your own plugins or themes, making it easy to build a site that reflects your brand.

If you're looking to build an e-commerce site, Medusa is a solid choice that offers a lot of functionality out of the box. With its user-friendly interface, setting up an online store is a straightforward process. Plus, since it's an open-source platform, you have the freedom to modify and extend it as needed.

Additional Resources

Here are some resources that you can use to extend the functionalities:

• Integrate SendGrid as a notification provider.
• Integrate Stripe as a payment provider.
• Create a service.

Developers publish packages on NPM to share their code with others. And organisations also use NPM to share code internally.

In this article, you will learn how to create a package. And you will also learn how to publish your package on NPM so others can download and use it.

Let's get started!

How to Choose a Name For Your NPM Package

The first thing you need to do before creating your package is to choose a name. This is important because your package needs to have a unique name. You should choose a name that has not been used already.

When you decide on a name, go to the NPM registry and run a search. Be sure there's no exact match to the name you chose (or a match that is too similar).

For example, if there's a package called hellonpmpackage and you decide to call yours hello-npm-package, NPM will throw an error when you attempt to publish it.

If there's already a package in the NPM registry with the same you want to use, then you have two options.

1. You can choose a different name.

2. You can publish your package as a scoped package (see the section "Publishing scoped packages" below).

How to Create a NPM Package

Follow the steps below to create your package.

1. Install Node

If you do not already have Node installed, you should go ahead and install it. You can visit the official website to download and install Node.js. NPM comes pre-installed with Node.

2. Initialize a Git Repository

Create a new project folder for your package and navigate into the folder. Then, run the following command in your terminal:

git init

This will help you track the changes you make to your package. Also, make sure you have a remote version of your repository on GitHub (or your preferred hosting service).

3. Initialize NPM in Your Project

To do this, navigate to the root directory of your project and run the following command:

npm init

This command will create a package.json file. You will get prompts to provide the following information:

• package-name: As you learned earlier in this tutorial, the name of your package must be unique. Also it must be lowercase. It may include hyphens.

• version: The initial value is 1.0.0. You update the number when you update your package using semantic versioning.

• description: You can provide a description of your package here. Indicate what your package does and how to use it.

• entry point: The entry file for your code. The default value is index.js.

• test command: Here, you can add the command you want to run when a user runs npm run test.

• git repository: The link to your remote repository on GitHub.

• keywords: Add relevant keywords that will help others find your package on the NPM registry.

• author: Add your name.

• license: You can add a license or use the default license (Internet Systems Consortium (ISC) License).

See the screenshot below for an example of how to answer the prompt questions:

Creating a package.json file

Note: I left the test command blank because there is no test command for the package in this tutorial.

4. Add Your Code

Now, you can go ahead and add the code for your package.

First, you need to create the file that will be loaded when your module is required by another application. For this tutorial, that will be the index.js file.

Inside the index.js file, add the code for your package.

For this tutorial, I will be creating a simple package called first-hello-npm. This package returns the string "Hello NPM!".

//index.js

function helloNpm() {
  return "hello NPM"
}

module.exports = helloNpm

After creating your function, you should export it like in the example above. That way, anyone who downloads your package can load and use it in their code.

If you have been following along, you should now have your package created. But before you publish, you need to test your package. Testing your package reduces the chances of publishing bugs to the NPM registry.

How to Test Your NPM Package

Testing ensures that your NPM package works as expected. There are many ways to test your package. In this tutorial, you will learn one of the simplest ways of testing.

First, navigate to the root of your package project. Then, run the following command:

npm link

This will make your package available globally. And you can require the package in a different project to test it out.

Create a test folder. And inside that test folder, add a script.js file.

Example of a test folder with a script.js file

In the example above, the test folder contains only the script.js file. It does not yet contain the package. To add the package you created to your test folder, run the command below:

npm link <name-of-package>

In the case of the test folder for this tutorial, I will run the following command:

npm link first-hello-npm

This will create a node-modules folder. And it'll add all the files and folders from your package – see the screenshot below:

In the script.js file, you can now require your package and use it for the test.

// test/script.js

const helloNpm = require('first-hello-npm')

console.log(helloNpm())

The first-hello-npm package is expected to return the string "hello NPM!". As you can see from the screenshot below, the package works as expected when I run the script.

Test result for first-hello-npm package

After testing your package and ensuring it works as expected, you can now publish it on the NPM registry.

How to Publish Your NPM Package

To publish your package on the NPM registry, you need to have an account. If you don't have an account, visit the NPM sign up page to create one.

After creating the account, open your terminal and run the following command in the root of your package:

npm login

You will get a prompt to enter your username and password. If login is successful, you should see a message like this:

Logged in as <your-username> on https://registry.npmjs.org/.

You can now run the following command to publish your package on the NPM registry:

npm publish

If all goes well, you should get results similar to the screenshot below:

Notice indicating that the package is published successfully.

If you have been following along, then congratulations! You just published your first NPM package.

You can visit the NPM website and run a search for your package. You should see your package show up in the search results.

For example, from the screenshot below, you can see the first-hello-npm package is now available on NPM.

The first-hello-npm package is now available on NPM

How to Publish Scoped NPM Packages

If an existing package has the same name you would like to use, the workaround is to publish a scoped package.

When you publish a scoped package, you have the option to make it public or private. If it's private, you can choose who you want to share the package with.

How to Create a Scoped NPM Package

To create a scoped package, first navigate to the root of your package directory.

Then, run the npm init command and pass your username as the value to the scope flag:

npm init --scope=@your-username

Respond to the prompts to create a package.json file. For your package name, the format should be @your-username/package-name.

For example @benjaminsemah/first-hello-npm.

You can now add the code for your package and test it. The process is the same as already explained above.

Then, to publish your scoped package, run the following command in your terminal.

npm publish --access public

You can change from public to private if you don't want to make the package available for public use.

You should see a response similar to this.

Scoped package published successfully.

Congratulations if you followed along. You've published your scoped package. You should see your scoped package on NPM if you search for it. For example in the screenshot below, you can see the scoped package I created in this tutorial.

Scoped package is now available on NPM

Conclusion

Packages helps developers work faster. And they also improve collaboration. When you figure out a smarter way of doing things, one way you can share with the community is to create and publish your solution as a package.

In this article, you learned what packages are and why they are useful. You also learned how to create and publish packages on the NPM registry. The developer community awaits all the beautiful packages you will create and share.

Thanks for reading. And happy coding!

In this tutorial, you will learn what node modules are. You will also learn about the three types of node modules. And we'll go over the right way to use them in your applications.

What is a Module in JavaScript?

In simple terms, a module is a piece of reusable JavaScript code. It could be a .js file or a directory containing .js files. You can export the content of these files and use them in other files.

Modules help developers adhere to the DRY (Don't Repeat Yourself) principle in programming. They also help to break down complex logic into small, simple, and manageable chunks.

Types of Node Modules

There are three main types of Node modules that you will work with as a Node.js developer. They include the following.

• Built-in modules

• Local modules

• Third-party modules

Built-in Modules

Node.js comes with some modules out of the box. These modules are available for use when you install Node.js. Some common examples of built-in Node modules are the following:

• http

• url

• path

• fs

• os

You can use the built-in modules with the syntax below.

const someVariable = require('nameOfModule')

You load the module with the require function. You need to pass the name of the module you're loading as an argument to the require function.

Note: The name of the module must be in quotation marks. Also, using const to declare the variable ensures that you do not overwrite the value when calling it.

You also need to save the returned value from the require function in someVariable. You can name that variable anything you want. But often, you will see programmers give the same to the variable as the name of the module (see example below).

const http = require('http') 

server = http.createServer((req, res) => { 
    res.writeHead(200, {'Content-Type': 'text/plain'}) 
    res.end('Hello World!')
})

server.listen(3000)

You use the require function to load the built-in http module. Then, you save the returned value in a variable named http.

The returned value from the http module is an object. Since you've loaded it using the require function, you can now use it in your code. For example, call the .createServer property to create a server.

Local Modules

When you work with Node.js, you create local modules that you load and use in your program. Let's see how to do that.

Create a simple sayHello module. It takes a userName as a parameter and prints "hello" and the user's name.

function sayHello(userName) {
    console.log(`Hello ${userName}!`)
}

module.exports = sayHello

First, you need to create the function. Then you export it using the syntax module.exports. It doesn't have to be a function, though. Your module can export an object, array, or any data type.

How to load your local modules

You can load your local modules and use them in other files. To do so, you use the require function as you did for the built-in modules.

But with your custom functions, you need to provide the path of the file as an argument. In this case, the path is './sayHello' (which is referencing the sayHello.js file).

const sayHello = require('./sayHello')
sayHello("Maria") // Hello Maria!

Once you've loaded your module, you can make a reference to it in your code.

Third-Party Modules

A cool thing about using modules in Node.js is that you can share them with others. The Node Package Manager (NPM) makes that possible. When you install Node.js, NPM comes along with it.

With NPM, you can share your modules as packages via the NPM registry. And you can also use packages others have shared.

How to use third-party packages

To use a third-party package in your application, you first need to install it. You can run the command below to install a package.

npm install <name-of-package>