package.json Quick Start Guide

Introduction

Manual project dependency management is a weary task. For Node.js projects, the package.json file provides a simplified way to manage a project’s metadata and dependencies.

The file ensures a project always has current information about the libraries and tools it needs to work correctly.

Learn all about the package.json file and its various properties in this guide.

What is package.json?

Every npm package and Node.js project has a package.json file with metadata for a project. The file resides in the root directory of every Node.js package and appears after running the npm init command.

The package.json file contains descriptive and functional metadata about a project, such as a name, version, and dependencies. The file provides the npm package manager with various information to help identify the project and handle dependencies.

package.json Example

The package.json file is fully customizable and looks different for every project. A basic package.json file looks like the following:

{
	"name": "example-name",
	"version": "1.0.0"
}

The example file contains elementary fields suitable for a personal project and the minimum required fields to publish a package.

However, published packages benefit from having a more comprehensive package.json file. For example:

{
	"name": "example-name",
	"version": "1.0.0",
	"license": "MIT",
	"description": "An example NodeJS project",
	"keywords": ["example", "learning", "kb"],
	"author": "Bob",
	"contributors": [{
		"name": "Alice",
		"email": "alice@example.com"
	}],
	"main": "app.js",
	"repository": {
		"type": "git",
		"url": "https://github.com/neveropen-KB/example.git"
	},
	"scripts": {
		"start": "node index.js",
		"dev": "nodemon"
	},
	"dependencies": {
		"express": "^4.1.4",
		"compression": "~1.3.2"
	},
	"devDependencies": {
		"nodemon": "^1.18.10"
	}
}

The file contains various metadata with package and dependency information. Whether long or short, the package.json file must be a valid JSON file to work correctly.

package.json Metadata

The package.json metadata fields help describe various properties of a Node.js project. The properties divide into two subtypes:

• Descriptive properties help identify a project and distinguish a package if published.
• Functional properties install and manage the project and its dependencies correctly.

Below is a brief overview of some commonly used properties in a package.json file.

name Property

The name property is a descriptive field that identifies a project. The combination of a project name and version forms a unique identifier for a package.

In a package.json file, the name property looks like the following:

"name": "example-name"

Several rules put limitations on the value in the name field:

• The maximum length of a name is 214 characters.
• Only lowercase letters are allowed in a name.
• Hyphens and underscores are allowed, but avoid using spaces and other characters. The name is a part of a URL, a command line argument, and a directory/folder name. Therefore, the value should respect the naming conventions of all three cases.

For published packages, the name must be unique. Check the npm registry to verify if there is a package with the same name.

version Property

The version property is a descriptive field that helps identify the package version. A published project requires having a version field in the package.json file. If working on a personal project, this property is optional.

The version property looks like this:

"version": "1.0.0"

The version number corresponds to the semantic versioning specifications in the form:

<major>.<minor>.<patch>

When releasing a new package version, increment:

• <major> when the changes are not backward compatible.
• <minor> when the update contains new functionalities which do not break older versions.
• <patch> when pushing compatible bug fixes.

The version field lets developers know what an update brings and what precautionary measures to take before updating.

For example, a major release informs developers that a package does not work with their current build and will require reworking the code that uses the package before updating.

license Property

The license is an informative field in a package.json file that lets other developers know about restrictions and permissions when using or distributing a package.

The most basic way to use the license property is to provide an SPDX license identifier. For example:

"license": "MIT"

Advanced use cases include using multiple licenses:

"license": "(MIT OR GPL-3.0)"

Alternatively, provide a custom-defined license:

"license": "See license in <file>"

If using a custom license, include the file at the top level of the package.

description Property

The description property is a custom and brief explanation of the project’s purpose and function. For example:

"description": "An example Node.js project."

Add a description to help other developers discover the package when listing through npm search.

For unpublished packages, use the description to write short documentation for the project.

keywords Property

The keywords property has a similar purpose as a description field. The npm package manager indexes the keywords array, which helps developers find packages. A list of keywords looks like the following example:

"keywords": ["example", "learning", "kb"]

The property is beneficial for published packages as it helps others discover the module. Unpublished packages do not benefit from using keywords.

author and contributors Properties

The author and contributor fields properties define the creators and helpers of a project. The author property is a single entity, whereas the contributors property is an array (with none, one, or several entries).

The author and contributor sections have the following fields:

{
	"name": "First Middle Last",
	"email": "author@email.com",
	"url": "http://my-website.com/about-me"
}

