For most of my career as a web developer, I worked on the Front-End of websites and applications consuming APIs made by other people. Recently, I decided to learn Node.js properly and do some server-side programming as well.
I decided to write this introductory tutorial for anyone who is interested in learning Node after realising that it’s not so easy to read the documentation and figure out how to go about building stuff with Node.
You can search the web for instructions on how to install Node.js and
npm for your preferred platform or visit the Node.js website (
npm comes with Node). The versions I used while building this project are as follows:
- Node.js v9.3.0
- npm v5.8.0
You can view the version of Node and
npm you have installed by running the following commands in your terminal:
node -v npm -v
I believe the code will still work even if you’re on an older version of Node, but if you have any trouble completing the tutorial, try upgrading to the versions I used to see if it fixes your problem.
What we’ll be building
I’ll take you through how to build a simple website with Node.js, Express and Pug. The website will have a homepage and a few other pages which we’ll be able to navigate to.
Checkout the live website here.
Download the starter files from github, and then run the following command from the root of the downloaded folder to install the project dependencies.
I’ve chosen to provide these starter files so you don’t run the risk of running into bugs as a result of using a different version of a package from the one I used. Don’t worry, I’ll explain what each dependency does as we go along.
Now open up
server.js in the root directory and type in the following code:
We start by importing Express which is the web server framework we are using. The
express() function is a top-level function exported by the
Next, we need to set up the website to run on port 7000. You can choose another port if 7000 is in use on your machine.
You can start the web server by running
node server.js from the root of your project folder.
If you open
http://localhost:7000 in your browser, you will see an error message that says “Cannot GET /”. This is because we have not defined a root route for our website so let’s go ahead and do just that.
Add the following code before the
server variable declaration in
The code above specifies that when a GET request is made to the root of our website, the callback function we specified within the
get() method will be invoked. In this case, we are sending the text “Hello World!” back to the browser.
Now, you need to restart your server before the changes take effect. Doing this every time you make a change in your code can become incredibly tedious, but I’ll show you how to get around that in the next section.
For now, stop the node process in your terminal using Ctrl-C and start it again with
node server.js then refresh your browser. You should see the text “Hello World!” on the page.
Setup pm2 to auto restart Node.js application server
There are several tools you can use to auto restart your Node server after every change so you don’t have to deal with that. My preferred tool is pm2 which has worked really well for me in my projects.
If you look at the
package.json file, you will see that
pm2 is listed under the
devDependencies, so you can start using it right away.
Change the start script in package.json to the following:
Kill the node process and run
npm start. Now your web server will be restarted automatically everytime you make a change.
Rendering HTML in the Browser
Instead of just sending text to the browser when someone hits a route, we can send HTML as most websites do. We can author the HTML files by hand and specify what file to send to the browser once a GET request hits a route, but it’s almost always better to use a template engine to generate HTML files on the fly.
A template engine allows you to define templates for your application and replace the variables in the template with actual values at runtime while transforming the template to an actual HTML file which is then sent to the client.
There are several template engines you can use with Express. Pug, Mustache, and EJS are some of the most popular ones. I’ll be using Pug here because I’m comfortable with the syntax but you can do the tutorial in another templating engine if you wish.
I’ve already included the
pug package in our project dependencies so we can go ahead and use it in express.
Add the following code to your
server.js file below the
app variable. This tells express that we are using
pug as our template engine.
Express expects that our template files be kept in a folder called
views. Create this folder in the root of your project directory then create a file called
index.pug in the
views folder and paste the following code therein:
Now change the line in your
server.js file that says
res.send('Hello World!') to
res.render(index). This tells express to render the index template that we just created. You don’t need to put the
.pug extension at the end.
If you refresh your browser, you should see the words “Hello Pug!” on the page. If you inspect the text using your browser’s developer tools, you should see that the code you wrote in
index.pug was transformed into regular HTML.
The first thing to know is that Pug relies on indentation to describe the structure of the template and there are no closing tags.
Here’s the basic syntax for Pug that you need to understand to complete this tutorial along with the HTML equivalent in a comment below the Pug code.
You have your element, a space and the contents just like we’ve done above:
You can put an element’s content on its own line like this to achieve the same result:
If you want to nest elements, you need to indent it by one level:
You can use classes and ids on your elements like this:
And here’s how you use HTML attributes:
Passing variables in Pug
You can pass information from your route to your template by passing an object when you render the template like this:
And in your template file, you can reference it like this:
If you want to use a variable in an attribute, you have to do it using ES2015 template literals:
Let’s create a website
We can demonstrate the power of Pug and Express by building a simple website.
First, create a
default.pug file in the
views directory and paste in the following content. This file acts as a sort of boilerplate for our other templates.
block keyword allows us to extend a template through inheritance. When extending a template, you can define custom content for any block in the parent template.
Here’s an example of how that works. In the
index.pug file, type in the following:
The default template expects a title variable, so we need to pass that in when rendering any template that extends it.
Refresh your browser to see the changes.
Working with static content
We need to tell express where static files (such as stylesheets, fonts or images) for our website are placed so that it knows how to serve them correctly.
server.js file to look like this:
If you refresh your browser, the styles referenced in
default.pug should kick in.
Working with JSON data
In the root folder, there is a
people.json file which we are going to use to construct the website’s pages. If you inspect it, you will see a
profiles key which is an array that contains a few objects each representing a person’s profile.
In a real world application, you will likely fetch this data from a database somewhere, but this method should serve to illustrate the concept well.
Let’s construct the website homepage. We need to pass the json data to our index template and render a card for each person defined within.
server.js file to look like this:
Here, we store a reference to the
people.json file in the
people variable. Next we pass the
profiles array to the
index template as the
Now change your
index.pug file to look like this:
each keyword in pug allows us to iterate over arrays and objects. Each object in the
people array can be accessed under the
person key for each iteration and we use that to construct a card for each person on the homepage.
There is a link at the bottom of each person which should go to their respective profiles. But when you click it, you get an error message that says “cannot GET /profile”.
Let’s fix that by creating a new route for
server.js, add the following code under the root route:
Once you hit a person’s profile, it should send the person’s id back to the browser. In Express, you can access URL query parameters under
Let’s create a new template file that will be rendered once someone hits the profile route. Go ahead and create
profile.pug in the
views folder, and add the following content:
Here, we are extending the default template again, and overriding the
header block defined within with an empty block because we don’t want the default header content to show on this page.
content block, I’ve added the necessary markup for each profile. As you can see, this template expects us to pass the object that describes each person so let’s go ahead and do just that.
/profile route to look like this:
First we use the array
find() method to extract the first object whose
id property matches the one recieved in the query parameters. Then we pass this object to the
The result is that each person’s profile can be viewed by clicking their respective profile links on the homepage.
That concludes my tutorial. I hope it has helped you learn the basics of Node.js, Express and Pug, and how you can use it to build simple websites.