Node.js and npm Tutorial

Knowing how to use npm is a requirement for using many cool things such as webpack and eleventy, so here is a tutorial on everything you need to know!

If you have questions or feedback regarding the tutorial, please use the comment section at the end of the page! Don't be shy; I know it's frustrating when you're stuck, and I'd love to help.

Command Line

In this tutorial we will be executing commands in a command line. If you're using Windows you can use the Windows PowerShell for this (you might have to open it as an administrator). If you're using VSCode to code you can also open a terminal in VSCode (right-click on file free and choose "Open in Integrated Terminal").

When I give you a command, for example npm --version, this means you have to type that in and press enter. It will output one or multiple lines of information (in this case your installed version of npm).

Tip: You can use the up-arrow key on your keyboard to load the most recent command. This is practical if you have a command you need to execute again and again.

Make sure the current path in your terminal is the root folder of your project (e.g. D:\Projects\my-project). The current path in your terminal is shown to the left of where you type. If you've opened the integrated terminal in VSCode the path should already be correct. If you need to change the path of the terminal you can do this with the cd command (= "change directory"):

• cd .. will go one folder up.
• cd <path> (e.g. cd D:\Projects\my-project or cd my-project) will switch to that directory

Definitions

Before we start we need to define some terms.

Node.js (Node) is a JavaScript runtime environment that executes JavaScript code outside of a web browser. Check if you have it installed via node --version. When you install Node.js, npm is also automatically installed.

npm (Node Package Manager) is a tool which will allow you to install third party libraries/packages (other people's code, such as webpack or eleventy) by using the command line. Check if you have it installed via npm --version. When you install Node.js, npm is automatically installed, which means you don't need to install this seperately.

FYI: We will be installing node and npm globally (once on your device) and all packages locally (once per project).

• Webpack will take all your CSS, SCSS and JavaScript files and generate one big JavaScript file out of them all. Webpack itself requires a bunch of other packages (such as css-loader) to work. (I have a tutorial on how to set it up here.) My tutorial is coming soon.
• Eleventy is a static site generator. You can create "templates" (either .html or .njk files) and re-use them. This way you don't have to edit your header in every single page file, etc. Then you execute a command, and Eleventy will generate all your page files for you. These files you can upload to your website as you normally would. (I have a tutorial on how to set it up here.) Here is my tutorial.
• tippy.js styles your tooltips
• and many many many more...

Installation

First, we will need to install Node.js on our device. Download the node.js installer from here and execute it to install Node.js on your computer.

We will now check if the installation was successful. Open a terminal of your choice (e.g. Windows PowerShell, or a terminal in VSCode) and execute the command node -v. It should show the version you just installed.

Also execute npm -v to check if npm was also successfully installed (it will show a different version than node, that's okay).

If both commands work and show you a version you have successfully installed node and npm! :)

Tip: If you ever need a newer version of node, just download the newer installer and go through the installation wizard again. It will replace your current version with the newer one. Only do this if you know it won't mess with your projects!

Note: If you need multiple different node versions on your computer because you have projects that require different node versions, you can use nvm (Node Version manager) (not to be confused with npm). This tutorial will not include this.

Once you've installed node and npm you don't need to do it again. It's installed on your device, not in your project, so you can use it in all your projects.

Project Setup

We will now initalize our project as an npm project. We do this by creating a file with the name package.json in the root folder of our project (e.g. D:\Projects\my-project\package.json)..

Add this in the file:

{
  "name": "your-project-name",
  "private": true
}

You can add more information, such as version or description and custom commands (see below), but that's all optional for most projects, especially small/personal projects.

(Alternatively, instead of creating the file yourself, you can run the npm init command, which will ask you some questions about your project and generate the file for you.)

Done! Now you can now start installing packages.

Custom Commands

In the package.json you can define custom commands to "replace" other commands. The command for custom commands is always npm run <command name>.

For example:

"scripts": {
    "build": "npx @11ty/eleventy"
}

will run the command npx @11ty/eleventy when you execute npm run build.

You can even run two commands with one (seperated by a &), for example:

"scripts": {
    "build": "npx @11ty/eleventy & webpack"
}

will run the commands npx @11ty/eleventy and webpack when you execute npm run build.

More info on custom commands here.

GitIgnore

If your project is a git repository you should add node_modules to your gitignore file, because the folder should not be added to your repository (because it is quite large and generated automatically).

If you don't have a gitignore file yet, create it like this: In the root folder of your project, create a file with the name .gitignore (don't forget the period at the start). In it, type node_modules. This will make git ignore the node_modules folder, as if it wasn't there.