Alternatively, shorten the syntax to a single line:

"author": "First Middle Last <author@email.com> (http://my-website.com/about-me)"

The email and URL parameters are optional for both authors and contributors.

main Property

The main property points to the project’s entry point. When a Node.js application imports the package through a require statement, the package.json file uses the exports from the file in the main property and returns it to the application.

The syntax for the main property is:

"main": "app.js"

The file path is relative to the root directory of the package. If a package.json file does not have the main property, the value defaults to index.js.

repository Property

The repository property contains information about the repository where the code resides. Use this field to point interested parties to the source code.

The repository property has the following form:

"repository": {
	"type": "git",
	"url": "<URL to git repo.git>",
	"directory": "<path to package.json>"
}

The URL is the publicly available repository. If the package.json file is not in the root directory, state the directory path in the directory field.

scripts Property

The scripts property in a package.json file contains commands that run at various times in the package lifecycle. The key-value pairs have the script name and the corresponding user-made script or command to execute.

An example scripts property looks like the following:

"scripts": {
	"start": "node index.js"
	"dev": "nodemon"
}

To run scripts defined in the scripts property, use the default npm run command:

npm run <script name>

Scripts are a simple and powerful tool for building and maintaining projects. Use the property to streamline commands for building, testing, and developing a module.

dependencies Property

The dependencies property is an essential field in a package.json file. The section maps production-level dependent packages and their versions used in the project.

An example dependencies property is:

"dependencies": "{
	"<package name>": "^4.1.4",
	"<package name>": "~1.3.2",
	"<package name>": "1.0.2",
	"<package name>": "<=1.3.2"
}

Additional characters help define advanced version ranges. The syntax for versioning comes from the node-semver package. The package is available as an npm dependency which you can install with:

npm install semver

Import the package as a module or use it as a command-line utility to double-check a version number.

devDependencies Property

The devDependencies property defines the package dependencies necessary for the development process. The development dependencies help other developers copy the build steps.

For example, if a package.json file contains a development script that uses the nodemon tool for monitoring, add the devDependencies field and provide the compatible version:

"scripts": {
	"start": "node index.js"
	"dev": "nodemon"
},
"devDependencies": {
	"nodemon": "^1.18.10"
}

Use devDependencies to list unnecessary packages for production but aid in creating a development environment that is true to the original setup.

optionalDependencies Property

The optionalDependencies property in a package.json file lists dependencies that are not essential for the package to work.

If the packages in the property are available, they are installed and provide additional functionalities. Add packages to this section in cases where:

• A package is only available on some systems.
• The specific package version is only available on some systems.
• Developers who use the package can choose not to install the packages.

Compared to other dependencies, the main difference with the optionalDependencies property is that the package works correctly without the provided dependencies.

The optionalDependencies property uses the same syntax as dependencies and devDependencies. The names of packages map to version numbers or ranges inside a list.

engines Property

The engines property in a package.json file describes the Node.js version and other runtime environments compatible with the package.

The object maps runtime environment names to version numbers or ranges. For example:

"engines": {
    "node": "~14.0.0",
    "npm": "5.0.0"
}

Defining the engines property in a package.json file lets developers and package users know the specific runtime environments where the package works correctly. Different runtime environments do not guarantee a package’s functionality and can produce behavior other than expected.

os Property

The os property lists the operating systems a package runs on. For example:

"os": ["ubuntu", "debian"]

Alternatively, use the property to block operating systems:

"os": ["!darwin", "!win23"]

If the package.json file does not have the os property, the package is compatible with every operating system.

cpu Property

The cpu property defines the CPU architecture for which the package is compiled. The property lists all compatible architectures. For example, to indicate the project is compiled for x64 and x86 architectures, write the property as:

"cpu": ["x86", "x64"]

The cpu property typically appears when publishing binary packages with compiled code to indicate specific platform compatibility.

How To Manage Your package.json

To manage your package.json file, use the npm command line interface, which comes bundled with Node.js. The npm tool comes with many commands for managing package dependencies.

The table below briefly describes common npm commands for managing a package.json file.

To create and update the package.json file, use the npm commands whenever possible. The npm tools ensure the JSON file is valid and synced with the project.

When necessary, manual management is possible through a text editor.

Conclusion

After reading this guide, you’re ready to manage Node.js package dependencies automatically using a package.json file. The file is essential to any Node.js project and contains important information about a package.