The Basics of Package.json – NodeSource

In this chapter, we’ll give you an initial introduction to using

package.json effectively with Node.js and npm.

The package.json file is central 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 understand the most common and crucial properties of a package.json file in order to use it effectively.

This is a series, based on one of the most prominent whitepapers we have made 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 publishing by units of knowledge every Thursday of the coming weeks. Today you are in part 1 of the guide:

The essential commands of npm 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 in your package.json as a dependency Install modules

    • and save them in your package.json as a developer dependency Install modules
    • globally on your system
    • The basics of

    • package.json
  1. 2.1. Identifying metadata within package.json The name property The version property The license property The

      description of

    • the
    • property The

    • keyword
    • property

    2.2. Functional metadata

    inside package.json The main property The repository property The script property The dependencies property

    The devdependencies

    • property
    • Description of the different types of dependencies and other hosts Specifications inside package.json PeerDependencies PeerDependenciesMeta OptionalDependencies

    • BundledDependencies
    • engines
    • of the

    • CPU
    • operating system

    Identifying metadata within

package.json The name property

The name property

of a package.json file is one of the fundamental components of the package.json

structure. In essence, the name is a string that is exactly what you would expect: the name of the module that package.json describes.

Within your package.json, the name property as a string would look like this

: “name”: “metaverse”

There are only a few material restrictions on the name property: • Maximum length of 214 URL-supported characters • No uppercase letters • No leading periods (.) or underscores (_) (Except for scoped packages) However

, some software ecosystems have developed standard naming conventions that allow discoverability. Some examples of this namespace are the babel plugin for Babel and the webpack-loader tools.


version property The version property is a crucial part of a package.json file

because it indicates the current version of the module that the package.json file describes.

While the version property is not 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, This is what you will typically find in the Version property of a package.json file.

Inside your package.json, the version property

as a string using semver might look like this

: “version”: “5.12.4” The license property

The license property

of a package.json file

is used to annotate the module that describes the package.json file. While there are some complex ways to use the licensed property of a package.json file (to do things like dual licenses or define your own license), the most typical use is to use an SPDX license identifier. Some examples you may recognize are MIT, ISC, and GPL-3.0.

Within its 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 readable description of the module. It is the module developer’s opportunity to let users know what exactly a module does quickly. Search tools typically index the description property as npm search and the npm CLI search tool to help find relevant packages based on a search query.

Inside its package.json, the description property would look like this

: “description”: “The virtual reality of the Metaverse. The end result of all virtual worlds, augmented reality and the Internet.” The

keywords property within a package.json file is, as you might 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 array values; each of these strings will be, in turn, one of the project’s keywords

. Within your package.json

, the keyword array would look like this

: “keywords”: [ “metaverse”, “virtual reality”, “augmented reality”, “snow shock” ] Functional metadata inside package.json The

main property The

main property of package.json is an address to the entry point to the module that


describes. In a Node.js application, when the module is called through a require statement, exports of the module from the file named in the main property will be returned to the Node.js application.

Within your package.json, the main property, with an app.js entry point

, would look like this: “main”: “app.js ”

The repository property

The repository property

of a package.json file is an array that defines where the module’s source code resides. Typically, this would be a public GitHub repository for open source projects, with the repository array noting that the version control type is git and the URL of the repository itself. One thing to note about this is that it’s not just a URL from where the repository can be accessed, but the full URL from which version control can be accessed.

Inside your package.json, the repository property

would look like this

: “repository”: { “type”: “git”, “url”: “” } The scripts


The scripts property of a package.json file is conceptually simple but functionally complex, to the point that many use it as a build tool.

In its simplest form, 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, compile, and optimize the commands required to work with a module. Within 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 build from the example above, you would need to run this: Usage: $ npm run build That said, to run the test

suite, you would need

to run this:


$ npm test

Note that npm does not require the run keyword as part of the given script command for some tasks like test

, start, and stop by default.

The property

dependencies The dependencies property of a module’s package.json file is defined by the other modules that this module uses. Each dependencies property entry includes the name and version of other packages required to run this package.

Note: You will often find collations (^) and tildes (~) included with package versions. Here are the notations for the range of versions: Digging deeper into them is beyond the scope of this guide, but you can learn more in our manual on SEMver. In addition, you can specify URLs or local paths instead of a range of versions.

Within your package.json, your module’s dependencies property may look similar to the following:

“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, the devDependencies property is commonly used to define the dependencies that the module needs to execute in development.

Within your package.json, the devDependencies property would look 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 journey .js node to a professional level with N| Solid.

  • To get the best 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 or through this form.

  • And if you want to know our latest content and product launches, these are the channels to keep up with NodeSource:

      • Nodesource Twitter Nodesource LinkedIn

Contact US