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 thepackage.jsonfile and its various properties in this guide.
What is package.json?
Every npm package and Node.js project has apackage.jsonfile 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": "[email protected]"}],"main": "app.js","repository": {"type": "git","url": "https://github.com/phoenixnap-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 apackage.jsonfile.
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 usingspaces 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.
Note: The name does not have to be unique for local unpublished projects.
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": "[email protected]","url": "http://my-website.com/about-me"}Alternatively, shorten the syntax to a single line:
"author": "First Middle Last <[email protected]> (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 thesource 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 semverImport 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"}UsedevDependenciesto 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 theoptionalDependenciesproperty 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.
Note: Need to install Node.js with npm? Use one of our OS-specific installation guides:
- Node.js and npm for CentOS
- Node.js and npm for Debian
- Node.js and npm for Ubuntu
- Node.js and npm for macOS
- Node.js and npm for Windows
The table below briefly describes common npm commands for managing apackage.jsonfile.
| Command | Description |
|---|---|
npm init | Creates a new package.json file with elementary properties. Contains prompts about the project , such as the name, version, etc. |
npm install | Installs dependencies listed in the package.json file. Reads from dependencies and devDependencies properties. |
npm update | Checks for newer versions and updates dependencies provided in the package.json file. |
npm run <script name> | Runs scripts provided in the scripts property. |
npm uninstall <package> | Removes a package from the dependencies or devDependencies property. |
To create and update thepackage.jsonfile, 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.
