Essential insights into package.json: Navigating project dependencies

Essential insights into package.json: Navigating project dependencies

Unlocking the power of package.json: Everything you need to know

A few days ago I had a problem with a package.json at my work and I had to investigate some details to solve it. I found out that there are a few things that are didn't know. In this article I will try to explain what a package.json file is, what it is for and how to manage it in a front-end project.

What is a package.json?

The package.json file is generated by default for all node.js projects, when you run the command npm init automatically starts asking you a few questions about the project, then it generates the package.json file.

If you are here, you may be front-end and may know package.json because your Angular, React or Vue project.

The main purpose of this file is to contain information about the npm packages installed for the project.

A typical package.json file might look like this:

  "name": "my-app",
  "version": "0.0.0",
  "description": "",
  "keywords": [],
  "author": "Rubén Peregrina",
  "license": "ISC",
  "scripts": {
  "private": true,
  "dependencies": {
  "devDependencies": {

What is each field?

Let's look at each field in package.json:

  • name: The name of the project, library, or package, ideally matching the repository.

  • version: Version of the package.

  • description: Short project description.

  • main: Entry point for the project, usually index.js (for Node) or index.html (for browsers).

  • scripts: Collection of project scripts.

  • keywords: Relevant keywords for project searchability.

  • author: Author's name, usually including contact information or a URL.

  • license: Project license type, commonly ISC.

  • dependencies: Packages required for production environment.

  • devDependencies: Packages needed for development environment.

  • homepage: URL of the project's homepage.

  • repository: Repository URL (type and route).

  • bugs: Object containing the project's issues page URL.

Managing dependencies

The main focus of this file is to specify dependencies, providing an efficient way of managing project dependencies.

There are several types of dependencies, let's review each of them:

dependencies: Essential project dependencies, added using npm install my-dependency

devDependencies: Dependencies used during development, added using the --save-dev flag

optionalDependencies: These are dependencies that will not cause installation failure of an application or project. NPM will ignore them if they fail. The application will still work as expected regardless of whether these dependencies are present or not. Use the --save-optional flag to install them as optional.

bundledDependencies: Used to specify an array of dependencies that should be bundled together with the package itself when it is released or distributed. If an NPM package has dependencies listed in bundledDependencies, those dependencies will be automatically installed along with the main package.

peerDependencies: Used to specify dependencies that are necessary for the package to work properly, but must be provided by the environment in which the package is installed. NPM will give a warning if some peer dependencies are missing.

Formats for specifying versions

There are several formats to specify which version you are using:

1.2.2: Exactly version 1.2.2

^1.2.2: The latest version compatible with version 1.2.2

~1.2.2: Works for versions such as 1.2.2, 1.2.3, 1.2.4,...

~1.2: Works for versions like 1.3, 1.4, 1.5,...

1.2.x: Works with any patched version of 1.2

1.x: Works for any minor version of the package’s 1 version

\>=1.2: Version 1.2 or higher. You can also use <, <= or >

1.2.2 4.1.1: Versions 1.2.2 through 4.1.1 (inclusive)

Multiple possible version ranges can be specified by separating each range with ||


The package.json file serves as a crucial component in Node.js projects, facilitating efficient management of dependencies and project configurations. Understanding its structure and functionality is essential for seamless project development and maintenance.

With this article you have learnt a bit more about the structure of the package.json and how it works, there are still questions in the air that we can clear up in the next articles.

Did you find this article valuable?

Support Rubén Peregrina by becoming a sponsor. Any amount is appreciated!