Getting started with npm and package.json

Going through the codebase of just about any modern open source (or even commercial) project, you are likely to come across a file in the root directory called package.json. Used in tandem with npm, this JSON (JavaScript Object Notation) file is used to keep track of a couple major aspects of a software application, such as release versions as well as dependencies used in the project. This blog post will give an overview of the package.json file in relation to npm, how to create a basic configuration file and some of its most integral components.

What are dependencies?

A dependency is any source code that a web or software project relies on in order to function. A project will utilize and reference other source code, and won’t work correctly without these dependencies. Some basic examples of dependencies may include Bootstrap or jQuery, although there are a multitude of others. There are literally hundreds of thousands of packages available via the official npm registry, demonstrating the sheer prevalence of modularity in modern software development — building on bits of other people's source code in order to create something new.

Introduction to npm

npm's (the Node Package Manager) primary function is to keep track of a project's dependencies, as well as any changes in the project's (or its dependencies') versioning. If a project requires a specific version of a dependency, or is able to support a range of different versions, npm will keep track of all of that. npm utilizes Semver (Semantic Versioning) in order to keep track of package versions. A typical version number using Semver would look something like:

2.3.1

A full overview of Semver is out of scope for this post, although the basic format is the first number indicating a major version, the second for minor version updates, and the last number for patches.

Installing npm (via Node.js)

Since npm is an integral part of the Node.js ecosystem, it come pre-packaged with any installation of Node. To install both, go to the official Node.js website, find the installation for your OS, and run the installer after downloading.

To verify that Node was installed successfully, run node -v (Node version) from the command line:

If Node is correctly installed, you should see a version number returned.

Similarly, you can check that npm is installed by running npm -v:

The most current version is 5.7.1 as of the time of this writing.

Managing dependencies via npm

If you intend to manage your dependencies via npm, there are two options:

1. Use npm from the very beginning of your project. npm will automatically keep track of any dependencies added to the project, and update the package.json file accordingly.
2. Manually create and/or edit your package.json file as required.

While it is useful to be able to edit package.json manually as needed (especially in cases where you may be adding package.json to a project already underway), the first option is definitely the ideal. Like all build tools and package managers, one of the prime functions is to automate these simple tasks, cutting down on any busy work best left to your computer to handle. npm can be used to install dependencies without having to deal with a package.json file at all, although this somewhat defeats the purpose of one of its main functions.

Starting a new project with npm init

If you have ever used Git before, the process of adding npm to a project is relatively similar. To add npm to a new project, navigate to your project directory from the command line, and run npm init:

You will be greeted with a message explaining that npm will now walk you through the steps of setting up a package.json file:

You can also cancel the init utility (and the creation of the package.json file) at any point by pressing ⌃C (CTRL + C).

Creating a basic package.json file

Going through the init utility, npm will prompt you to input some basic information, followed by ↩ (Return) to commit each property ("name", "version", etc.)

npm will automatically label the package name based on the name of the directory you started npm init in (in this case, npm-test), although it can be changed by specifying another name. npm will also set "1.0.0" as the default starting version of your package, although this can also be changed.

By default, the only properties that are absolutely required for package.json are "name" and "version". Everything else is totally optional.

If we step through the init utility, hitting ↩ to accept the default values for "name"and "version" and skipping through the other properties ("description", "entry point", "test command", etc.), we'll end up with npm displaying the full content of package.json, followed by a confirmation prompt:

Hit ↩ once more, and our package.json file will now be created. We can verify this by typing ls, seeing package.json as the only file currently in our directory:

We can view the contents of our package.json file by running cat package.json:

Adding dependencies

Similar to initiating a Git repository via git init, once npm has been initiated it will automatically watch for any changes in our dependencies, and modify our package.json file accordingly. Let's add our first dependency to show how this works.

To install Bootstrap via npm, run npm install bootstrap. You will then see that 1 package was added:

(Note: the warnings that appear are due to not supplying description or repository properties in the initial package.json setup, as well as notifications that Bootstrap requires a couple other dependencies in order to function correctly)

We can verify that Bootstrap was added to package.json by running cat package.json again:

Bootstrap 4 will now be listed as a dependency. We can confirm that it was added to our project, via ls. All dependencies are kept in a node_modules directory, which we can view the contents of now:

Installing dependencies via package.json

One major benefit of working with npm and package.json is that you don't need to include your dependencies as part of your source code's distribution. Let's say there are multiple developers working on a project. Instead of having to share the source code for every dependency, only the package.json will need to be included.

We can demonstrate this by deleting our node_modules directory and running npm install:

npm will install all of the listed dependencies, just from package.json.

Conclusion

As we’ve seen in this post, npm and package.json are invaluable for managing a project's dependencies in an efficient way, without having to include your dependencies' source code with your project's distribution. There are many other aspects and advanced features of npm, although the steps covered in this post are enough to get started using this extremely prevalent and useful development tool.

About the author

While always deeply interested in technology since childhood, Nicholas has been involved in web development in a professional capacity since 2012, as both a front-end developer and project manager. He is most adept at HTML, CSS & JavaScript, but is interested in the entire spectrum of computer science. Some of his tech interests include full-stack JavaScript development, Unix-based operating systems, open-source web projects, and computer-assisted composition. He is Senior Project Manager for LA-based web design and development agency, Sunlight Media.