The package.json File Guide

If you work with or interact with a JavaScript project, frontend project or a node.js project you surely know about the package.json file.

What is package.json file?

The package.json file is kind of manifest for your project. It is used to store the metadata related to the project as well as to store the list of dependency packages.

1. The package.json file is used to give information to npm that allows it to identify the project as well as handle all the project’s dependencies.
2. The package.json file makes it easy for others to install and manage the packages related to the project.
3. The package.json file contains metadata such as a project description, the version of the project in a particular distribution, license information, and many more things.
4. If you want to store any dependency or any package related to your project then you need to create package.json file

Where you can find package.json file?

The package.json file is normally present at the root directory of a project folder structure.

How to create your own package.json file?

1. First, create a folder in your directory and go to that folder by using the following command

mkdir demo

cd demo

2. Then type npm init on the command line [ npm init <initializer> can be used to set up a new or existing npm package. ]

npm init

Note: You can also use yarn in place of npm. Just replace the npm word with yarn.

3. While creating a package.json file, it will ask for some information, like version, description and many more, as shown below.

4. If you want to create a package.json file without giving the answer to the question then write the following command on the command line

npm init --yes

5. Using the npm init command with the - -yes or -y flag. It will create a default package.json using information extracted from the current directory

After that, your package.json file will look similar to this. 

Information of content present inside the package.json file:

Now you have package.json file in your folder. Open the file on the editor you want, you can see the name, version, licenses and many other things.

We’ll see what it is one by one.

1. Name:

The name field describes the name of your project, directory or the name of your app. You can give any name to your app, just you need to follow a specific pattern, that it should be in lowercase and can contain hyphens and underscores.

In the package.json file you can see the name field in the following way:

{
  "name": "demo"
}

2. Version:

version is the current version of your app. The version field must be of form x.x.x.

The version field is also used by npm to make sure the right version of the package is being installed.

Generally, it’s in the major.minor.patch format

For E.g. 

major.minor.patch

1.0.2

Here, Major, minor and patch represent the different releases of a package.

In package.json file sometimes you see the ‘~’(tilde) and ‘^’ (caret) signs in front of the version of the package. It is used to designate which patch and minor versions to use respectively.

For E.g

1. if you see ~1.0.3 it means to install version 1.0.3 or the latest patch version such as 1.0.5.

2. If you see ^1.0.3 it means to install version 1.0.3 or the latest minor or patch version such as 1.1.0.

In the package.json file you can see the name field in the following way:

{
  "version": "1.0.0"
}

3. Description:

The description field is used to describe the project in one line or else you can keep as it is, it will take an empty string.

It also helps people discover your package, as it’s listed in the npm search.

For e.g

{
  "description": " "
}

4. License:

The license property is used to specify a license for your package so that people know how they are permitted to use it, and any restrictions you’re placing on it.

While there are some ways you can use the license property of a package.json file (to do things like dual-licensing or defining your own license), the most typical usage of it is to use an SPDX License Identifier — some examples that you might know are MIT, ISC.

Inside your package.json, you can see the licensed property with an MIT license look like the following:

{
  "license": "ISC"
}

5. Main:

The main field is used to show the primary entry point to your program.

In a Node.js application, when the module is called with a require statement, the module’s exports from the file named in the main property will be what’s returned to the Node.js application.

For eg, if the user installs a package “express” and then does require(“express”) in the application, then your export object of the main module will be returned.

Inside your package.json, the main property would look like this:

{
  "main": "index.js"
}

6. Repository:

The repository field of a package.json file is in the array format that defines where the source code of the project lives. Typically, for open source projects, this would be a public GitHub repository or Bitbucket repository. In the repository field, you can see the array that is nothing but type and URL.

The type is used to show the version control for eg.git and the URL is nothing but where your project is stored either on GitHub or bit bucket.

Inside your package.json, the repository property would look like the following:

"repository": 
 {
   "type": "git",
   "url": "https://github.com/snehal9/demo"
 }

7. Private:

Private is one of the most important attributes. The use of this field is if you set private as true in your package.json, then npm will refuse to publish it within the npm ecosystem. In this way, you can prevent the accidental publication of private repositories.

Inside your package.json, the private property would look like the following:

{
  "private": true
}

8. Dependencies:

The dependencies field contains all the required node_modules and versions required for the application in the production environment. In the following eg, it contains four dependencies, which allow us to use react, react-dom, react-router-dom and react-scripts in our JavaScript. react-scripts is a library that provides a set of useful development scripts for working with React.

In the below eg, the react version is specified as ^16.12.0, which means that npm will install the most recent major version matching 16.x.x. Or else if you see something like ~16.12.0 in package.json, it means that it will install the most recent minor version matching 16.12.x.

In order to add a package under dependencies, use — save at the installation time.

For example,

npm install <package-name> --save

This lists the package by default under dependencies with its version number.

"dependencies":
  {
    "react": "^16.12.0",
    "react-dom": "~16.12.0",
    "react-router-dom": "5.1.2",
    "react-scripts": "3.3.0",
  }

9. DevDependencies:

DevDependencies lists out the packages required for development and testing.

In order to add a package to the devDependencies list, while installing you have to specify it as a dev dependency by writing --save-dev

For example, npm install <package-name> --save-dev

By using the above command the package will be added to the list of devDependencies property.

E.g

"devDependencies": 
    {
      "enzyme": "3.10.0",
      "enzyme-adapter-react-15": "1.4.1",
      "enzyme-adapter-react-16": "1.15.1",
      "eslint": "6.7.2",
    }

10. Scripts:

The script property is used to specify aliases that you can use to run any command. For example, if you want to run a node application, then you can write the command for running your application. There can be other scripts or commands as well, such as lint, deploy any many more. 

For example, when using lint, you can write the following, here I am linting all files.

“lint”: “eslint ‘./src/**/*.{ts,tsx}’”

Following are the e.g of script property:

"scripts":
 {
   "start": "node app.js",
   "lint": "eslint './src/**/*.{js}'"
 }

11. Homepage :

homepage property is used to specify the URL to the project homepage. This becomes handy in your react applications when you use the gh-pages, where it deploys your build directory to your homepage.

For e.g

{
   "homepage": "https://github.com/owner/project#readme"
}

I hope your understanding of the package.json file is better now.

Happy Coding :)