Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Your First package.json

Create your first package.json with npm init, yarn init or pnpm init, learn what each generated field means, and read and validate the file with plain Node.js code.

Every Node.js project starts with a file called package.json. It is the project's identity card and shopping list: the name, the version, the scripts you can run and the packages you depend on. All three package managers can create it for you. This lesson creates one, explains each line and shows how to read it from code.

Creating the file

In an empty folder, run one of these on your computer (read-only here):

Terminal
npm init          # asks questions, one at a time
npm init -y       # accepts every default (-y means "yes")
yarn init -y
pnpm init

npm init -y produces a file like this (the exact fields vary a little between versions):

JSON
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

The name defaults to the folder name. You can edit the file by hand at any time: it is ordinary JSON.

JSON rules that trip people up

package.json must be strict JSON, not JavaScript. That means double quotes around every key and string, no trailing commas and no comments. A single stray comma makes every npm command fail with a parse error.

Node.js Strict JSON: what breaks a package.json

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Editors such as VS Code underline JSON mistakes as you type. If you need comments, use a separate README or a tool-specific config file; package.json itself cannot hold them.

The fields you must know first

  • name: lowercase, no spaces, up to 214 characters; it is how others install you if you publish. For private apps it still identifies the project.
  • version: three numbers, like 1.0.0 (see Semantic Versioning).
  • description and keywords: shown in registry search.
  • main: the file loaded when someone imports your package.
  • scripts: named commands you run with npm run <name> (npm Scripts).
  • license: the SPDX identifier such as MIT or ISC.
  • private: set it to true for apps you never intend to publish; the registry will then refuse accidental publishes.

Dependencies and the many other fields are covered in the next chapter, starting with package.json Fields.

Reading package.json from Node

Because it is JSON, any program can read it. Here a program writes a manifest into a temporary folder and then reads it back, the way many tools do:

Node.js Write and read a manifest

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The two-space indentation and trailing newline are what npm itself writes, so your diffs stay small when tools rewrite the file.

A tiny validator

Before publishing, tools check that the name and version are legal. This stand-in applies the main rules:

Node.js Validate name and version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The real rule set also covers scopes such as @acme/tools, covered in The npm Registry and Package Names.

What happens next

Once the file exists, npm install some-package adds a dependencies section and creates node_modules plus a lockfile. You never need to create node_modules or the lockfile by hand, and you should not edit them. Commit package.json and the lockfile to git; add node_modules to .gitignore, because it can always be rebuilt.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does npm init -y do?

    -y accepts the defaults for every question.
  2. 2. Which is valid in package.json?

    package.json is strict JSON: double quotes, no trailing commas, no comments.
  3. 3. What does "private": true prevent?

    The registry client refuses to publish a private package.
  4. 4. Which should be committed to git?

    node_modules can be rebuilt from the manifest and lockfile.

Summary

  • npm init, yarn init and pnpm init create package.json; -y accepts defaults.
  • The file is strict JSON: double quotes, no trailing commas, no comments.
  • Key fields: name, version, description, main, scripts, license, private.
  • Any program can read it with JSON.parse.
  • Commit the manifest and lockfile, never node_modules.

Next: package.json Fields