Getting Started with Node.js

Node.js is a runtime environment for executing JavaScript outside the web browser. It makes JavaScript usable in contexts beyond just web pages.

Node.js is not a framework or language. Instead, it is an asynchronous, event-driven environment that includes tools such as:

• JavaScript engine (Google’s V8)
• Module system (CommonJS and ES modules)
• Operating system APIs (os)
• Filesystem access (fs)
• Network servers (http, net, https)
• Memory management tools
• Event loop

These components make up Node.js’s core infrastructure, enabling JavaScript to run outside of browsers.

This guide will help you understand Node.js’s purpose by guiding you through a basic application setup. Let’s begin with installing Node.js.

The first step to creating a Node.js application is to have Node on your system. So, go to the Node.js website and install the latest LTS (long-term support) version.

After installation, run the following command in your terminal to display the Node.js version installed on your system.

Once you’ve successfully installed Node.js on your system, we can proceed to create the project directory.

Use the mkdir CLI command to create a new project directory as follows:

Afterward, navigate to your project directory using the command line.

Use npm to initialize a package.json file after navigating into the project directory.

Next, use the following command to delete the optional main field from package.json:

JavaScript was originally created for web browsers, but other environments also provide the infrastructure to execute it.

Node’s 2009 release provided an environment for running JavaScript outside the web browser. For example, let’s create a script to run from our system’s terminal.

Create the JavaScript file you want Node to run.

In a shell that supports touch, such as Bash or zsh, use the following command. Otherwise, create the file in your code editor:

Open the newly created JavaScript file and write your program:

Installing Node.js makes the node command available for running a Node application from your command line.

• node: The command for running Node.js scripts or the REPL.
• console.js: The JavaScript file you want Node to run.

You can also add the command to the "scripts" field of your project’s package.json file:

With this script in place, you can run your JavaScript program from your terminal like this:

Once you execute your script, Node will print the file’s output to your terminal. It will look like this:

As you can see, we’ve successfully executed JavaScript outside a web browser. That’s precisely what Node.js helps us with. It is an asynchronous, event-driven runtime environment for running JavaScript code outside the web browser. You can also automate rerunning your program. Let’s discuss how.

By default, Node.js requires you to manually rerun your JavaScript file each time you make changes.

Repeating the manual process of executing your application as you make changes can be burdensome. Luckily, Node provides the --watch flag for automating the process:

The snippet above uses the --watch flag to start Node.js in watch mode. This causes Node to re-execute the specified script whenever you update any of the files in its dependency graph.

• node: The command for running Node.js scripts or the REPL.
• --watch: The flag for activating Node’s watch mode.
• filename.extension: The script you want Node to execute.

The --watch flag, by default, watches the entry point and all the modules it depends on. In other words, the watch command causes Node to monitor:

• The entry file (filename.extension)
• All files imported by the entry file
• All files imported in those imports
• And so on through the whole dependency graph

Node’s default watch mode does not watch unrelated files. If you want Node to watch other files, use the --watch-path flag:

The --watch-path flag, in the snippet above, tells Node to watch all files in the src and tests directories, even if they are not in the entry point’s dependency graph.

• node: The command for running Node.js scripts or the REPL.
• --watch-path: The flag for specifying the path you want Node to watch for changes.
• filename.extension: The script you want Node to execute.

Node.js supports two module systems. Let’s learn about them.

Node.js supports both CommonJS (.cjs) and ECMAScript (.mjs) modules. This allows you to use your preferred module type to create Node.js applications.

For example, below is a script.mjs JavaScript file. Node will treat it as an ECMAScript module because it has a .mjs file extension.

On the other hand, Node will regard the script.cjs JavaScript file below as a CommonJS module because it has a .cjs file extension.

Suppose you want to specify the module type for the .js files in your project. In that case, specify a type field in your package.json file like so:

The "type": "module" field in the snippet above makes Node treat .js files governed by this package.json as ES modules. A nested package.json establishes its own scope. .mjs and .cjs files retain their respective module types.

Set the "type" field to "commonjs" to make Node treat .js files in that scope as CommonJS.

Some notes:

