In this tutorial, we'll explore
package.json files, Node.js configuration files that contain essential metadata for projects and dependencies. We'll break down each configuration key available and how to utilize them with your projects.
The package.json file
When you create and initialize a Node.js project, a
package.json file is automatically created with default settings for your project in JSON format. Here is an example:
"description": "A test project",
"precompress": "[executed before the compress script]",
"compress": "[compresses files]",
"postcompress": "[executes after the compress script]"
The Configuration Keys
Let's go over each of the configuration keys:
namestring - The name of your Node.js project, in all lowercase and URL-friendly format. The name is required for public projects and must be unique to the npm repository.
versionstring - A version number in x.x.x format, or one understandable by node-semver. The version is required for public projects and optional for private projects.
descriptionstring - A brief description for the project. This is optional but recommended so your project can be easily found in the npm repository.
mainstring - The entry file for your project. By default, this is index.js, but can be a different filename or include a directory if the entry point is in a different location than the root. Another example could be lib/index.js.
scriptsobject - An object with script names as keys and commands as values. These are typically used to run custom commands and automate repetitive tasks to help save time and reduce errors.
keywordsarray - An array of keywords to help people find the project in the npm repository.
authorobject - An object containing the details about the author of the project, typically containing keys and values for name, email, and url.
licensestring - The license name using the SPDX Identifier. Possible values are ISC or MIT license choices. You can also specify UNLICENSED for private projects.
browserstring - This value replaces the
mainkey/value pair in cases where the project should be launched in a browser instead of on a server.
filesarray - An array of file names and locations included when the project is added as a dependency for another project.
privateboolean - Set this value to true in cases where your project is not meant to be published in the npm repository. Settings this value prevents accidental publishing when the project is meant to remain private and isn't required, but is good practice.
enginesobject - Used to specify versions of Node.js or npm that the project is designated for. Here, you could specify an object key for node and/or npm with a version range.
homepagestring - The URL of the homepage for the project.
bugsstring - The URL given for users to report bugs, typically a GitHub Issues URL.
You can also manage a project's dependencies within the configuration file. Here is a list of the dependencies available:
dependenciesarray - Normal project dependencies. You can also add these dependencies to your project using the command line:
npm install [dependency-name].
devDependenciesarray - Used only during the development phase of a project. You can also add a development dependency with the
--save-devflag while installing it.
optionalDependenciesarray - Allow npm to proceed if one fails to install. You can also add an optional dependency with the
--save-optionalflag while installing it.
bundledDependenciesarray - Come bundled together as a group of modules in a single file. You can also add a bundled dependency with the
--save-bundleflag while installing it.
peerDependenciesarray - Important when you're creating packages or plugins that will be used by other developers. There is no command line flag for this option.
When adding version numbers to your dependencies, make sure to adhere to the following formats:
1.2.3- Version 1.2.3
^1.2.3- The latest version compatible with version 1.2.3
~1.2.3- Works for patch versions equal to or greater than version 1.2.3, example: 1.2.3, 1.2.4, 1.2.5, etc.
1.x- Works for any minor version within the package 1
1.2.x- Works with any patch version within the package version of 1.2
>=1.2- A version greater than or equal to version 1.2
<=1.2- A version less than or equal to version 1.2
1.2.3 2.1.4- A version including or between versions 1.2.3 and 2.1.4
1.2.3 2.1.4 || 2.2.4 2.3.1.- Multiple version ranges between 1.2.3 and 2.1.4 or 2.2.4 and 2.3.1
With this tutorial, you should have a good understanding of the inner workings of
package.json files and how to use them for your Node.js projects.