Understanding the package.json file

What is a package.json file

A package.json is a JSON file that exists at the root of a Javascript/Node project. It holds metadata relevant to the project and it is used for managing the project's dependencies, scripts, version and a whole lot more.

Creating a package.json file

There are two ways of creating/generating a package.json file.

• Npm or Yarn

To create the package.json file with npm, run npm init on your terminal.

To use this method, you need to have Node installed on your system.

To create the package.json file with yarn, run yarn init on your terminal.

To use the yarn method, you need to have Node and Yarn installed on your system.

Note: Throughout the course of this article, I would make use of npm commands for showing examples of how to do perform specific tasks, if you prefer making use of yarn, check here for the yarn CLI commands.

After running the command, it should ask for some information about the project and generate a package.json file in the root of your project. The generated file should look like the example below.

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

Note: You can also run npm init -y or yarn init -y to generate the package.json file with default values.

• Manually

To create the file manually, create a package.json file manually in the root of the project, and add an empty object with the required properties, which are name and version.
It should look like the example below.

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

Properties of a package.json file

name

The name property is a required field in the package.json file, it represents the name of the project. There are rules you need to follow when specifying a name for your project in the package.json file.

• must be lowercase
• must be one word
• can contain hyphens and underscores
• should not start with an underscore(_) or dot(.)

  "name": "package.json-mastery"

version

The version is also a required field in the package.json file. The property denotes the current version of the module for the project.
The rule required for the version field is that it needs to follow the semantic versioning guidelines e.g 1.0.2

  "version": "1.0.0"

description

The description property is used in describing and providing more information about the project.

  "description": "Mastery of the package.json file"

engines

The engines property is a JSON object of key/value pairs that are used to denote/specify the version of the libraries and runtimes on which the application should run.

 "engines": {
    "npm": "6.10.0",
    "node": "10.14.1"
  }

dependencies

The dependencies property denotes the list of the required modules/packages for your application to function. After installing a dependency, it is added to the dependencies list.

"dependencies": {
  "bcryptjs": "^2.4.3",
  "cors": "^2.8.5",
  "dotenv": "^6.1.0",
  "express": "^4.16.4",
}

To install a dependency, run npm i package or npm install package on your terminal. Where the package is the name of the package you are trying to install.

For example, to install axios dependency, run npm install axios on your terminal.

devDependencies

The devDependencies property denotes the list of modules/packages that are not required for your application to function. They are also known as development dependencies.

 "devDependencies": {
    "eslint": "^4.19.1",
    "mocha": "^6.2.0",
    "nodemon": "^1.19.1",
  }

To install a devDependency, run npm i package --save-dev or npm install package -D on your terminal. Where the package is the name of the package you are trying to install.

For example, to install chai devDependency, run npm install chai --save-dev on your terminal.

scripts

The script property takes a JSON object of key/value pairs. Each script can be used in performing different sets of tasks, like building, testing, linting the application.
You can run the scripts by running npm run scriptname, or yarn scriptname on the terminal.

  "scripts": {
    "start": "node index",
    "dev": "nodemon index",
    "test": "jest",
    "lint": "eslint ./server",
  }

For example, to execute the dev script in the example above, run npm run dev or yarn dev on your terminal.

main

The main property serves as the entry point of your application and should point to the file that serves as the entry point to your application.

  "main": "app.js"

homepage

The homepage property is used to specify the landing page for the application/package.

 "homepage": "https://github.com/Easybuoy/package.json-mastery#readme",

private

The private property is false by default but can be set to true to prevent the application/package to be published.

  "private": true

license

This property denotes the type of license that's being used by the project

"license": "MIT"

author

This property denotes the creator/owner of the project

"author": "Ezekiel Ekunola"

repository

The repository keyword is a JSON object of key/value pairs that are used to specify the version control system being used to manage the application. You can specify the type of version control being used,
the URL to the repository, as well as an optional directory within the repository.

"repository": {
    "type": "git",
    "url": "git+https://github.com/Easybuoy/package.json-mastery.git"
  }

bugs

The bugs property is used to point to the issues page of the repository for the application or anywhere the project issues can be reported.

 "bugs": {
    "url": "https://github.com/Easybuoy/package.json-mastery/issues"
  }

keywords

The keywords property is an array of keywords that helps in identifying your project or make your project easier to find when a user searches those keywords.

  "keywords": ["node", "javascript", "npm", "yarn"]

Custom Properties

The package.json file can also be used for package specific commands like Babel, ESLint, Jest and lots more. You can find the usage in the package documentation.

Find an example of a custom property for Jest below.

  "jest": {
      "snapshotSerializers": [
        "enzyme-to-json/serializer"
      ]
    }

After combining all the properties explained above, we can end up having a package.json file looking like the example below

{
  "name": "package.json-mastery",
  "version": "1.0.0",
  "description": "Mastery of the package.json file",
  "private": false,
  "main": "index.js",
  "scripts": {
    "start": "node index",
    "dev": "nodemon index",
    "test": "jest"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Easybuoy/package.json-mastery.git"
  },
  "keywords": [
    "node",
    "javascript",
    "npm",
    "yarn"
  ],
  "author": "Ezekiel Ekunola",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/Easybuoy/package.json-mastery/issues"
  },
  "homepage": "https://github.com/Easybuoy/package.json-mastery#readme",
  "engines": {
    "npm": "6.10.0",
    "node": "10.14.1"
  },
  "dependencies": {
    "bcryptjs": "^2.4.3",
    "cors": "^2.8.5",
    "dotenv": "^6.1.0",
    "express": "^4.16.4"
  },
  "devDependencies": {
    "eslint": "^4.19.1",
    "mocha": "^6.2.0",
    "nodemon": "^1.19.1"
  },
  "nyc": {
    "exclude": [
      "server/app.js",
      "server/config/",
      "server/build"
    ]
  }
}

Conclusion

In this article, we've been able to see what a package.json file is, how to create it, the different properties and their use cases.

There are still so many more properties that can be specified in the package.json file, if you want to go in-depth, check here.

If you have any questions or feedback about this article, feel free to leave a comment.

Thanks for reading.

This article was originally published on my blog.