Don't know what Git is? Check out my git tutorial.

Installing Packages

You can install packages using this command: npm install <package>, e.g. npm install webpack.

Note: Packages are either installed as dependencies or development dependencies (devDependencies). The distinction is probably not important to you as a beginner: either is fine. To install a package as a devDependency use this command: npm install <package> --save-dev

Here's what happens when you install a package: npm checks if that package exists, looks for the most recent version of it, and tries to download and install the package. If successful, these things happen:

• The package name and version will be added to the list of dependencies in your package.json file.
• A package-lock.json will be created, which contains information about all installed packages. (You won't need to look at this file, but don't delete it.)
• A node_modules folder will be created in your project which contains the necessary files for this package.

You should never manually edit anything in the node_modules folder or the package-lock.json file. (And you won't have to, anyway.) Since these files are generated automatically any changes you make in them would be soon overwritten.

If, instead of these things happening, you get an error read the 'troubleshooting' section below.

You can uninstall packages by running npm uninstall <package>.

Understanding Dependencies in package.json

Once you have some packages installed they will be listed in your package.json file, e.g.:

"devDependencies": {
    "@11ty/eleventy": "^2.0.1",
    "css-loader": "^7.1.2",
    "sass": "^1.77.8",
    "sass-loader": "^16.0.1",
    "style-loader": "^4.0.0",
    "tippy.js": "^6.3.7",
    "webpack": "^5.94.x",
    "webpack-cli": "^5.1.4"
  },

The first value is the name of the package, the second is the version rule. The version rules can look like this:

• 1.2.3: only version 1.2.3, nothing else
• ^1.2.3: version 1.2.3 or higher, but below 2.0
• ~1.2.3: version 1.2.3 or higher, but below 1.3
• 1.x.x: version 1.0.0 or higher, but below 2.0
• 1.2.x: version 1.2.0 or higher, but below 1.3
• *: any version

and so on.

You can edit these manually and install them by running npm install (more info on that later). However, it's also possible to install/update/deinstall packages with command line commands alone, without editing this file manually.

These version rules are based on semantic versioning. Essentially, this just means that the first number is a major release (which breaks backward comaptibility), the second number is a minor release (which adds new features), and the third number is a patch release (which fixes bugs). Sometimes, the second and/or third number is left out, which implies ".0" (e.g. 1.3 = 1.3.0)

npm install and npm update

One more thing you need to know:

The command npm install (without specifying a package) 'reads' the dependency list in your package.json file and makes sure all packages are installed in the right version. If, for some reason, you delete your node_modules folder or package-lock.json, you can get them back with npm install.

There is also the command npm update, which (confusingly) does the same thing as npm install but also checks for newer versions of packages. You probably won't need this unless you're planning on updating to newer version of a package.

Troubleshooting

Clean Slate: If you feel like you messed up everything, just delete the entire node_modules folder and the package-lock.json file, make sure your dependency list is correct, and execute npm install again for a "fresh" install.

Cache Problem: If you get an error along the lines of Failed to remove some directories. EPERM: operation not permitted on Windows, execute npm cache clean --force and try whatever you did again.

Dependency Conflicts: Packages that you install need to fit together. For example, if you install package-a and it required version 1.2-1.5 of package-b, and you then try to install version 3.6 of package-b it obviously won't work! Problems like these are called conflicts, and how to resolve them depends on what you're trying to do. In the example I just gave, one solution would be to check for a newer version of package-a that requires a more up-to-date version of package-b. Alternatively, you could also install an older version of package-b so that the requirement of package-a is fulfilled. For a more detailed explanation, read 'How to Resolve Conflicts' below.

How to Resolve Conflicts

"devDependencies": {
    "package-a": "^5.74.0",
    "package-b": "^3.3.11"
},

While resolving: my-project@undefined
Found: package-a@5.94.0
dev package-a@"^5.74.0" from the root project

Could not resolve dependency:
peer package-a@"4.x.x" from package-b@3.3.12
node_modules/package-b
dev package-b@"^3.3.11" from the root project

Additional Commands

• Show all installed packages: npm list -g --depth=0
• Show all outdated packages: npmoutdated
• Show the newest available version of a package: npm view <package> version,
  e.g. npm view webpack version

Comments

Leave your questions, problems, suggestions, requests and thanks here!

To share very long code or error messages with me, please upload it to pastebin (or a similar site) and include the link. This is to make sure you don't hit the max character limit on comments.