The Basics of Package.json
The Basics of Package.json
In this chapter, we'll give you a kickstart introduction to effectively using package.json
with Node.js
and npm
.
The package.json
file is core to the Node.js ecosystem and is a fundamental part of understanding and working with Node.js
, npm
, and even modern JavaScript
. This file is used as a manifest, storing information about applications, modules, packages, and more.
Because understanding it is essential to working with Node.js
, it's a good idea to grasp the commonly found and most crucial properties of a package.json
file to use it effectively.
This is a series, based on one of the most featured whitepapers we have done by developers in the Node.js ecosystem. If you are interested in the complete guide, you can get it through this link.
The 2022 guide will include this, which we will be releasing by units of knowledge every Thursday in the following weeks. Today you are in part 1 of the guide:
The Essential npm Commands
- Using
npm init
to initialize a project - Using
npm init --yes
to instantly initialize a project - Install modules with
npm install
- Install modules and save them to your
package.json
as a dependency - Install modules and save them to your
package.json
as a developer dependency - Install modules globally on your system
- Using
The Basics of package.json
2.1. Identifying Metadata Inside package.json
- The
name
property - The
version
property - The
license
property - The
property
description - The
keywords
property
2.2. functional metadata inside package.json
- The
main
property - The
repository
property - The
script
property - The
dependencies
property - The
devdependencies
property
- The
Understanding the different types of dependencies and other host Specs inside package.json
- PeerDependencies
- PeerDependenciesMeta
- OptionalDependencies
- BundledDependencies
- engines
- os
- cpu
Identifying Metadata Inside package.json
The name
property
The name
property in a package.json
file is one of the fundamental components of the package.json
structure. At its core, the name is a string that is exactly what you would expect: the name of the module that the package.json
is describing.
Inside your package.json
, the name
property as a string would look something like this:
"name": "metaverse"
There are only a few material restrictions on the name
property:
• Maximum length of 214 URL-friendly characters
• No uppercase letters
• No leading periods (.) or underscores (_) (Except for scoped packages)
However, some software ecosystems have developed standard naming conventions that enable discoverability. A few examples of this namespacing are the babel plugin- for Babel and the webpack-loader tooling.
The version
property
The version
property is a crucial part of a package.json
, as it denotes the current version of the module that the package.json
file is describing.
While the version
property isn't required to follow semver (semantic versioning) standards, which is the model used by the vast majority of modules and projects in the Node.js ecosystem, it's what you'll typically find in the version
property of a package.json
file.
Inside your package.json
, the version
property as a string using semver could look like this:
"version": "5.12.4"
The license
property
The license
property of a package.json
file is used to note the module that the package.json
file describes. While there are some complex ways to use the licensed property of a package.json
file (to do things like dual-licensing or defining your own license), the most typical usage is to use an SPDX License identifier. Some examples that you may recognize are MIT, ISC, and GPL-3.0.
Inside your package.json
, the license
property with an MIT license looks like this:
"license": "MIT"
The description
property
The description
property of a package.json
file is a string that contains a human-readable description of the module. It's the module developer's chance to let users know what precisely a module does quickly. Search tools frequently index the description
property like npm search and the npm CLI search tool to help find relevant packages based on a search query.
Inside your package.json
, the description
property would look like this:
"description": "The Metaverse virtual reality. The final outcome of all virtual worlds, augmented reality, and the Internet."
The keywords
property
The keywords
property inside a package.json
file is, as you may have guessed, a collection of keywords that describe a module. Keywords can help identify a package, related modules and software, and concepts.
The keywords
property is always an array, with one or more strings as the array's values; each one of these strings will, in turn, be one of the project's keywords.
Inside your package.json
, the keywords array would look something like this:
"keywords": [
"metaverse",
"virtual reality",
"augmented reality",
"snow crash"
]
Functional Metadata Inside package.json
The main
property
The main
property of a package.json
is a direction to the entry point to the module that the package.json
is describing. In a Node.js application, when the module is called via a require
statement, the module's exports from the file named in the main property will be returned to the Node.js application.
Inside your package.json
, the main
property, with an entry point of app.js, would look like this:
"main": "app.js"
The repository
property
The repository
property of a package.json
is an array that defines where the source code for the module lives. Typically, this would be a public GitHub repo for open source projects, with the repository array noting that the type of version control is git and the URL of the repo itself. One thing to note about this is that it's not just a URL where the repo can be accessed from, but the full URL the version control can be accessed from.
Inside your package.json, the repository property would look like this:
"repository": {
"type": "git",
"url": "https://github.com/bnb/metaverse.git"
}
The scripts
property
The scripts
property of a package.json
file is simple conceptually but complex functionally, to the point that it's used as a build tool by many.
At its simplest, the scripts
property contains a set of entries; the key for each entry is a script name, and the corresponding value is a user-defined command to be executed. Scripts are frequently used to test, build, and streamline the needed commands to work with a module.
Inside your package.json
, the scripts
property with a build command to execute tsc (presumably to transpile your application using TypeScript) and a test command using Standard would look like this:
"scripts": {
"build": "tsc",
"test": "standard"
}
To run scripts in the scripts
property of a package.json
, you'll need to use the default npm run
command. So, to run the above example's build, you'd need to run this:
Usage:
$ npm run build
That said, to run the test suite, you'd need to execute this:
Usage:
$ npm test
Notice that npm
does not require the run keyword as part of the given script command for some tasks like the test, start, and stop by default.
The dependencies
property
The dependencies
property of a module's package.json
is defined by the other modules that this module uses. Each entry in the dependencies
property includes the name and version of other packages required to run this package.
Note: You'll frequently find carets (^) and tildes (~) included with package versions. These are the notations for version range — taking a deep dive into these is outside the scope of this guide, but you can learn more in our primer on semver. In addition, you may specify URLs or local paths in place of a version range.
Inside your package.json
, the dependencies
property of your module may look something like this:
"dependencies": {
"async": "^0.2.10",
"npm2es": "~0.4.2",
"optimist": "~0.6.0",
"request": "~2.30.0",
"skateboard": "^1.5.1",
"split": "^0.3.0",
"weld": "^0.2.2"
},
The devDependencies
property
The devDependencies
property of package.json
is almost identical to the dependencies
property in terms of structure. The main difference: while the dependencies
property is used to define the dependencies that a module needs to run in production, devDependencies
property is commonly used to define the dependencies the module needs to run in development.
Inside your package.json
, the devDependencies
property would look something like this:
"devDependencies": {
"escape-html": "^1.0.3",
"lucene-query-parser": "^1.0.1"
},
Remember that you can now monitor your applications and take your Node.js journey to a professional level with N|Solid.
To get the best out of Node.js and low-cost observability, start a free trial of N|Solid.
If you have any questions, please feel free to contact us at info@nodesource.com or through this form.
And if you want to find out about our latest content and product releases, these are the channels to keep up to date with NodeSource: