Skip to main content

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"
}

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() 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.

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.

author

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

Here's an example:

{
"author": "Oluwatobi Sofela <oluwatobiss@codesweetly.com> (https://www.codesweetly.com)"
}

You can also write the snippet above as:

{
"author": {
"name": "Oluwatobi Sofela",
"email": "oluwatobiss@codesweetly.com",
"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.

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.

Note that 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"
}
}

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

Suppose a user installs the project through the npm install (or yarn add) command. In such a case, the package manager will find and download all the listed devDependencies to the project's node_modules directory.

Keep in mind that 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.

homepage

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

Here's an example:

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

Overview

This article discussed what a package.json file is. We also looked at the commonly used fields in a package.json file.