`package.json`

Every Node project has a package.json. It declares dependencies, scripts, the module type, and metadata.

4 min read Level 1/5 #nodejs#package-json#npm

What you'll learn

Initialize a package.json
Read the common fields
Define npm scripts

package.json is the manifest of a Node project — its name, version, dependencies, scripts, and configuration. It sits at the project root.

Creating One

npm init -y     # accepts defaults, no prompts

A Realistic Example

{
  "name": "my-api",
  "version": "1.0.0",
  "type": "module",
  "main": "src/index.js",
  "engines": {
    "node": ">=22.0.0"
  },
  "scripts": {
    "dev": "node --watch src/index.js",
    "start": "node src/index.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^4.21.0",
    "zod": "^3.23.0"
  },
  "devDependencies": {
    "vitest": "^1.6.0"
  }
}

The Fields That Matter

Field	Purpose
`name`	Package name (must be unique on npm to publish)
`version`	Semver — `MAJOR.MINOR.PATCH`
`type`	`"module"` for ESM, `"commonjs"` otherwise
`main`	Entry point when imported
`scripts`	Command shortcuts run via `npm run`
`dependencies`	Runtime deps shipped to production
`devDependencies`	Dev-only deps (tests, bundlers)
`engines.node`	Minimum Node version

Scripts

The most-used part of package.json:

{
  "scripts": {
    "dev":       "node --watch src/index.js",
    "build":     "tsc",
    "test":      "vitest",
    "lint":      "eslint src",
    "typecheck": "tsc --noEmit"
  }
}

Run with npm run dev. (start and test can drop the run.)

Semver in Dependencies

Range	Means
`"4.21.0"`	exact
`"^4.21.0"`	`4.x.x`, where x ≥ 21 (most common)
`"~4.21.0"`	`4.21.x` (patches only)
`">=4.21.0"`	any version 4.21.0 and up
`"*"`	anything — avoid

`package-lock.json`

Auto-generated. Records the exact versions installed of every dep and sub-dep. Commit it. It’s how teammates and CI get the same build.

Up Next

npm itself — installing, running, and publishing packages.

npm →