Package.json – A Place to Manage our Project Configurations

The ‘package.json’ is the project configurations file for our NodeJS projects. It supports both of the leading package manager tools- npm and yarn.

The npm and yarn use this file to identify dependencies, run and manage various scripts for testing, building, deploying etc. The configurations in the file also help us mange project versions, repository location, the authors, license and so many other details.

A Sample project.json file

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My Project description.",

  "main": "index.js",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
  },
  "dependencies": {
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "react-scripts": "4.0.0",
    "web-vitals": "^0.2.4"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^5.11.5",
    "@testing-library/react": "^11.1.0",
    "@testing-library/user-event": "^12.1.10",
  },
  "repository": {
    "url": "https://mycompany.com/my-project",
    "type": "git"
  },

  "author": "Your Name <you@mycompany.com>",
  "license": "MIT"
}

The Key Fields for Common Usage

These are some of the key fields commonly used across most of our projects and quite important to start with.

  • name – It’s the identifier of our package. It should be unique, if we are publishing it to the global registry.
  • version – It’s the version number of our package. NodeJS and all the standard libraries follow Semver standards. In Semver standard a version number follows a format of X.X.X which stands for [Major Release].[Minor Release].[Patch Release]
    • Major Release : It consists of major API changes including incompatible API changes. It may include changes entitled for minor and patch releases.
    • Minor Release : It includes backward compatible functionality changes. It may include changes entitled for patch releases.
    • Patch Releases : It includes only bug-fixes and security patches.
  • description – It’s a field to provide a description for our project.
  • main – This becomes the entry point when we execute a NodeJS project. The default file being index.js.
  • scripts -We can save our command line scripts with short names.
    • In the above example : to run the start script we can use ‘npm run start
  • dependencies – This lists the external libraries which need to be bundled with the production build.
  • devDependencies – This lists the libraries used for supporting development such as testing, build, quality analysis etc.

Some Other Useful Fields

We can find the complete list of fields here : https://docs.npmjs.com/files/package.json . Here is a list of few other useful fields :

  • repository -We can use this field to specify the location of the source code.
  • private – We should make it false, to be able to publish it on npm
  • engines - This specifies the versions of NodeJs the project works on
  • browserlist - We can use this field to list the browsers (and their versions) we want to support
  • author – We can specify the list of authors under this.
  • contributors – It follows the same format as author –
  • license – Legal terms of your package and what is the allowed usage of the code in your package.

Creating A New Project using npm init

To create a project from scratch we can use a ‘npm init’ which will create a base project.json file for us as follows.

F:\nodejs\node01\first-project>npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (first-project) first-project
version: (1.0.0)
description: Learing to create a NodeJS project from scratch
entry point: (index.js) main.js
test command: echo 'Hello World'
git repository: none
keywords: Tutorial
author: SpectrumsJS
license: (ISC) UNLICENSED
About to write to F:\nodejs\node01\first-project\package.json:

{
  "name": "first-project",
  "version": "1.0.0",
  "description": "Learning to create a NodeJS project from scratch",
  "main": "main.js",
  "scripts": {
    "test": "echo 'Hello World'"
  },
  "repository": {
    "type": "git",
    "url": "none"
  },
  "keywords": [
    "Tutorial"
  ],
  "author": "SpectrumsJS",
  "license": "UNLICENSED"
}


Is this OK? (yes) yes