Let’s start by creating a server that returns plain text to the user. This will cover the key concepts required to set up a server, which will provide the foundation necessary to return more complex data formats like JSON.
First, we need to set up an accessible coding environment to do our exercises, as well as the others in the article. In the terminal, create a folder called first-servers:
NOTE: This may vary for windows OS
mkdir first-servers
Then enter that folder:
cd first-servers
Now, create the file that will house the code:
touch hello.js
Open the file in a text editor. We will use nano as it’s available in the terminal:
nano hello.js
We start by loading the http module that’s standard with all Node.js installations. Add the following line to hello.js:
const http = require("http");
The http module contains the function to create the server, which we will see later on.
Our next step will be to define two constants, the host and port that our server will be bound to:
const host = 'localhost';
const port = 8000;
As mentioned before, web servers accept requests from browsers and other clients. We may interact with a web server by entering a domain name, which is translated to an IP address by a DNS server. An IP address is a unique sequence of numbers that identify a machine on a network, like the internet. For more information on domain name concepts, take a look at our An Introduction to DNS Terminology, Components, and Concepts article.
The value localhost is a special private address that computers use to refer to themselves. It’s typically the equivalent of the internal IP address 127.0.0.1 and it’s only available to the local computer, not to any local networks we’ve joined or to the internet.
The port is a number that servers use as an endpoint or “door” to our IP address. In our example, we will use port 8000 for our web server. Ports 8080 and 8000 are typically used as default ports in development, and in most cases developers will use them rather than other ports for HTTP servers.
When we bind our server to this host and port, we will be able to reach our server by visiting localhost:8000 in a local browser.
Let’s add a special function, which in Node.js we call a request listener. This function is meant to handle an incoming HTTP request and return an HTTP response. This function must have two arguments, a request object and a response object. The request object captures all the data of the HTTP request that’s coming in. The response object is used to return HTTP responses for the server.
We want our first server to return this message whenever someone accesses it: "My first server!".
Let’s add that function next:
const requestListener = function (req, res) {
res.writeHead(200);
res.end("My first server!");
};
The function would usually be named based on what it does. For example, if we created a request listener function to return a list of books, we would likely name it listBooks(). Since this one is a sample case, we will use the generic name requestListener.
All request listener functions in Node.js accept two arguments: req and res (we can name them differently if we want). The HTTP request the user sends is captured in a Request object, which corresponds to the first argument, req. The HTTP response that we return to the user is formed by interacting with the Response object in second argument, res.
The first line res.writeHead(200); sets the HTTP status code of the response. HTTP status codes indicate how well an HTTP request was handled by the server. In this case, the status code 200 corresponds to "OK".
The next line of the function, res.end("My first server!");, writes the HTTP response back to the client who requested it. This function returns any data the server has to return. In this case, it’s returning text data.
Finally, we can now create our server and make use of our request listener:
const server = http.createServer(requestListener);
server.listen(port, host, () => {
console.log(`Server is running on http://${host}:${port}`);
});
Save and exit nano by pressing CTRL+X.
In the first line, we create a new server object via the http module’s createServer() function. This server accepts HTTP requests and passes them on to our requestListener() function.
After we create our server, we must bind it to a network address. We do that with the server.listen() method. It accepts three arguments: port, host, and a callback function that fires when the server begins to listen.
All of these arguments are optional, but it is a good idea to explicitly state which port and host we want a web server to use. When deploying web servers to different environments, knowing the port and host it is running on is required to set up load balancing or a DNS alias.
The callback function logs a message to our console so we can know when the server began listening to connections.
Note: Even though requestListener() does not use the req object, it must still be the first argument of the function.
With less than fifteen lines of code, we now have a web server. Let’s see it in action and test it end-to-end by running the program:
$ node hello.js
In the console, we will see this output:
Output
Server is running on http://localhost:8000
Notice that the prompt disappears. This is because a Node.js server is a long running process. It only exits if it encounters an error that causes it to crash and quit, or if we stop the Node.js process running the server.
In a separate terminal window, we’ll communicate with the server using cURL, a CLI tool to transfer data to and from a network. Enter the command to make an HTTP GET request to our running server:
$ curl http://localhost:8000
When we press ENTER, our terminal will show the following output:
Output
My first server!
We’ve now set up a server and got our first server response.
Let’s break down what happened when we tested our server. Using cURL, we sent a GET request to the server at localhost:8000. Our Node.js server listened to connections from that address. The server passed that request to the requestListener() function. The function returned text data with the status code 200. The server then sent that response back to cURL, which displayed the message in our terminal.
Before we continue, let’s exit our running server by pressing CTRL+C. This interrupts our server’s execution, bringing us back to the command line prompt.