• The ES module system is the official standard for JavaScript.
• Kevin Dangoor started the project that became CommonJS in January 2009, before JavaScript had an official standard module system.
• ES modules became part of the ECMAScript standard in 2015. CommonJS remains supported in Node.js.

In this guide, we’ll mainly use Node.js with ES modules, since ES modules are JavaScript’s standard module system. To follow the examples, make sure the "type" field in your package.json file is set to "module". You can do this by running the following command from your project directory:

When relevant, we’ll compare CommonJS syntax.

Let’s now discuss using Node.js to create web servers that receive and respond to requests from browsers.

An HTTP server lets your JavaScript application handle requests from clients, such as browsers, and send responses.

There are three main steps to configuring an app’s HTTP server:

1. Create a new instance of the HTTP Server object.
2. Specify the system’s port where you want the server to run.
3. Define how the server should respond to client requests.

Let’s discuss the three steps in detail. To start, create an ES module for your project.

Afterward, open the newly created module and initialize a new instance of the HTTP Server object.

Node provides the createServer method for creating an instance of the HTTP Server object (http.Server).

You can use it in your project by importing it from Node’s http module as follows:

Here’s what’s going on:

• import statement: Imports the createServer API from Node’s http library to the server.js ES module.
• server: A variable for storing the HTTP Server object that the createServer() function outputs.

Here’s the CommonJS alternative:

Once you have created the local HTTP Server object, specify the server’s port.

The HTTP Server object provides a listen() method to configure the port on which the server should run and accept client requests.

This form of the listen() method accepts the following arguments:

• port: (number) The port number where the server should run and listen for client requests. If omitted, the operating system will assign any unused port. You can use server.address().port to retrieve the port the server is listening on after it starts listening for client connections.
• hostname: (string) The hostname or IP address on which the server should accept client connections. If omitted, the server will default to either an unspecified IPv6 (::) address or an IPv4 (0.0.0.0) address. These unspecified addresses bind to all network interfaces for the applicable address family. You can use server.address().address to retrieve the bound IP address once it starts listening for client connections.
• backlog: (number) Maximum length of the pending connections’ queue. 511 is the default value.
• callback: (function) The function to execute once the server starts listening for client requests.

Here’s what’s going on:

• import statement: Imports the createServer API from Node’s http library to the server.js ES module.
• server: A variable for storing the HTTP Server object that the createServer() function outputs.
• server.listen(): Starts the server to listen for client connections. (Tip: The method emits a listening event once the server starts successfully.)

Here’s the CommonJS alternative:

The 127.0.0.1 address is an IPv4 loopback address that refers to your local computer. The hostname localhost also refers to your local computer, but it may resolve to 127.0.0.1 or the IPv6 loopback address, ::1. You can use it as follows:

If you run this server and visit its web address, the browser will wait for a response because we have not yet set up a request handler. Let’s configure that now.

The createServer() method accepts a requestListener callback that is invoked automatically whenever the server receives an HTTP request. Node allows you to use this callback to respond to requests.

The createServer() method accepts two optional arguments. Here’s the syntax:

• options: An object for customizing the server’s behavior.
• callback: The requestListener function for handling and responding to client requests. It accepts two parameters:

• request parameter: An http.IncomingMessage object that provides details about the client request.
• response parameter: An http.ServerResponse object for responding to the client requests.

Providing the requestListener callback function as createServer’s second argument causes Node.js to automatically register it as a listener for the "request" event. So, the syntax above is equivalent to:

server.on("request", callback) tells the server to listen for a request event and execute the callback on such an event.

The snippet above used the requestListener callback function’s response parameter to configure the server to respond to client requests. Here’s the server.on("request", callback) alternative:

Now that your server is set up and the port configured, you can run the application.

• node: The command for running Node.js scripts or the REPL.
• server.js: The JavaScript file you want Node to run.

While the server is running, if users request the app’s resource at the server’s web address, they will see a Hello World! response.

Let’s now discuss some of the http.ServerResponse object’s APIs you can use to respond to HTTP requests.

Below are some of the ServerResponse APIs for responding to client requests.

The response.statusCode property sets the status code used when Node sends implicit response headers, such as on the first write() or end() call.

<number> is the status code value you want to send to the client. It typically falls within one of the following categories:

• 100 – 199: Informational responses
• 200 – 299: Successful responses
• 300 – 399: Redirection messages
• 400 – 499: Client error responses
• 500 – 599: Server error responses

200 is the default response status code.

The snippet above uses res.statusCode to set the response’s status code to 200 (success).

The response.statusMessage property sets the human-readable status message used when Node sends implicit response headers.

<string> is the message you want to send to the client. undefined is the default, which makes Node default to the status code’s standard message if you do not define a statusMessage.

The snippet above uses res.statusMessage to set a human-readable status message for the server response’s status code.

The response.setHeader() method sets an HTTP response header that Node.js will send to the client when it sends the response headers.

Calling setHeader() does not send the header immediately. It stores the header so that Node can send it later—for example, when you call response.write() or response.end().

You can also use an array to define multiple values for a single header:

The snippet above uses res.setHeader to set the header that the server sends to the client in response to the client’s request. The value can also be an array:

The response.writeHead() method sets the HTTP response’s status code, status message (optional), and headers that the Node.js server will send to the client.

• statusCode: A 3-digit number representing the HTTP response’s status code that the Node.js server will send to the client.
• statusMessage: An optional string representing the human-readable status message that the Node.js server will send to the client. If omitted, Node uses an existing response.statusMessage value or the status code’s standard message.
• headers: An optional object or array representing the HTTP response headers that the server will send to the client. If you use an array, Node will interpret the even-numbered indices as header names and the odd-numbered indices as header values.

The snippet above uses writeHead to send three headers to the client. We also chained an end() method to the ServerResponse object returned by writeHead().

Here’s the array equivalent of the headers argument:

Let’s now discuss the difference between writeHead(), statusCode, setHeader, and statusMessage.

The writeHead() method sets the status code and, optionally, the status message and headers for one HTTP response. Here’s how it works differently from the implicit alternatives.

• writeHead(): A method of the http.ServerResponse object
• statusCode: A property of the http.ServerResponse object
• statusMessage: A property of the http.ServerResponse object
• setHeader(): A method of the http.ServerResponse object

• writeHead(): Sets the response’s status code, status message (optional), and headers.
• statusCode: Sets (or gets) the response’s status code.
• statusMessage: Sets (or gets) the response’s status message.
• setHeader(): Sets the response’s header. (You can use getHeader() to retrieve the header.)

• writeHead(): Commits the status and headers. It does not guarantee immediate network transmission.
• statusCode: Sets the status code before implicit headers are sent.
• statusMessage: Sets the status message before implicit headers are sent.
• setHeader(): Stores a header for later transmission, for example with the first write() or end() call.

Before the headers are committed, you can assign statusCode and statusMessage or call setHeader() repeatedly. The latest value replaces the previous one.

Call writeHead() only once per response, before write() or end().

The status code and any status message supplied to writeHead() override the corresponding properties. Its headers merge with those set by setHeader(), overriding values with matching names.

Headers supplied directly to writeHead() without prior use of setHeader() are not cached for retrieval with getHeader(). The statusCode and statusMessage properties remain readable.

The response.write() method sends a chunk (portion) of the HTTP response body to the client. In other words, rather than sending all the data at once, you can use write() to send it in chunks. It is an efficient way to stream or send large amounts of data.

• chunk: A string, buffer, or Uint8Array representing the portion of the HTTP body you want to send to the client.
• encoding: An optional string specifying how Node should encode a string chunk into a byte stream. "utf8" is the default value.
• callback: An optional function, which Node will call when it sends the chunk of data to the client.

The snippet above uses write() to send three chunks of body data to the client.

The response.end() method completes the response to an HTTP request. It signals to Node that you’ve finished sending all response headers and the body to the client. In these examples, call this method to finish the response. It does not necessarily close the underlying connection, which may be reused.

• chunk: An optional string, buffer, or Uint8Array representing the portion of the HTTP body you want to send to the client before ending the stream. If specified, it is equivalent to calling response.write(chunk) followed by response.end().
• encoding: An optional string specifying how Node should encode a string chunk into a byte stream. "utf8" is the default value.
• callback: An optional function, which Node will call when the data streaming ends.

The snippet above uses the end() method to properly end data streaming to the client.

Node.js comes with a built-in REPL, which stands for read-eval-print loop. You can use it to test small pieces of code.

To begin a REPL session, just type node in your terminal (without any arguments) and press the Enter key.

The node command starts Node.js in REPL mode, and your terminal will display messages similar to the following:

The message above means the command line is ready and waiting for you to enter JavaScript or REPL code. Here are some examples.

The snippet above told Node.js to print the === Hello from the CodeSweetly Team! === string. The REPL is smart enough to know when you want to display values, so you usually do not need to use console.log().

Here’s an example:

Each time you run some code, the REPL does the following:

1. Reads the code.
2. Evaluates it.
3. Prints the result and waits for your next input.
4. Loops (repeats) these steps after each input until you exit the REPL session.

As you can see, REPL lets you keep running code until you exit the session.

To write multiline code, such as a function, press Enter after each line. The REPL will recognize that you wish to continue on a new line.

The example above demonstrates running a multiline if statement in a REPL session. The displayed result depends on the local time when you run it.

In addition to .exit, REPL provides several other useful commands. Below are some of the most common.

• .help: Print the REPL’s dot commands.
• .break: Abort the multiline expression currently being entered. Unlike .break, .clear can also reset the context of a programmatically created REPL.
• .editor: Allows you to write multiple expressions in editor mode and run them all at once. Press Ctrl + D on Windows, macOS, or Linux to exit editor mode and execute your code.
• .load: Load code from a JavaScript file into the REPL session.
• .save: Save all the JavaScript code you entered in this REPL session to a file.

REPL also has built-in variables for storing the previous result and error. Let’s look at how they work.

REPL has the following variables predefined:

• Underscore (_): Stores the previous operation’s result.
• Error (_error): Stores the last error thrown.

The REPL assigns the result of your last operation to an internal underscore variable (_). You can use this variable in your next command.

The example above uses the underscore variable (_) to retrieve the result of the last operation.

The REPL assigns the last error to an internal error variable (_error), or to undefined if no error has occurred.

The example above uses the error variable (_error) to retrieve the most recent error.

Node.js also lets you run the REPL from a JavaScript file for advanced customization. The following section explains how to do this.

To run the REPL from a JavaScript file, import it from the node:repl module like this:

After importing the repl module, you can use its APIs to create, launch, and manage a REPL instance. Below are a few examples.

The example above uses the repl.start() method to create and launch a new REPL Server instance. Run the file from your command line as shown below:

Node.js will enter REPL mode, and your terminal will display messages similar to the following:

By default, REPL uses a greater-than sign and a space (> ) as its prompt. You can change this by providing a prompt argument to the repl.start() method.

• import statement: Imports the repl API from Node’s repl library.
• repl.start(): The method for creating and launching an interactive REPL instance.
• promptValue: A string or object for specifying a custom REPL prompt.

In the example above, the custom prompt is set to ===+ . You can also use an object as shown below:

When you run the file from your command line, your terminal will display messages similar to the following:

The options object passed to repl.start({ ... }) has several properties for customizing the REPL environment. For example, you can use the eval property to handle user input.

Here’s an example:

The example above uses the eval property to define a custom function for processing user input in the REPL session. It rejects input that converts to a finite number and converts other input to uppercase. The input already arrives as a string; this is a numeric-conversion check, not a string-type check.

Before we proceed to the next chapter, let’s recap what Node.js is.

Node.js is not just for creating web servers. You can use it for a wide variety of projects, such as:

• Command-line developer tools
• Web applications
• Automation scripts
• Deployment scripts
• Filesystem tools

For example, the snippet below uses Node’s createWriteStream API to write data to a file.

Some notes:

• If the specified file does not exist, Node will create it automatically. With the default settings shown here, an existing file is overwritten.
• The node filename.extension command still works for running a Node.js script that streams data to a file. The node command is a universal CLI tool for running all Node.js scripts regardless of their purposes.

And that’s it! This chapter used a basic application setup to explain what Node.js is, its purpose, and how you can use it to run JavaScript programs outside a web browser. In the following chapter, we will discuss how to use Node to manage files.