Himanshu Gupta

Posted on Feb 24, 2023 • Edited on May 30, 2023

Everything about package.json

#javascript #node #angular #programming

Package.json is a file in the root directory of a Node.js project that holds various information relevant to the project. This file gives information to npm that allows it to identify the project as well as handle the project’s dependencies.

A package.json file:

lists the packages your project is dependent on
specifies versions of a package that your project can use/ using
makes your build reproducible, and therefore easier to share with other developers
contains other metadata such as a project description, the version of the project in a particular distribution, license information, even configuration data etc
is vital to both npm and the end-users of the package
How to create the package.json file?
Open the command line, navigate to the root directory of your project.
Run the following command
npm init
Answer the questionnaire in the command line.

You can run the following command if you want to create the file using default values.

npm init --yes

Understanding the Properties of package.json
name —
This is the most important and required field in the package.json file. This should represent the name of the project.

Your name should be unique (when publishing to NPM) ☝;
If you have proper NPM organization register, you can use your package with so-called scope e.g. @organization/package;
The character length of the name should be no bigger than 214 characters including scoping;
No capped letters and underscore (_) or dot (.) on the beginning;
You can use only URL-safe chars — your name will most likely be typed by others in terminals and used as URL at NPM page;
"name": "my-blog-backend",

version —
This is also a mandatory property of the package.json file just like the name. This property represents the version of the module of the project. You will change this every time you want to publish a new version of your package. Try to follow semantic versioning (more details on what this is later). My suggestions are as follows:

When you first create a package, use 0.0.1.
Whenever you fix a bug, you want a “patch” revision. Increment the last digit.
1.0.1 → 1.0.2 3.4.9 → 3.4.10
Whenever you add a new feature, soft-deprecate (i.e. discourage) an existing feature, or do anything else that doesn’t break code that previously worked fine, you want a “minor” revision. Increment the second-to-last digit and set the last digit to zero.
1.0.1 → 1.1.0 3.9.0 → 3.10.0 0.3.5 → 0.3.6*
Whenever you hard-deprecate (i.e. remove) an existing feature, change the behavior of something, or otherwise do anything that will break code that worked fine on a prior version, you must use a “major” revision. Increment the first digit and set the other two to zero.
1.1.3 → 2.0.0 10.1.3 → 11.0.0 0.3.5 → 0.4.0* 0.0.3 → 0.0.4*
Note the examples with an asterisk. For versions below 1.0.0, a patch revision is not possible and the other two types shift down; incrementing the second-to-last digit is major and the last digit is minor. For versions below 0.1.0, this is even more severe, since every version bump is a new major version.

This is why updating from 0.0.X to 0.1.0 and from 0.X.X to 1.0.0 are what I like to call "maturity" revisions; they completely change the meaning of each digit. As good practice, try to reduce the number of major versions you make after 1.0.0, but use as many minor and patch versions as you'd like.

As a notation guide, semantic versions are usually prefixed with a “v” outside of package.json. When referring to version 1.2.3 in a GitHub issue, for example, say "v1.2.3".

You also may want to note that alpha, beta, and release candidate versions are supported by semantic versioning. For example, 1.0.0-alpha.1, 2.2.0-beta.4, 0.3.0-rc.0. Typically, the patch version is unset for these prerelease versions, and they aren't downloaded by package managers unless the user requests a prerelease version.

"version": "1.0.0",
description —
You can type in the description of the project with more specifics to understand the project as a string. This helps people discover your package, as it’s listed in npm search.

"description": "This project is the personal blog",
main —
The main field represents the file which is the primary entry point to your program. This should point to the file that serves as the entry point to your application.

"main": "server.js",
scripts —
The “scripts” property is a dictionary containing script commands that are run at various times in the lifecycle of your package. The key is the lifecycle event and the value is the command to run at that point.



"scripts": {
  "start": "npx babel-node src/server.js",
  "dev": "npx babel-node src/server.js",
  "test": "echo \"Error: no test specified\" && exit 1",
  "lint": "eslint ./server"
},

people fields: author, contributors —
The “author” is one person. “contributors” are an array of people. We can use either of the fields according to our needs to list the people involved in the project.



"author": {
  "name": "Himanshu",
  "email": "support@alxoo.com",
  "url": "https://alxoo.com/"
},

author (strongly recommended) —
The name (and optionally email and website) of the author of the package. Optimally, you will use your full name here, but if you’re not comfortable doing so, your online alias will suffice. The field can take one of two formats:

"Your Name youremail@alxoo.com (https://alxoo.com)"
or



