What is package.json ?

package.json is a file on a project that uses javascript packages and depicts javascript related information about a project. The project would be working with node and installs its packages/dependencies with npm.

For you to have a project with a package.json file,

• You must have node installed and running. You can install node using node version manager (nvm) to install node and npm on your local machine.

Creating a package.json file

There are 3 ways to go about it.

1 . New project boilerplate: from creating a new react or vue project via the command line. But not restricted to the frontend centric project libraries and frameworks obviously.

2 . Creating a package.json file via the command line: Depending on your preferred package manager, npm or yarn.

npm init -y

or

yarn init -y

You can create a package.json file and the -y is to speed up the process by answering yes to all the yes or no questions involved.

3 . Manually: You can easily create a package.json file by going to the root of your project and creating a file in that name and adding content in json format as such.

{
   "name": "menu_order",
   "version": "1.0.0"
}

File Structure

There is no fixed requirement for what is suppose to be on the file but there are some common keys that will be found in a number of package.json file around.

• version: This is the version of your project. Version numbers usually start from 1.0.0.
• name: This is the name of your project. As seen above in the manually created package.json file, the name of my project is menu_order.
• description: This is a description of what the project entails.
• main: This is the entry point to which your application runs.
• private: This prevents the project from been published on npm if set to true.
• scripts: This is key contains a set of node scripts that you can run for different aspects of your project. This could be starting the application, to building the application, to deploy the project, to testing on local and develop e.t.c.
• engines: This is the versions of node and npm on which the application runs.
• dependencies: This is the most important key in the package.json file. This has the list of npm packages as dependencies on the application that is required for the application to run on production.
• devDependencies: This contains the list of dependencies that the application need to test and run locally and they are not needed in production environment.
• browserlist: This indicates the browsers and versions that your application supports.

Here is an example of a package.json file.

{
  "name": "menu_order",
  "version": "1.0.0",
  "description": "The application is for ordering food and drinks.",
  "main": "index.js",
  "engines": {
    "node": "15.8.0",
    "npm": "7.14.0"
  },
  "scripts": {
    "start": "cross-env NODE_ENV=production node index.js",
    "dev": "cross-env NODE_ENV=development nodemon index.js",
    "test": "cross-env NODE_ENV=test jest --verbose --runInBand",
    "start:test": "cross-env NODE_ENV=test nodemon index.js"
  },
  "keywords": [
    "nodejs",
    "expressjs"
  ],
  "author": "Toluwalase Akintoye",
  "license": "MIT",
  "dependencies": {
    "bcryptjs": "^2.4.3",
    "body-parser": "^1.19.0",
    "cors": "^2.8.5",
    "dotenv": "^10.0.0",
    "express": "^4.17.1",
    "jsonwebtoken": "^8.5.1",
    "mongoose": "^5.12.14",
    "mongoose-unique-validator": "^2.0.3",
    "morgan": "^1.10.0"
  },
  "devDependencies": {
    "cross-env": "^7.0.3",
    "jest": "^27.0.4",
    "nodemon": "^2.0.7",
    "supertest": "^6.1.3"
  }
}

Semantic Versioning

Each installed package have different versions based on releases and packages depends on other packages and they express those dependencies via version ranges.

All versions have 3 digits, x.y.z => 1.0.0.

• x stands for major version. Which means the number increases when there is an incompatible API changes.

• y stands for minor version. Which means that when there is a backward-compatible functionality. The current version works on the older applications that the older versions were on before.

• z stands for patch version. Which means that when there are backward-compatible bug fixes.

Semantic version symbol rules

• ^: Updates does not affect the leftmost zero i.e from 1.0.0 to 1.0.1 or 1.1.0 but not to 2.0.0. The major version remains unchanged.

• ~: Updates only affects the patch version i.e 1.0.0 to 1.0.1, one level up.

• >: Updates package to any higher version than the specified version i.e from >1.0.0 to 2.0.0.
• >=: Updates package to any specified or higher version i.e >=1.0.2 to 1.5.0.
• <: Updates package to any version lower than the specified version i.e <1.5.0 to 1.4.1.
• <=: Updates package to any specified or lower version i.e <=1.5.0 to 1.4.9.
• =: Updates package to the exact version i.e =1.2.0 to 1.2.0.
• -: Updates package to the version ranges i.e 1.0.0-1.2.0.
• ||: Updates package to combine sets 1.0.0 || >=1.1.0 <1.2.0.
• latest: Updates package to the latest version.
• *: Updates package to any version.

That's basically the all on what your package.json is all about.

Happy coding!!!

Illustration from Undraw.