DEV Community

loading...
Cover image for Package.json File explained!!!

Package.json File explained!!!

Naveenchandar
Optimistic human 🧍 and trying hard not to procrastinate things!!!😜 Passionate about Web Development and have a keen interest in learning new technologies.
Updated on ・4 min read

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.

  1. Must be less than or equal to 214 characters
  2. should not begin with dot (.) or underscore(_).
  3. should not have an uppercase letter in the name.
  4. 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.
  5. 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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
]
Enter fullscreen mode Exit fullscreen mode

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

"homepage": "https://github.com/owner/project#readme"
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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).
Enter fullscreen mode Exit fullscreen mode

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 ./"
}
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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

"private": true
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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"
    ]
  }
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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 😉.

Discussion (24)

Collapse
lukeshiru profile image
LUKESHIRU

2 tips worth adding:

  • In VSCode, you can hover every property in a package.json file and if is a standard property (such as name, description, version and so on), it shows a description for it.
  • There is a nifty package called fixpack that organizes your package.json always the same way, so if you have several packages and you want to keep the order of the properties consistent across them, fixpack is great for that.

Cheers!

Collapse
naveenchandar profile image
Naveenchandar Author

Thanks mate..I was not aware of fixpack earlier. Glad to know.👏

Collapse
barelyhuman profile image
Reaper

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.

Collapse
naveenchandar profile image
Naveenchandar Author

That's a great one to add 👏.

Collapse
lakshmananarumugam profile image
Lakshmanan Arumugam

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"
  }
Enter fullscreen mode Exit fullscreen mode

More info

Collapse
naveenchandar profile image
Naveenchandar Author

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

Collapse
lakshmananarumugam profile image
Lakshmanan Arumugam • 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.

Collapse
duhdugg profile image
Doug Elkin

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.

Collapse
naveenchandar profile image
Naveenchandar Author

Agreed 👍.

Collapse
sakalpatil profile image
sakalpatil

@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

Collapse
naveenchandar profile image
Naveenchandar Author

Thanks a lot. 🙏

Collapse
forkbikash profile image
Bikash Mishra

Thanks for sharing

Collapse
naveenchandar profile image
Naveenchandar Author

Pleasure..😊

Collapse
cenacr007_harsh profile image
KUMAR HARSH

Nice article.

Collapse
naveenchandar profile image
Naveenchandar Author

Thank you 😊.

Collapse
goodok21 profile image
Alexander Eric

Nice article but please change the title 😅

Collapse
naveenchandar profile image
Naveenchandar Author

😃.. I'm bad at creating title. Can you suggest me some good one ?😉

Collapse
omarfarooq profile image
Mohammad Omar Farooq Khan

Some Titles :

  • What is Package.json 🤔
  • Complete Explanation of Package.json
Collapse
goodok21 profile image
Alexander Eric

Depends on content of this article:

  • Simple explanation of the package.json
  • Package.json basics
Collapse
bernardbaker profile image
Bernard Baker

Setting it to private doesn't stop it being published. Unless you're only working on public packages.

Collapse
nicolasmontielf profile image
Nicolás Montiel

Great article man, Thank you very much!

Collapse
naveenchandar profile image
Naveenchandar Author

Thank you 😊

Collapse
coder023 profile image
Mukul Borole

Nice article 👍. This article revised all my concepts.

Collapse
naveenchandar profile image
Naveenchandar Author

Thank you..😊