Create a package.json File

Part of learning Node.js is creating a package.json file using npm init, but you can also create one automatically. Creating a package.json file is typically the first step in a Node project, and you need one to install dependencies in npm. If you're starting a project from scratch, you create a package.json file to hold important metadata about your project and record your dependencies. When you run npm init to generate a package.json, you can accept the suggested defaults, or fill out your own information.

In this tutorial, we'll:

  • Create a package.json file using npm init
  • Inspect the generated file and explore the defaults
  • Learn how to generate a package.json automatically

Goal

Generate a package.json file, understand the contents, and learn how to create one automatically.

Prerequisites

Create package.json

At a high level, to create a package.json file you'll need to do the following:

  • Enter the root folder of your project
  • Run npm init
  • Fill out the prompts to create your package.json

The easiest way to create a package.json file is to run npm init to generate one for you. It will ask you to fill out some fields, and then create a package.json file in the current directory.

If you haven’t already, create a folder for your project to live in.

In your terminal, enter the folder you just created and run npm init.

You should see help text like the following:

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (my-project)

Fill out the prompts for fields in your package.json. Either accept the defaults suggested by npm, or type a new value and hit enter.

The package.json fields you'll be prompted for are name, version, description, main, test command, git repository, keywords, author, and license. It's okay to accept the defaults if you don't know what to put for a field. The important part is generating a package.json so you can begin to install dependencies.

With one important exception, all fields in a package.json are optional. You're not required to use any of them, and the only true requirement is that the file is valid JSON. There are more requirements if you intend to publish the package to the NPM registry to distribute to others.

NPM requires a unique name field and a version number before publishing. If you are going to be publishing your package for others to use, you should make sure you fill out all the fields that npm init prompts you for, because they help others find your project on npmjs.com and point people to where they can go to find help.

Even though most package.json fields are optional, they can be very useful to other tools that interact with your project and rely on information in the file. It is best practice to at least provide the information npm init asks for, but the decision is up to you.

You can learn more about the different fields and how they are used in our What Is package.json tutorial.

Review the package.json preview shown after answering the prompts, and either accept it by hitting enter, or type "no" to abort.

Accepting will save the package.json file to the directory you are currently in.

The generated file might look like the following:

{
  "name": "my-server",
  "version": "1.0.0",
  "description": "An express application",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Jon Church",
  "license": "ISC",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/osiolabs/heynode.git"
  },
  "bugs": {
    "url": "https://github.com/osiolabs/heynode/issues"
  },
  "homepage": "https://github.com/osiolabs/heynode#readme",
  "keywords": [
    "express",
    "server"
  ]
}

After you've created a package.json, you are free to install dependencies for your project using npm install <package>. Learn more about installing packages with npm.

Accepting the defaults

The npm CLI will try to infer defaults from the folder you ran npm init from. For example, inferring the name of the folder to suggest as the package name. Or, if you have already set up a remote git origin before running npm init, the repository field will be suggested for you.

Instead of running npm init and then repeatedly hitting the enter key to accept defaults, you can also generate a package.json without being asked for input. Run npm init -y to generate a package and automatically and accept all the defaults. The package.json created will be shown on the command line, and saved to the current directory.

Updating package.json

You can always manually edit your package.json file in your text editor once it is created. Just make sure you don't introduce any JSON formatting errors, as the file must be valid JSON to work properly. If your package.json is invalid, you'll get an error when using npm commands to interact with your project.

If you just want to update fields which are included when running npm init, you can run the command again after you've already created your package.json.

Running npm init you already have a package.json will attempt to update the existing file, instead of creating a new one. For example, if you didn't add a git origin until after you created your package.json, you can re-run npm init -y and the repository field will be added automatically to your package.json. Re-running npm init is additive. It won't overwrite values you have already entered, but will update any previously blank fields it can.

Recap

The first step in creating a Node.js application is generating a package.json for your project. Using npm init, you can easily generate a package.json, with either the help of the setup prompts, or by accepting the suggested defaults. For private projects, which won't get published to NPM, there are no strictly required fields, but it is still best practice to fill out as many of the package.json fields as you can. Once you have generated a package.json, you are ready to begin installing dependencies into your application.

Further your understanding

Additional resources

Sign in with your Osio Labs account
to gain instant access to our entire library.