Essential package.json Fields

Beyond the basics, package.json supports many fields that help configure your project. Let's explore the most useful ones.

Project Information Fields

homepage

Link to your project's homepage:

{
  "homepage": "https://my-project.com"
}

repository

Where your code lives:

{
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-project.git"
  }
}

Shorthand for GitHub:

{
  "repository": "github:username/my-project"
}

bugs

Where to report issues:

{
  "bugs": {
    "url": "https://github.com/username/my-project/issues",
    "email": "bugs@my-project.com"
  }
}

funding

How to support the project:

{
  "funding": {
    "type": "patreon",
    "url": "https://www.patreon.com/username"
  }
}

Configuration Fields

type

Specify module system:

{
  "type": "module"
}

Value	Import Style
"commonjs" (default)	require()
"module"	import/export

engines

Specify required Node.js version:

{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

This helps prevent compatibility issues.

private

Prevent accidental publishing:

{
  "private": true
}

Essential for apps, internal tools, and monorepos.

workspaces

For monorepo projects:

{
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

Entry Point Fields

main

The primary entry point (CommonJS):

{
  "main": "dist/index.js"
}

module

Entry point for ES modules (used by bundlers):

{
  "module": "dist/index.mjs"
}

exports

Modern, flexible exports (Node.js 12+):

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}

bin

For CLI tools:

{
  "bin": {
    "my-cli": "./bin/cli.js"
  }
}

Or for a single command:

{
  "bin": "./bin/cli.js"
}

File Control Fields

files

Which files to include when publishing:

{
  "files": [
    "dist",
    "src",
    "README.md"
  ]
}

By default, npm includes most files. Use .npmignore to exclude files.

directories

Describe your project structure:

{
  "directories": {
    "lib": "src",
    "test": "tests",
    "doc": "docs"
  }
}

Dependency Fields

peerDependencies

Packages that must be installed by the user:

{
  "peerDependencies": {
    "react": ">=17.0.0"
  }
}

Common for plugins and libraries.

peerDependenciesMeta

Make peer dependencies optional:

{
  "peerDependencies": {
    "react": ">=17.0.0",
    "vue": ">=3.0.0"
  },
  "peerDependenciesMeta": {
    "vue": {
      "optional": true
    }
  }
}

optionalDependencies

Dependencies that aren't required:

{
  "optionalDependencies": {
    "fsevents": "^2.3.2"
  }
}

Your app should handle these being missing.

bundleDependencies

Dependencies to bundle when publishing:

{
  "bundleDependencies": [
    "my-private-package"
  ]
}

overrides

Override nested dependency versions:

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

Practice: Complete package.json

Here's a more complete package.json. Study the fields and try modifying them:

Field Categories Summary

Category	Fields
Identity	name, version, description
People	author, contributors
Links	homepage, repository, bugs
Entry Points	main, module, exports, bin
Files	files, directories
Dependencies	dependencies, devDependencies, peerDependencies
Config	type, engines, private, workspaces

Key Takeaways

1. type: "module" enables ES modules
2. engines specifies Node.js version requirements
3. private: true prevents accidental publishing
4. exports provides modern, flexible entry points
5. peerDependencies for libraries that need host packages

What's Next?

Now that you understand package.json, let's learn how to install and manage packages.