Your first Node.js project

6 min readFeb 1, 2018

Recently I’ve been asked to help my colleagues to start their journey with Node.js. This is a very basic tutorial which hopefully will be extended with further examples on how to build a small web app with hapi.js.

For sake of simplicity I’ll be referring to Node.js as “node”.

Terminal

I’m using console/terminal a lot — I recommend doing the same. For Windows my preference it ConEmu (https://conemu.github.io/). Windows 10 users can use Windows Subsystem for Linux (https://docs.microsoft.com/en-us/windows/wsl/install-win10).

For OSX combination of iTerm2(https://www.iterm2.com/) and oh-my-zsh (https://github.com/robbyrussell/oh-my-zsh)

Getting node

I’m on OSX so it’s a bit simpler than windows:

» brew install node

For windows go to https://nodejs.org/en/, download and instal node.

Node comes with Node Package Manager — NPM which is super useful and is widely used to manage project dependencies and more.

npm is great, but I think yarn is better (I had few cases where it was faster on Windows and got packages that npm couldn’t).

In most cases, yarn and npm have very similar commands and provide same functionality.

Read-Eval-Print-Loop (REPL)

Once node installed, you can use it! Node comes with REPL which you can start by typing “node” in your terminal. That lets you play with node flavor of java script.

Yarn

Yarn (https://yarnpkg.com/en/) is a package manager developed by Facebook.

» brew install yarn

For windows go to https://yarnpkg.com/en/, download and run the msi file.

First project

We need to start somewhere. I like to start by creating a folder and initializing a git repository in it.

» mkdir hellojs && cd hellojs
hellojs» git init

Next we should initialize a node project.

hellojs» yarn init

The generator will ask us few questions, it’s ok to just press [enter] for all of them.

At this point we’ve created package.json file which defines a node project. Currently it’s not very useful since it’s points to non existing index.js file and has no dependencies :)

{
 “name”: “hellojs”,
 “version”: “1.0.0”,
 “description”: “Hello world with nodejs”,
 “main”: “index.js”,
 “author”: “Piotr Karpala”,
 “license”: “MIT”
}

Editor

There are many! Brackets, Atom, VSCode, Sublime, WebStorm to name a few. I’m using Atom — https://atom.io/

» brew cask install atom

It’s very configurable, fast and has ton of plugins. I like that it’s available from command line and to open a project I can just do:

hellojs» atom .

Let’s write some code

We can write a simple hello world app that we can extend with some dependencies later.

This just prints some text to the console. Use of function is just to add some more complexity, we could just do console.log(“Hello node.js!”) without writing any functions.

Let’s run some code

Easiest way to run it is using “node <file.js>”

hellojs» node index.js                                              
Hello node.js!
Using v9.4.0 node version.

That works, but it’s not recommended way for most node projects. The way to go is to add scripts section in package.js

{
  "name": "hellojs",
  "version": "1.0.0",
  "description": "Hello world with nodejs",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "author": "Piotr Karpala",
  "license": "MIT"
}

Scripts section is super useful and it’s primarily used for … — you guessed it! scripting :) of some day to day commands (deploy, test, run, code coverage etc.).

Let’s run the start command.

hellojs» yarn start
Hello node.js!
Using v9.4.0 node version.
✨  Done in 0.17s.

Something interesting

We had to cover all the boring stuff first to get to something interesting. Let’s say we want to add a cool feature from external library to our project. Maybe, let’s color the text in red.

I usually start by googling for a package that already does what I need. Maybe searching for “nodejs color console”. Another way is to check npm registry — https://www.npmjs.com/

Choosing right package may be difficult. I follow few guidelines — number of downloads and number of github stars. That usually points you to something that people like :)

In this particular example, you’ll see that the author of top results is the same person — sindresorhus, a GIANT of nodejs and OS community. I recommend following his work, e.g. https://github.com/sindresorhus/awesome-nodejs, but back to our task.

Once we find the right package we need to add it to our project using yarn.

(Note that we’re using npm registry with yarn — they are compatible)

hellojs» yarn add chalk

That command did few things:

created node_modules directory
downloaded chalk package and it’s dependencies into node_modules
modified package.json file
created yarn.lock file

At this point we should commit our work, in order to do that we need to add simple .gitignore file first.

Because our dependency is saved in package.json, we don’t have to keep node_modules in source control (that would be a very bad practice).

hellojs» git add .                                                                                 
hellojs» git status                                                                                
On branch master
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
 new file:   .gitignore
 new file:   index.js
 modified:   package.json
 new file:   yarn.lockhellojs» git commit -m "init commit"                                                               
[master 29de6af] init commit
 4 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore
 create mode 100644 index.js
 create mode 100644 yarn.lock

Using dependencies

To use chalk package we need to use require function.

After running it:

More on dependencies

Last thing to try is to make sure our project works if we remove node_modules. Before moving to next step — commit your changes.

To remove all untracked files run:

hellojs» git clean -fxd

It will remove node_modules and any other files that were not tracked in git, basically replicating scenario of clean repository copy.

Next let’s install all dependencies just by running yarn command.

To make sure it still works run yarn start.

Ufff, that’s enough for one day :) In the next episode I’ll cover unit testing and running a simple hapijs web app.

Further learning

I really like nodeschool for it’s hands on approach. If you’re new to node/git/javascript — that’s the place to start! https://nodeschool.io/#workshoppers