{
  "name": "Himanshu",
  "email": "youremail@alxoo.com",
  "url": "https://alxoo.com"
}

The email and website are optional, but you must add your name or alias.

New package.json:



{
  "name": "alxoo",
  "version": "0.0.1",
  "description": "Fast Unicode to Catlang converter",
  "author": "Cat <cat@alxoo.com>"
}

bugs —
This field contains the URL to your project’s issue tracker and/or the email address to which issues should be reported. These are helpful for people who encounter issues with your package.



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

homepage —
The URL to the project homepage.

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

keywords —
This helps people discover your package as it’s listed in npm search You can add the keywords in it as an array of strings.



"keywords": [
    "node",
    "vue",
  ],

private —
If you set “private”: true in your package.json, then npm will refuse to publish it. The default value will be false .

dependencies —
Dependencies are specified in a simple object that maps a package name to a version range. The version range is a string that has one or more space-separated descriptors.



"dependencies": {
  "express": "^4.17.1"
},

devDependencies —
If someone is planning on downloading and using your module in their program, then they probably don’t want or need to download and build the external test or documentation framework that you use.



"devDependencies": {
  "@babel/cli": "^7.12.8",
  "@babel/core": "^7.12.9",
  "@babel/node": "^7.12.6",
  "@babel/preset-env": "^7.12.7"
}

repository —
Specify the place where your code lives. This is helpful for people who want to contribute. If the git repo is on GitHub, then the npm docs command will be able to find you.



"repository": {
  "type" : "git",
  "url" : "https://github.com/npm/cli.git"
}
"repository": {
  "type" : "svn",
  "url" : "https://v8.googlecode.com/svn/trunk/"
}

license —
You should 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.

“license”: “ISC”,
Below is the example of the package.json file that has all the fields that I have explained here. There are still many other fields in package.json. You can find more about them here.



{
    "name": "my-blog-backend",
    "version": "1.0.0",
    "description": "This project is the personal blog",
    "private": true,
    "main": "index.js",
    "scripts": {
      "start": "npx babel-node src/server.js",
      "dev": "npx babel-node src/server.js",
      "test": "echo \"Error: no test specified\" && exit 1",
      "lint": "eslint ./server"
    },
    "keywords": [
      "node",
      "vue"
    ],
    "repository": {
      "type": "git",
      "url": "https://github.com/npm/cli.git"
    },
    "author": {
      "name": "Sanchitha",
      "email": "s@sharma.com",
      "url": "http://wordspoolsite.wordpress.com/"
    },
    "bugs": 
    {
      "url": "https://github.com/owner/project/issues",
      "email": "project@hostname.com"
    },
    "homepage": "https://github.com/owner/project#readme",
    "license": "ISC",
    "dependencies": {
      "express": "^4.17.1"
    },
    "devDependencies": {
      "@babel/cli": "^7.12.8",
      "@babel/core": "^7.12.9",
      "@babel/node": "^7.12.6",
      "@babel/preset-env": "^7.12.7"
    }
  }

engines (optional) —
The environments in which your library will work. This is only applicable for libraries that support Node.js (e.g. a CSS library shouldn’t use this field). If your library does not use modern features of JavaScript (such as async iterators), you also don’t need to specify this field. The format is as follows:



{
  "node": ">=0.10.3 <15"
}

For now, node is the only key of the engines field that you'll need to use.

Suppose catlang-encoder needs support for ES6 features such as Promise

directories —
directories may be one of these mysterious fields that not many know what it exactly does. 🤔 I'll tell you - it's mostly just meta-info. Exactly two fields provide some functionality and nothing else. Of course, all of them should have a form of string pointing to different directories.

lib - meta info about where your library is exactly located in your package;
bin - directory where all your executable files are located. Can be used instead of providing different files, one by one, with bin property. Know that you cannot use these two properties together - only one of them;
man - directory where all your man pages are located. You can use this instead of providing an array of files through man property. It's certainly less tiresome;
doc - meta info about directory where markdown documentation for a given package is located;
example - meta info about directory where you have example code;
test - meta info about directory where your test files are located;
Keep in mind that, as NPM official documentation mentions, this data can be used in the future to provide some additional features e.g. nice documentation or whatever…

Thank you for keeping reading

Top comments (7)

Morgan Wowk • Feb 25 '23

Great topic to cover! I love seeing folks zoom in on topics like this. It's easy enough to rely on copy and pasting npm install <your-package>, or following a tutorial that builds your package.json for you, without understanding how the end result is working.

Having a resource like this can help so many people be more self-sufficient and truly own their package.json.

Thank you for this!