Naveenchandar

Posted on Jun 30, 2021 • Updated on Jul 2, 2021

Package.json File explained!!!

#react #javascript #node #angular

If you've been working on javascript or related framework projects then definitely you came across the file named package.json and we might be curious why this file is included in our projects and why it's needed 🤔.

The main purpose of this file is to hold various metadata related to the project and it is used to give information to npm that allows to identify the project and its dependencies.

To create a package.json file manually you need to run a command npm init which will ask you a bunch of questions that is not compulsory. Just hit enter to complete those.You can change it later.
If you do want to answer these questions then you can run a command npm init -y which will create a file named package.json with the defaults.

Let's see the list of available options which npm has given us to make in this file.

name
If you've been working on some projects in local and if planning to publish it.
Two important things are name and versions. Both are required and it should be unique.
Name represents the name of your project.
There are some rules for defining names.

Must be less than or equal to 214 characters
should not begin with dot (.) or underscore(_).
should not have an uppercase letter in the name.
package name must not contain any non-url-safe characters (since name ends up being part of a URL) Please go through this link to find unsafe characters.
If needed you can check the npm registry whether the name is available or not.

version
This property defines the version of your project and it should follow semantic versioning guidelines.
Example

"version": "1.0.0"

description
This property is used to provide more information about the project and it helps people to discover your package as its listed in npm's search.
Example

"description": "A package to work with strings"

keywords
It's an array of strings.Keywords related to your project. This helps people discover your package based on the keyword search.
Example

"keywords": [
  "react",
  "Javascript"
]

homepage
This property is used to provide landing page url of your project.
Example

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

license
This property denotes the type of license in your project, whether this package can be used by others without any restrictions.To know more about license

bugs
This property is used to specify the project issue tracker and / or the email address to which issues should be reported. These will be helpful for people who encounter issues while using your package.
Example:

"bugs":{
  "url" : "https://github.com/owner/project/issues",
  "email" : "project@hostname.com"
}

people fields: author, contributors
This property specifies the number of contributors involved in developing this project.
Author is for single person and contributors is array of people.
Example:

"author": "abc@example.com https://www.abc.com/",
"contributors": [{
    "name": "example",
    "email": "example@example.com",
    "url": "https://www.example.com/#team"
}]
(email and url are optional).

scripts
This property contains commands that run at various times in the lifecycle of your package. It takes object with key being scripts we can with (npm run ) with the various command we give in the values.The key is the lifecycle event, and the value is the command to run at that point.
Example:

"scripts":{
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "lint": "eslint ./"
}

These are mostly terminal commands which helps us to execute specific task used during development. Learn more about npm scripts

dependencies
This is one of the most important key in your file and the entire reason to use this file. All your dependencies used in this project(various npm libraries installed via CLI) are listed here. when package is installed as npm install , after installation it will automatically added under the dependencies key.
Example:

"dependencies": {
 "react": "^17.0.1",
 "react-router-dom": "^5.2.0",
 "compression": "~1.7.4"
}

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

devDependencies
some packages are needed only for development and doesn't need for production. Those packages can be listed in this. An example would be eslint or nodemon. These are the packages we will be using while development.
To install a package as devDependency run

npm install --save-dev <packagename>

private
This property is either true or false. If you set it to true, then npm will refuse to publish it.
Example:

"private": true

engines
This property sets which versions of Node and other commands this project should work on.
Example:

"engines": {
  "node": ">= 6.0.0",
  "npm": ">= 3.0.0",
  "yarn": "^0.13.0"
}

browserslist
This property specifies which browser (along with versions) you want to support your project. If you are using latest ES features we need make sure all browsers supports it or if not then fallback/polyfills is needed. It's referenced by Babel, Autoprefixer, and other tools. To add the polyfills and fallbacks needed to the browsers you target.
You can check here whether the latest features has been supported by browser or not.

Example:

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

Note:
0.2% specifies that you want to support the browsers with at least 0.2% of global usage.
not dead means exclude browsers without official support in the last 24 months.
You can learn more about browserslist here.

main
This property specifies the entry point in your project. If someone installs your project and then uses import something from 'something', the file you named in this key will be the one gets imported.
If nothing is specified, it will be set to index.js by default.
Example:

"main": "src/main.js"

This package.json file will be the heart of any javascript/node project.Not all properties will be applicable to your project but we can make use of these properties to achieve some powerful benefits. Understanding the role of package.json file is important part of javascript ecosystem and it will make you more insightful!!🙂.

Thanks for reading this and have a great day 😃.
Lets meet in the next post 😉.

Top comments (23)

Lakshmanan Arumugam • Jul 1 '21

Good article @naveenchandar . well explained each options with example. recent days one option added in package.json. This option also useful for now a days.

Example:

"resolutions": {
    "d2/left-pad": "1.1.1",
    "c/**/left-pad": "^1.1.2"
  }

More info

Naveenchandar • Jul 3 '21

Yeah but this is available only on Yarn right?. Correct me if I'm wrong.

Lakshmanan Arumugam • Jul 3 '21 • Edited

Yes. I guess now a days most of the people using yarn only.

I Forgot to add this note: This option only useful for who using yarn package manager in their project.

Reaper • Jul 1 '21

small addition, a lot of people don't know about the
publishConfig key, you can use it to set the access and other variables so you can avoid doing the npm publish --access=public when working with scoped packages.

Might help someone.

Naveenchandar • Jul 1 '21

That's a great one to add 👏.

Doug Elkin • Jul 1 '21

The "homepage" property is used for a completely different purpose for projects using react-scripts. This is a bit frustrating, in my opinion.

Also, if your package is distributing both commonjs and ES modules, the "main" property should be the path to the commonjs module, and the "module" property should be the path to the ES module.

Naveenchandar • Jul 1 '21

Agreed 👍.

sakalpatil • Jul 1 '21

@naveenchandar : its best article, I did found any course which explain the package.json like you. Now I have clear understanding of package.json thanks Naveen