Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Packages and package.json

package.json Fields Reference

A practical tour of package.json fields beyond the basics, including engines, files, bin, repository, bugs, homepage, funding, sideEffects and packageManager, with runnable checks.

A freshly generated package.json has a handful of fields, but real projects use many more. Each field tells a tool something: npm reads some, Node reads some, bundlers and editors read others. This lesson tours the ones you will meet most, grouped by what they are for.

Identity and discovery

JSON
{
  "name": "@acme/date-tools",
  "version": "2.3.1",
  "description": "Small helpers for working with calendar dates",
  "keywords": ["date", "calendar", "utility"],
  "homepage": "https://example.com/date-tools",
  "bugs": { "url": "https://example.com/date-tools/issues" },
  "repository": { "type": "git", "url": "git+https://example.com/acme/date-tools.git" },
  "license": "MIT",
  "author": "Ada Lovelace <[email protected]>",
  "contributors": ["Grace Hopper"],
  "funding": "https://example.com/sponsor"
}

homepage, bugs and repository power the links on the registry page and the npm repo and npm bugs commands. funding is shown by npm fund. author can be a string in the form Name <email> (url) or an object.

What gets installed and how it is loaded

  • main: entry point for CommonJS consumers.
  • module and browser: hints used by bundlers (not by Node itself).
  • type: "module" makes .js files ES modules; the default ("commonjs") treats them as CommonJS.
  • exports: the modern, strict way to declare entry points (Entry Points, exports and type).
  • bin: command line programs the package installs.
  • files: which files go into the published tarball.
  • sideEffects: tells bundlers whether unused files can be dropped (tree shaking).
  • types: path to TypeScript declarations.

Requirements and constraints

  • engines: Node and npm versions the package supports, e.g. { "node": ">=20" }. npm only warns by default; set engine-strict=true in .npmrc to make it an error. pnpm and Yarn Berry enforce it more eagerly for the root project.
  • os and cpu: restrict installation to specific platforms (mostly for native modules).
  • packageManager: pins the manager for Corepack, e.g. "[email protected]".
  • private: true blocks publishing.
  • publishConfig: settings used only at publish time (registry URL, access level, tag).
Node.js Inspect a manifest by group

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 files field and .npmignore

When you publish, npm packs a tarball. By default it includes everything except node_modules, a few ignored names and whatever your .gitignore or .npmignore lists. The files allow-list is safer: only the listed paths (plus package.json, the README and the license) are included.

Node.js Which files would be published?

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.

Check your result with npm pack --dry-run, which lists the exact contents without creating a file. Publishing is covered in depth in the Publishing chapter.

Dependency fields

Five fields list dependencies: dependencies, devDependencies, peerDependencies, optionalDependencies and bundleDependencies. They have their own lesson: Dependencies, devDependencies and peerDependencies.

Config that tools read from package.json

Many tools let you configure them inside package.json instead of a separate file: for example "prettier", "eslintConfig", "browserslist" and "jest". npm also reads "config" (values exposed to scripts as npm_package_config_*) and "workspaces" (Workspaces). Unknown fields are simply ignored by npm, so tools can add their own.

npm does not run a full schema check on package.json. A typo such as "dependancies" is silently ignored, so nothing installs. If a field has no effect, double-check the spelling first.

Node.js Catch misspelled field names

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which field restricts which Node versions a package supports?

    engines declares compatible Node and npm versions.
  2. 2. What does the files field do?

    Only the listed paths, plus package.json, README and LICENSE, are packed.
  3. 3. What happens if you misspell "dependencies" as "dependancies"?

    Unknown fields are ignored; npm does not validate against a strict schema.
  4. 4. Which command shows what would be published without publishing?

    npm pack --dry-run lists the tarball contents.

Summary

  • Identity fields (name, version, repository, license) describe the package; homepage, bugs and funding power links.
  • Loading fields (main, type, exports, bin, files) control what consumers get.
  • engines, os, cpu and packageManager state requirements.
  • files is an allow-list for publishing; verify with npm pack --dry-run.
  • Unknown or misspelled fields are silently ignored.

Next: Dependencies, devDependencies and peerDependencies