Lesson 4. Building a simple web server in Node.js

This lesson covers some basic functions of the http module, a Node.js library of code used for handling requests over the internet. The tech community raves about Node.js and its use of JavaScript as a server-side language. In this lesson, you build your first web server. In a few short steps, you convert a couple of lines of JavaScript to an application with which you can communicate on your web browser.

This lesson covers

• Generating a basic web server using Node.js and npm
• Writing code that processes requests from a browser and sends back a response
• Running a web server in your browser

4.1. Understanding web servers

Web servers are the foundation of most Node.js web applications. They allow you to load images and HTML web pages to users of your app. Before you get started, I’ll discuss some important web server concepts. After all, the final product will look and feel a lot better if you have clear expectations of the result.

When you visit https://www.google.com, for example, behind the scenes you’re making a request to Google’s servers, which in turn send a response back to you, rendering the famous Google Search landing page. This request-response relationship allows for a channel of communication between the user and the application. In figure 4.1, a bundle of data is sent to the application’s server in the form of a request, and when the server processes the request, it issues a bundle of data back in the form of a response. This process is how most of your interaction on the internet is facilitated.

Figure 4.1. A web server sends your browser web pages, images, and other resources on request.

When you enter the URL you want to see in your browser, an HTTP request is sent to a physical computer elsewhere. This request contains some information indicating whether you want to load a web page or send information to that computer.

You may build a fancy application with many bells and whistles, but at the core lies a web server to handle its communication on the internet. (These concepts will make more sense to you as I discuss them throughout the book.) In the next section, you start building your web server.

4.2. Initializing the application with npm

Before you get started with a Node.js web application, you need to initialize the project in your project folder in terminal. Open a terminal window, and create a new directory called simple_server with mkdir. You can initialize the project with npm init.

Note

npm is Node.js’ package manager. Your Node.js projects rely on this tool to install and build applications. You can learn more about npm and how it’s used at https://docs.npmjs.com.

Running the npm init command initiates a prompt to create a package.json file. As the prompt explains, you’ll walk through configuring the most basic settings of your Node.js application in this file. For now, you can add main.js as the entry point, along with a short description and your name as the author, and elect to use the default values offered by pressing the Enter key until you reach the end of the prompt

Then you’re asked to confirm your settings with a preview of your package.json file. Press Enter to confirm and return to the regular terminal prompt.

4.3. Coding the application

When you installed Node.js, the core library was installed too. Within that library is a module called http. You’ll use this module to build your web server. In this section, you also use a package called http-status-codes to provide constants for use where HTTP status codes are needed in your application’s responses.

Note

Modules in Node.js are libraries of code that come packaged to offer specific functionality to your application. Here, the http module helps you communicate across the web by using HTTP.

In your text editor, create a new file called main.js, and save it in the project folder called simple_server containing the package.json file you created earlier. This file will serve as the core application file, where your application will serve web pages to your users. Within this project’s directory in terminal, run npm i http-status-codes -S to save the http-status-codes package as an application dependency.

Before I analyze every aspect of what you’re about to build, take a look at all the code in listing 4.1. The first line of code assigns the port number you’ll use for this application: 3000.

Note

Port 3000 is generally used for web servers in development. This number has no significance, and you can customize it with a few exceptions. Ports 80 and 443 usually are reserved for HTTP and HTTPS, respectively.

Then you use require to import a specific Node.js module called http and save it as a constant. This module is saved as a constant because you don’t plan on reassigning the variable. You also require the http-status-codes package to provide constants representing HTTP status codes.

Next, you use the http variable as a reference to the HTTP module to create a server, using that module’s createServer function, and store the resulting server in a variable called app.

Note

Using ES6 syntax, you structure callback functions with parameters in parentheses, followed by ⇒ instead of the function keyword.

The createServer function generates a new instance of http.Server, a built-in Node.js class with tools for evaluating HTTP communication. With this newly created server instance, your app is prepared to receive HTTP requests and send HTTP responses.

