The package.json file is an essential component in many Node.js-based app codebases. If you work with JavaScript or have interacted with a JavaScript project, Node.js, or a frontend project, it’s likely that you are familiar with the package.json file.

But what exactly is it for? What should you know about it, and what can you do with it? In this guide, we will explore the package.json file, its structure, and its properties.

The file structure

A package.json file is a manifest for your project. While there are no fixed requirements for what should be in a package.json file for an application, it must respect the JSON format to be readable by programs that access its properties programmatically.

Here’s an empty package.json file as an example:

{

}

However, if you are building a Node.js package that you want to distribute over npm, there are specific properties you must include to help others use it.

Properties breakdown

The package.json file can contain various properties. We’ll break down some of the essential ones below:

name

The name property sets the package name. It should be less than 214 characters and can only contain lowercase letters, hyphens (-), or underscores (_). This property is crucial when publishing a package on npm as it determines the package’s URL.

author

The author property lists the package author’s name. It can be specified as a string or an object containing the author’s name, email, and URL.

contributors

The contributors property lists one or more contributors to the project. It can also be specified as an array of strings or an array of objects containing the contributor’s name, email, and URL.

bugs

The bugs property links to the package’s issue tracker, typically a GitHub issues page.

homepage

The homepage property sets the package’s homepage URL.

version

The version property indicates the current version of the package. It follows the semantic versioning (semver) notation, consisting of three numbers: x.x.x (major.minor.patch).

license

The license property indicates the package’s license.

keywords

The keywords property contains an array of keywords that associate with what your package does. It helps with discoverability on npm’s website.

description

The description property contains a brief description of the package. It’s especially useful when publishing the package on npm.

repository

The repository property specifies where the package repository is located. It can be specified as a string with a prefix indicating the version control system or as an object containing the URL and type.

main

The main property sets the entry point for the package. It determines where the application will search for module exports when importing the package.

private

The private property, when set to true, prevents the package from being accidentally published on npm.

scripts

The scripts property defines a set of Node.js scripts that can be run using npm run or yarn. It allows you to automate various tasks during development.

dependencies

The dependencies property lists the npm packages installed as dependencies. These packages are required for the package to run correctly.

devDependencies

The devDependencies property lists the npm packages installed as development dependencies. These packages are only needed during development and not required for the package to run in production.

engines

The engines property sets the versions of Node.js and other commands that the package works on.

browserslist

The browserslist property tells which browsers and versions the package supports. It’s used by tools like Babel and Autoprefixer to add the necessary polyfills and fallbacks.

Package versions

In the description above, you might have noticed version numbers like ~3.0.0 or ^0.13.0. These are version specifiers that indicate the acceptable updates for a package dependency.

Here are some commonly used version specifiers:

  • ~: Matches patch releases only (~0.13.0 accepts 0.13.1 but not 0.14.0).
  • ^: Matches patch and minor releases (^0.13.0 accepts 0.13.1 and 0.14.0).
  • *: Matches any version, including major version upgrades.
  • >: Matches versions higher than the specified version.
  • >=: Matches versions equal to or higher than the specified version.
  • <=: Matches versions equal to or lower than the specified version.
  • <: Matches versions lower than the specified version.
  • No symbol: Matches the exact specified version.
  • latest: Matches the latest version available.

These version specifiers can be combined within ranges to define specific version requirements.

By understanding the structure and properties of package.json, you can effectively manage your Node.js projects and their dependencies.