Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.

Node.js

With any project that you start, a great way to plan it out is through README Driven Development. This means you write out all that you want to accomplish in your project README before doing anything else.

We will do just that, we will discuss what commands we want to be able to run and what we need to do to accomplish that functionality.


node

Plan a Node.js CLI Tool Project with README Driven Development

The first step to creating your project is initializing with NPM. We will walk through all the options that NPM has for you to create a `package.json` and also show you a shortcut to accept all the default options with the `-y` flag.


Initialize a Node.js Project with NPM

Node.js projects have two ways that you can import and export code into different files. This is through CommonJS (CJS) and ECMAScript modules (ESM).

CommonJS is Node's default way to import modules but because I like to have my Node.js code similar to my frontend code, we will use ESM for this project.

To do so we will set a project `type` in our `package.json`.


Set the Node.js Project to ECMAScript Modules (ESM)

When you run Node.js, you'll have access to the `process` object. If you console log it out you'll see that it has quite a bit of information stored on it. Dig through there and check it out!

We will focus on the `argv` property. This property is an array that has the path to node and our script as the first and second values. When we pass in arguments or flags to our script, argv include the values that we will pass.

We will see how we can check for flags and run conditional logic based on the flags that are passed.   


Parse User Input through Node.js process argv for Flags

Reading user input is a big aspect of this project because we will be asking for a question or an answer for the CLI to work with.

Node has some internal options for parsing user input. We will check out the `readline` module and how it parses input. We will also see the promise driven version of the module and use a top level await to ask questions in the CLI.

This package has some limitations in how you present questions to your user though so if presentation is important to you, you will want to consider using a 3rd party library.


Parse User Input in Node.js with readline

You want to focus your development efforts on the actual business logic of the application, not procedural aspects of the code like parsing inputs. 

This is why we'll look for a 3rd party tool to parse user input. We'll look at 4 different libraries and walk through how to decide which will be best for this specific project.


Assess and Choose a 3rd Party Library for your Node.js CLI Tool

Now that we've chosen Inquirer as the library to use in our project, we need to use it! To do so the current questions in the CLI will be swapped out with inquirer `prompt` API. You'll see some immediate benefits in styling and functionality that we get for free now that inquirer is being used.

Process User Input with Inquirer in Node.js

There are a handful of ways you can read and write to the File System in Node.js. 

We will look at `readFileSync`, `readFile`, and a promise based version of `readFile`.

Each have there use-cases and we will discuss the pros and cons of each one. For instance `readFileSync` is a blocking operation which if you were developing a web server with Node.js would be a huge problem. With this project being in the CLI for one user, this is a ok option to consider.  On the other hand, `readFile` is a non-blocking operation that uses promises/callbacks to interact with the file system.


Assess and Choose Three Approaches to Reading from the File System in Node.js

Now that we can read from files, we don't need to hardcode any data in our script. Instead, we can import a json file and use `readFile` to access questions and answers from the contents within.

We can then prompt the user with the question from the file and check the users answer against the answer that is stored.

Note: Checking the answer is just JavaScript! I set up this logic for you so we can focus on the scripting/file system side of things.


Read a File with Node.js readFile from the File System and Parse Question and Answer

Now that we have the basic question/answer functionality working, that being we can ask a question of the user and check if the users answer is correct, we want to log the results of the users answers back to the file.

To log the results, we'll assign the question we got to from our file to a variable and add `lastAnsweredCorrect` (that is true if the user answers the question correctly and false if not) and `lastAsked` (the current date) properties to that object. We will then add that question object back to the array of questions we got from the file system and use `readFile` to write our results.

Note: `checkAnswer` was refactored into its own function for easier visibility in our script.


Log Question Results by using Node.js to Filter and Write to a File

Currently we are grabbing the first element in the array that our JSON data gives us back. We want a random element (or question) from our file.

To get a random element from an array we will use Math.Floor and Math.Random in combination with the array length to get a random question returned to us.


Find a Random Element in a JSON File in Node.js

All of our questions have been hard coded so far. We want the user to be able to add a question when they pass the `--add` flag.

We will need to use inquirer to ask for a question and it's answer. Once we have a question and answer in hand we will read our data.json file and then write to it with our new question. While we do this, we will assign a unique id to the question based on the length of the array being stored in our file. 


Add Question/Answer Object to our Data with Node.js writeFile

One issue with our script is that the answer that is checked needs to be exactly the same string as the answer in the file system. This can be brittle because your user might not capitalize or forget a space. There are ways we could sanitize user data but this can introduce quite a lot of complex logic into our script.

A great work around is to use Inquirer to check with the user if they got the answer right or wrong, this way you know you are logging correct values and you don't need to worry about sanitizing data as the user is determining for themself if they were right.


Offload Complex Logic and Confirm a Correct Answer with the User

A CLI isn't super useful if you have to be inside of the project to start the script. 

To fix this, we can add a `#!` (shebang) to the top of our entry file. On linux and MacOS systems you'll also have to make the file executable as well. Then we can use a symbolic link to add a custom `quizme` command to our path that points at our scripts entry file.

We'll need to fix one more thing though! If you try to run the script in a different directory, the file it references for `./data.json` will be incorrect, we'll fix this in the next lesson.


Make a Node.js Script Globally Executable with a Shebang and a Symbolic Link

Our CLI can be run from anywhere on the system but we have a critical error. The script is trying to find a `data.json` file that is relative to where it is being called. This will throw an error if you aren't actually in the script directory. 

The fix for this in an ECMAScript project like we are in is to use a `import.meta.url` variable that will give use the directory that the script is executed in. We can append our `data.json` to this path and call that throughout our script and we've fixed our error!


Handle Relative Paths in a Node.js ESM Project with import.meta.url

From Node 18.3 and above, there is a new command line parser. Before, we would either have to use custom logic or a third-party library to explore process.argv.

I create an `options` object with a key of `add` that has an object of key `type`, which is a boolean, and a key of `short` which we pass the value of `"a"`. Now, I pass that to `parseArgs`, set that to a variable, and console.log it to show you more about how `parseArgs` works. 

Use parseArgs to Parse your Command Line

Humans were never meant to repeat joyless tasks in a precise manner, over and over and over. Learn to automate the joyless tasks out of your life.

Automate Daily Development Tasks with Bash

A quick overview of the features of Script Kit to help you get oriented and writing scripts in no time. 

Get Started Building CLI Tools with Node.js

Kevin Cunningham

You might also like these resources:

Automate Daily Development Tasks with Bash

Script Kit Showcase for Optimizing Your Everyday Workflows

Course Content

You might also like these resources:

Automate Daily Development Tasks with Bash

Script Kit Showcase for Optimizing Your Everyday Workflows