Warning

These method names are case-sensitive. Using createserver, for example, will throw an error.

The argument in createServer is a callback function that’s invoked whenever some event occurs within the server. When the server is running and your application’s root URL (home page) is accessed, for example, an HTTP request event triggers this callback and allows you to run some custom code. In this case, the server returns a simple HTML response.

You log that a request was received from the client and use the response parameter in the callback function to send content back to the user, from whom you first received a request. The first line uses a writeHead method to define some basic properties of the response’s HTTP header. HTTP headers contain fields of information that describe the content being transferred in a request or response. Header fields may contain dates, tokens, information about the origins of the request and response, and data describing the type of connection.

In this case, you’re returning httpStatus.OK, which represents a 200 response code, and an HTML content-type to indicate that the server received a request successfully and will return content in the form of HTML. Following this block, you assign a local variable, responseMessage, with your response message in HTML.

Note

200 is the HTTP status code for OK, used to indicate that no issue occurred in returning content in an HTTP response header. To get a list of other HTTP status codes, enter http.STATUS_CODES in the Node.js REPL shell. Use httpStatus.OK in place of the explicit number.

Right below that line, you’re writing a line of HTML in the response with write and closing the response with end. You must end your response with end to tell the server that you’re no longer writing content. Not doing so leaves the connection with the client open, preventing the client from receiving the response. You also log your response at this point so you can see that a response was sent from the server itself.

The last line of code takes the server instance, app, and runs the listen method to indicate that the server is ready for incoming requests at port 3000.

Listing 4.1. Simple web application code in main.js

const port = 3000,
  http = require("http"),                                           1
  httpStatus = require("http-status-codes"),
  app = http.createServer((request, response) => {                  2
    console.log("Received an incoming request!");
    response.writeHead(httpStatus.OK, {
      "Content-Type": "text/html"
    });                                                             3

    let responseMessage = "<h1>Hello, Universe!</h1>";
    response.write(responseMessage);
    response.end();
    console.log(`Sent a response : ${responseMessage}`);
  });

app.listen(port);                                                   4
console.log(`The server has started and is listening on port number:
${port}`);

• 1 Require the http and http-status-codes modules.
• 2 Create the server with request and response parameters.
• 3 Write the response to the client.
• 4 Tell the application server to listen on port 3000.

Note

The response object is used by Node.js and carried throughout the application as a way to pass information about the current client transaction from function to function. Some methods on the response object allow you to add data to or remove data from the object; writeHead and write are two such functions.

There your application is, in all its glory! Not so terrible. In only a few lines of code, you’ll also build a web server this way.

Note

If you don’t specify a port number, your operating system will choose a port for you. This port number is what you’ll soon use to confirm through your web browser that your web server is running.

With this code in place, you’re ready to start your Node.js application from terminal.

4.4. Running the application

The last step is an easy one. Navigate to your project’s directory with terminal, and run node main in your terminal window. Next, open any browser to the address localhost: 3000. You see a message indicating that the server has started. Your terminal window should resemble figure 4.2.

Figure 4.2. Running the a basic Node.js server

The browser window should greet you and the universe with salutations, as shown in figure 4.3. Congratulations! Your first Node.js web application is complete. It’s big, and it’s about to get bigger and better.

Figure 4.3. Display of your first web page

To stop the application, press Ctrl-C in your terminal window. You can also close the terminal window, but you may risk not shutting down the application properly, in which case the application could continue to run behind the scenes (requiring more command-line magic to kill the process).

Summary

In this lesson, you learned that Node.js has built-in functionality for creating web servers via the http module. You configured a new Node.js application via the package.json file. Using the http module and createServer method, with minimal effort you created a web server, which is a stepping stone to building robust applications with Node.js. Through terminal, you were able to run a web-server application.

Complete the “Try this” exercise to check your understanding.