package.json File – Explained with Examples

A package.json file is a JSON document that package managers—like NPM and Yarn—use to store information about a specific project.

In other words, a package.json file is a project’s metadata file.

Advantages of a package.json File

A package.json file:

• makes it possible to publish your project to the NPM registry
• makes it easy for others to manage and install your package
• helps NPM to manage a module’s dependencies easily
• makes your package reproducible and shareable with other developers

How to Create a package.json File

Go to your project’s root directory and initialize the creation of a package.json file by running:

npm init

Or, if your package manager is Yarn, run:

yarn init

Once you’ve executed the initialization command above, your package manager will walk you through creating the package.json file by asking a few questions about your project.

Note

You must have Node and NPM installed on your system for the NPM (and Yarn) initialization command to work. You can get both by installing the latest LTS or the current version from the Node.js website.

If you wish to skip the questionnaire, you can create a default package.json file. Let’s see how.

How to Create a Default package.json File

Suppose you prefer to skip the questionnaire prompted by the npm init (or yarn init) command. In such a case, go to your project’s root directory and run:

npm init -y

Or, if your package manager is Yarn, run:

yarn init -y

The command above will use default values extracted from the current directory to create your project’s package.json file.

Note

The -y flag is a shorthand for --yes.

Once your package manager finishes its initialization process, your project’s package.json file will contain an object with a set of properties.

Here’s an example:

{
  "name": "codesweetly-project",
  "version": "1.0.0",
  "main": "index.js"
}

You can see that the package.json file above contains the name, version, and main fields. Let’s learn more about these properties below.

The package.json’s Fields

The package.json’s properties make your project usable to package managers and end-users.

Suppose you wish to publish your package to the NPM registry. In that case, your package.json file must have the "name" and "version" fields.

However, if you do not intend to publish your package, in that case, all fields—including the "name" and "version" properties—are optional.

Let’s learn more about the commonly used fields in a package.json file.

name

The "name" field is a property used to record a project’s name.

The "name" property’s value must be:

• a single word
• lowercase lettering
• and less than or equal to 214 characters

Note that you can join words together with hyphens and underscores.

Here’s an example:

{
  "name": "code_sweetly-project"
}

CodeSweetly ads

Learn Flexbox with Images

Use beautiful images to learn CSS Flexbox.

Find out more

version

The "version" field indicates a project’s current version number.

The "version" property must be in the form of a major.minor.patch format. It must also follow the semantic versioning guidelines.

Here’s an example:

{
  "version": "1.0.0"
}

description

The "description" field is a property containing a brief description of a project’s purpose.

NPM recommends having a "description" property to make your package easier to find on the NPM website.

Your description will be one of the information shown when people run the npm search command.

Here’s an example:

{
  "description": "A brief description about this package (project)"
}

main

The "main" field indicates a project’s entry point.

In other words, when someone runs the require(<package-name>) function, Node will resolve the invocation to require(<package.json:main>).

Here’s an example:

{
  "main": "./src/index.js"
}

What is an entry point?

An entry point is a file that a bundler, like webpack, uses to start building a dependency graph of all the project’s modules needed to bundle up into a single browser-compatible module.

An entry point is the most critical file of a build step that links (directly or indirectly) to every other module in a project.

Note

Suppose your package.json file does not have a main field. In that case, Node.js defaults to your root folder’s index.js file.

private

The "private" field lets package managers know whether they should publish your project to the NPM registry.

Here’s an example:

{
  "private": true
}

If you set your package.json’s "private" property to true, package managers will not publish your project.

Therefore, setting the property is an excellent way to prevent accidental publication of your package.

scripts

The "scripts" field defines the script commands you want to run at various times in your project’s lifecycle.

Here’s an example:

{
  "scripts": {
    "test": "jest",
    "dev": "webpack --mode development",
    "build": "webpack --mode production",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

The "scripts" field above contains five properties whose values are the commands we want our package manager to run whenever we invoke the property’s key.

So, for instance, running npm run dev will execute the "webpack --mode development" command.

keywords

The "keywords" field specifies an array of keywords that can help people discover your package.

Here’s an example:

{
  "keywords": ["drag", "drop", "drag and drop", "dragndrop", "draggable"]
}

The "keywords" property is part of the information shown when people run the npm search command.

CodeSweetly ads

Create NPM Package like a pro

Learn the fundamentals of building and managing NPM packages from scratch.

Find out more

author

The "author" field lists a project’s author’s details.

Here’s an example:

{
  "author": "Oluwatobi Sofela <[email protected]> (https://www.codesweetly.com)"
}

You can also write the snippet above as:

{
  "author": {
    "name": "Oluwatobi Sofela",
    "email": "[email protected]",
    "url": "https://www.codesweetly.com"
  }
}

Note that the "email" and "url" properties are optional.

dependencies

The "dependencies" field lists all the packages a project depends on in production (when your app is running on a live server).

Here’s an example:

{
  "dependencies": {
    "first-package": "^1.0.4",
    "second-package": "~2.1.3"
  }
}

So, whenever a user installs your project from the NPM registry, the dependencies property ensures package managers can automatically find and install the packages listed.

You can add a package to the "dependencies" field through either of the following ways:

• Manually add the name and the semantic version of each package your project depends on in production.
• Run the npm install package-name --save-prod command on your terminal. Or yarn add package-name if Yarn is your package manager.

devDependencies

The "devDependencies" field lists all the packages a project does not need in production—but requires for its local development and testing purposes.

Here’s an example:

{
  "devDependencies": {
    "first-dev-package": "^5.8.1",
    "second-dev-package": "3.2.2—4.0.0"
  }
}

The packages listed in the "devDependencies" field will be available in the project’s development environment but not on its production server.

dependencies vs. devDependencies

Suppose you install a project in the development environment. In such a case, your package manager will find and download all the listed dependencies and devDependencies to the project’s node_modules directory.

But suppose a server installs the project in the production environment. In that case, the package manager will find and download only the dependencies to the project’s node_modules directory.

In other words, package managers will always install dependencies regardless of the environment. But they will install devDependencies only in development.

You can add a package to the "devDependencies" field through either of the following ways:

• Manually add the name and the semantic version of each package on which your project depends for its development and testing purposes.
• Run the npm install package-name --save-dev command on your terminal. Or yarn add package-name --dev if Yarn is your package manager.

peerDependencies

The "peerDependencies" field lists all the packages a project expects its host application to have in its node_modules directory.

Advantage of peer dependencies

Peer dependencies prevent having more than one copy of a package in the same app.

Here’s an example:

{
  "peerDependencies": {
    "first-peer-package": "^6.3.1",
    "second-peer-package": ">= 7.5.2 < 8"
  }
}

Suppose you install a project containing a peerDependencies field from the NPM registry to your application (the host app). In that case, your package manager will check whether your app contains the packages listed in the peerDependencies.

If so, it means your application (the host app) has the dependencies the installed package needs to work.

But suppose the package manager could not find the installed project’s peerDependencies in your app. In that case, some NPM versions (like versions 7 and 8) will install them automatically. But other versions (like versions 3 to 6) will display a warning saying that the package you are installing requires some peer dependencies, which you must install yourself.

Note the following:

• Not all developers need to specify peer dependencies. Consider listing peerDependencies only if you are publishing your own NPM package.
• You need to list peer dependencies manually in your package.json’s "peerDependencies" field. Do so by specifying the name and the semantic version of each package your project expects its host application to have in its node_modules directory.
• It is best to make your peer dependencies lenient to diverse minor and patch versions. So, suppose the package you wish to publish depends on a React version 17.3.1. In that case, specify "react": "^17.3.1" (or "react": ">= 17.3.1 < 18") in your peerDependencies’ field. Doing so will make your package broadly compatible with host applications having other React versions that may be greater or equal to v17.3.1 but less than v18.

homepage

The "homepage" field specifies the URL to your project’s homepage.

Here’s an example:

{
  "homepage": "https://codesweetly.com/package-json-file-explained"
}