Menu

Package.json Explained

Shivangi Rajde 2 years ago 1 980

In this article we will understand a very important file in React projects, that is the Package.json file. You might be familiar with the package.json file if you have ever worked on any node.js, react, or NPM application.

Package.json

File package.json contains actual JSON, not just a JavaScript object literal. The main purpose of this file is to hold various metadata related to the project. The file is used to provide the information to the node package manager (NPM) that allows identifying the project and its dependencies.

The package.json file is a core element in the Node.js ecosystem and is also basic for understanding and working with Node.js, NPM, modern JavaScript, and JavaScript frameworks and libraries.

As we know that when working with any of the Node, NPM, JavaScript frameworks or libraries we would need to have an understanding of the package.json file, so let’s try to understand as much as possible and the knowledge required to work with any of the projects.

File structure

As the name already indicates that the data of the file should be in JSON format. So basically the file any package .json file can be

{

}

Confused, just the braces as package.json file? But yes There are no fixed requirements of what should be included in the package.json file for any application. The only requirement is that it should respect the JSON format. Let’s have a look at another example of the package.json file.

{
  "name": "first-file"
}


Here the property “name” indicates the name of the app or package, that’s contained in the same folder where this file lives. Many more properties can be included in the file, let’s have a look at the more complex package.json file.

Create a basic package.json file

Let’s try to create a package.json file using NPM and have a look the properties in the file. To create a file follow the steps given below:

Create Folder

mkdir Package_json

Initiate npm to create the package.json file

npm init –y

When creating the file we will be asked some questions about the project that we are creating and initiating the package.json file for. As we are creating the file for understanding the purpose of the file we will use the flag –y, which will be the yes answer for every question.


Running the command given above will create this package.json file

initialize npm
initialize npm
{
"name": "Package_json",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}

Let’s cut a long story short for understanding the meaning of the properties in the file.

  • Name: application/package name
  • Version: current version
  • Description: a brief description of the app/package
  • Main: entry point for the application
  • Private: if set to true prevents the app/package to be accidentally published on npm
  • Scripts: a set of node scripts we can run
  • Keywords: an array of keywords that associate with what our package does
  • Author: package author-name
  • License: license of the package

Properties in the package.json file
• name
• author
• contributors
• bugs
• homepage
• version
• license
• keywords
• description
• repository
• main
• private
• scripts
• dependencies
• devDependencies
• engines
• browserslist

Package.json of a project created using CRA

Let’s create a React project using Create-react-app. To create a project name demo-package-json run the command:

npx create-react-app demo-package-json

A new directory will be created with the name as the project name provided in the above command. The boilerplate project when creating a react project with CRA contains the directories and files as shown in the image below:

package.json folder structure
package.json folder structure

To understand more about CRA visit this link:

Understand how to Run and build React app:

Let’s have a look at how the package.json file looks when we create a react project with create-react-app

{
  "name": "demo-package-json",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.16.2",
    "@testing-library/react": "^12.1.3",
    "@testing-library/user-event": "^13.5.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-scripts": "5.0.0",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}
package.json code
package.json

Each of the attributes in the file has its importance in some way or the other. Where some of these are basic and clear from their names, some are not.

Properties in detail

Name

"name": "demo-package-json",

The property “name” indicates the name of the project and is optional if the project is private. This property is generally used when an NPM package is published, it will be used as an URL. Hence, when the package gets published the name is required and must be unique on the NPM repository.

Some of the points as referenced from the official docs should be kept in mind when providing names of the project
• The name must be less than or equal to 214 characters. This includes the scope for scoped packages.
• The names of scoped packages can begin with a dot or an underscore. This is not permitted without a scope.
• New packages must not have uppercase letters in the name.
• The name ends up being part of a URL, an argument on the command line, and a folder name. Therefore, the name can’t contain any non-URL-safe characters.
We can also check the NPM registry to see if there’s something by that name already before we get too attached to it. https://www.npmjs.com/

Version

"version": "0.1.0",

The property “version” indicates the current version of the package. It is an optional property is optional for private and required for public modules. Changes to the package should come along with changes to the version. The version number should be understandable by node-semver.


This property follows the semantic versioning (semver) notation for versions, which means the version is always expressed with 3 numbers: x.x.x.


The first number is the major version, the second the minor version and the third is the patch version.


There is a meaning in these numbers: a release that only fixes bugs is a patch release, a release that introduces backward-compatible changes is a minor release, and a major release can have breaking changes.

Private

"private": true,

The property “private” if set to true prevents the app/package to be accidentally published on NPM. This is a way to prevent the accidental publication of private repositories.

Dependencies

"dependencies": {
}

The property “Dependencies” is one of the most important keys in our file and the entire reason to use this file. All the dependencies used in the project are listed here. When we install a package using NPM or yarn, using the commands

npm install
yarn add

then the mentioned package is automatically inserted into this list.
Basic dependencies for react project, when created using CRA, are:

"dependencies": {
    "@testing-library/jest-dom": "^5.16.2",
    "@testing-library/react": "^12.1.3",
    "@testing-library/user-event": "^13.5.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-scripts": "5.0.0",
    "web-vitals": "^2.1.4"
  },

Note:

~ and ^ that we see in the dependency versions are notations for version ranges defined in semver as it follows semantic versioning.

Scripts

"scripts": {
}

The property “scripts” contains the aliases that we can use to access some of the react-scripts commands in a more efficient manner. It takes objects with keys being scripts we can with (npm run ) with the various command we give in the values. Here the key is the lifecycle event, and the value is the command to run at that point.


For example, running npm start in your command line will run react-scripts start behind the scenes. Similar is true for other attributes: build, test, etc.
Example:

"scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

eslintConfig

"eslintConfig": {
}

The property “eslintConfig” takes care of the code linting. It will look for and read automatically, or we can specify a configuration file on the command line. To understand more about ESLint refer to the link eslintConfig

Example:

  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },


browserslist

"browserslist": {
}

The property “browserslist” provides information about the browser compatibility of the app. It is the config to share target browsers and Node.js versions between different front-end tools.


Example:

"browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }

There are many other properties that we can use in the package.json file. To know more about the properties other than the properties described in the article above visit the official site .

Summary

After reading this article, we now have a clear understanding of the properties used in the package.json file. As we now understand that the package.json file is the heart of any JavaScript/node project. Not all the properties will be applicable to our project but we can make use of these properties to achieve some powerful benefits.

Some articles to learn more about React
What Is React?
How to install React.js with create-react-app?
Why use React?
Fundamentals of Routing
How to Improve React Performance with Lazy Loading?
Next.js: The Powerhouse Framework for React Projects

– Advertisement – BuzzMag Ad
Written By

1 Comment

1 Comment

  1. Mark Nadig says:

    Thanks for the article. I came here from a google search of package.json versioning. The “note:” paragraph could use some help 🙂 I did find this https://docs.npmjs.com/cli/v6/using-npm/semver. Perhaps you can add a link for future folks?

Leave a Reply

Your email address will not be published. Required fields are marked *