Importance of package.json in Node JS Applications With Examples [Latest]

Prerequisite: You should have some basic knowledge about JSON file format, JSON data types etc.

What is package.json?

package.json is a plain JSON(Java Script Object Notation) text file which contains all metadata information about Node JS Project or application.

Every Node JS Package or Module should have this file at root directory to describe its metadata in plain JSON Object format.

We should use same file name with same case “package” and same file extension “*.json”.

Why that filename is “package”: because Node JS platform manages every feature as separate component. That component is also known as “Package” or “Module”.

Who uses package.json file?

NPM (Node Package Manager) uses this package.json file information about Node JS Application information or Node JS Package details.

package.json file contains a number of different directives or elements. It uses these directives to tell NPM “How to handle the module or package”.

Mandatory Directives of package.json file

package.json file contains a number of different directives or elements. Some are mandatory and some are optional directives.

Mandatory Directives

ackage.json file contains two mandatory directives;

1. name
2. version

name: It is a unique Node JS Package (Module) name or our Node JS Project name. This name should be in lower case letters. It is mandatory directive. Without this directive, we cannot install our Node JS Package by using NPM.

JSON file follows key-value pair format. Key is of JSON String type and value may be of any JSON Data type. Key and Value elements are separated by colon “:”.

Here “name” directive’s value is of JSON String type.

Example:

"name":"simplename"

When we run “npm install <package-name>” command, NPM reads package.json file available at root directory and checks that package name by reading this name directive. If it does not find this directive in package.json file then it throws an error message and cannot install that package.

version: version is the Node JS Package version number. It is a Mandatory directive in package.json file. NPM uses this version number to install or uninstall or update the right package in our NODE JS Environment.

“version” directive’s value is of JSON String type.

If NPM does not find this directive in package.json file then it throws an error message and cannot install that package.

Example:

"version":"1.0.0"
Here we need to define 3 parts of version: major, minor and patch

Both name and version directives of package.json file identifies a Node JS Package uniquely.

Example of sample package.json file

{
   "name" : "sample",
   "version" : "1.0.0"
}

Optional Directives

package.json file may contain many optional directives. We should use them only if our Node JS package really requires. We will discuss some important optional directives here.

description: It is the description of the Node JS Project or module. We need to provide brief and concise description about “What this module does”.

dependencies: Every Node JS Project or Module may dependent on other Node JS or Third Party Modules or our own Custom Modules. We should provide all those dependencies by using this “dependencies” directive.

“dependencies”: {
<Define all your Module Dependencies here in key-value pairs>
}

Here key is module name and value is required module version. For example;

"dependencies": {
      "mypackage": "1.0.0",
      "async": "0.8.0",
      "express": "4.2.x"
}

Complete package.json file example:

{
"name" : "sampleapp",
"version" : "1.0.0"'
"dependencies": {
	"mypackage": "1.0.0",
	"async": "0.8.0",
	"express": "4.2.x"
}
}

Here sample app is depending on 3 other Node JS Modules: mypackage (My own Custom Module), async and express (Node JS Modules)

While defining dependencies version we can use some pattern matching syntax.

Scenario 1: Any available version with * character

"dependencies": {
   "mypackage": "*"
}

It will pickup any available version of mypackage module.

Scenario 2: Range selection with ~ symbol

"dependencies": {
   "mypackage": "~0.2.0"
}

It pickup any available version of mypackage module between >=0.2.0 and < 0.3.0(Exclusive).

In development mode, we always want our Node JS application to use latest available module from Node JS repository.

Scenario 3: Range selection with ^ symbol

"dependencies": {
   "mypackage": "^0.2.0"
}

It will pickup any available version of mypackage module between >=0.2.0 and < 1.0.0(Exclusive).

repository: This directive is used to specify the URL where your source code is live for other people to contribute to your module or to learn your module. Its syntax is shown below.

"repository": {
   <Define  your URL here>
}

Here we need to define two elements:

• Type of source to which you are going to provide URL
• url

We define these two elements in key-value pairs. Here key is element name and value is either type of source or url.

For example;

"repository": {
"type" : "git",
"url" : "https://github.com/journaldev/jd.git"
}

Complete package.json file example with mandatory and optional directives:

{
	"name" : "sample",
	"version" : "1.0.0"'
	"repository": {
		"type" : "git",
		"url" : "https://github.com/journaldev/jd.git"
	},
	"dependencies": {
		"mypackage": "1.0.0",
		"async": "0.8.0",
		"express": "4.2.x"
	}
}

How to create package.json in Enide Studio IDE?

We have already discussed in last post about how to setup Enide Studio 2014 IDE with Eclipse and also how to create a new Node.js project.

When we create new Node.js Project in Enide Studio, it will create a package.json file automatically with default values as shown below.

We will use this package.json file knowledge in coming posts to develop our Node JS full-fledged Applications.