package-json-validator

package.json validator

Tools to validate package.json files.

Usage

npm install package-json-validator

import { validate } from "package-json-validator";

validate(/* ... */);

For tools that run these validations, see:

• eslint-plugin-package-json: to detect all violations and keep them warned against via ESLint
• package-json-validator-cli: if you want just a one-shot tool to run in the CLI

API

validate(data, options?)

This function validates an entire package.json and returns a list of errors, if any violations are found.

Parameters

• data packageData object or a JSON-stringified version of the package data.
• options is an object with the following:

  interface Options {
  	recommendations?: boolean; // show recommendations
  	warnings?: boolean; // show warnings
  }
  

Examples

Example using an object:

import { validate } from "package-json-validator";

const packageData = {
	name: "my-package",
	version: "1.2.3",
};

validate(packageData);

Example using a string:

import { validate } from "package-json-validator";

const text = JSON.stringify({
	name: "packageJsonValidator",
	version: "0.1.0",
	private: true,
	dependencies: {
		"date-fns": "^2.29.3",
		install: "^0.13.0",
		react: "^18.2.0",
		"react-chartjs-2": "^5.0.1",
		"react-dom": "^18.2.0",
		"react-material-ui-carousel": "^3.4.2",
		"react-multi-carousel": "^2.8.2",
		"react-redux": "^8.0.5",
		"react-router-dom": "^6.4.3",
		"react-scripts": "5.0.1",
		redux: "^4.2.0",
		"styled-components": "^5.3.6",
		"web-vitals": "^2.1.4",
	},
	scripts: {
		start: "react-scripts start",
	},
	eslintConfig: {
		extends: ["react-app", "react-app/jest"],
	},
	browserslist: {
		production: [">0.2%", "not dead", "not op_mini all"],
		development: [
			"last 1 chrome version",
			"last 1 firefox version",
			"last 1 safari version",
		],
	},
});

const data = validate(text);

Output for above example:

console.log(data);
// {
//  valid: true,
//   warnings: [
//    'Missing recommended field: description',
//    'Missing recommended field: keywords',
//    'Missing recommended field: bugs',
//    'Missing recommended field: licenses',
//    'Missing recommended field: author',
//    'Missing recommended field: contributors',
//    'Missing recommended field: repository'
//  ],
//  recommendations: [
//    'Missing optional field: homepage',
//    'Missing optional field: engines'
//  ]
}

validateAuthor(value)

This function validates the value of the author property of a package.json. It takes the value, and validates it against the following criteria.

• the property is either a string or an object
• if it's an object, it should include a name field and, optionally, email and / or url fields.
• if present, the email and url fields should be valid email and url, respectively.

It returns a list of error messages, if any violations are found.

Examples

import { validateAuthor } from "package-json-validator";

const packageData = {
	author: {
		email: "[e-mail]",
		name: "Barney Rubble",
		url: "http://barnyrubble.tumblr.com/",
	},
};

const errors = validateAuthor(packageData.author);

import { validateAuthor } from "package-json-validator";

const packageData = {
	author: "Barney Rubble <[e-mail]> (http://barnyrubble.tumblr.com/)",
};

const errors = validateAuthor(packageData.author);

validateBin(value)

This function validates the value of the bin property of a package.json. It takes the value, and validates it against the following criteria.

• It should be of type string or object.
• If it's a string, it should be a relative path to an executable file.
• If it's an object, it should be a key to string value object, and the values should all be relative paths.

It returns a list of error messages, if any violations are found.

Examples

import { validateBin } from "package-json-validator";

const packageData = {
	bin: "./my-cli.js",
};

const errors = validateBin(packageData.bin);

import { validateBin } from "package-json-validator";

const packageData = {
	bin: {
		"my-cli": "./my-cli.js",
		"my-dev-cli": "./dev/my-cli.js",
	},
};

const errors = validateBin(packageData.bin);

validateBundleDependencies(value)

This function validates the value of the bundleDependencies property of a package.json. It takes the value, and validates it against the following criteria.

• the property is either an array or a boolean
• if it's an array, all items should be strings

It returns a list of error messages, if any violations are found.

Examples

import { validateBundleDependencies } from "package-json-validator";

const packageData = {
	bundleDependencies: ["renderized", "super-streams"],
};

const errors = validateBundleDependencies(packageData.bundleDependencies);

validateConfig(value)

This function validates the value of the config property of a package.json. It takes the value, and validates that it's an object.

It returns a list of error messages, if a violation is found.

Examples

import { validateConfig } from "package-json-validator";

const packageData = {
	config: {
		debug: true,
		host: "localhost",
		port: 8080,
	},
};

const errors = validateScripts(packageData.config);

validateCpu(value)

This function validates the value of the cpu property of a package.json. It takes the value, and validates it against the following criteria.

• the property is an array
• all items in the array should be non-empty strings

It returns a list of error messages, if any violations are found.

Examples

import { validateCpu } from "package-json-validator";

const packageData = {
	cpu: ["x64", "ia32"],
};

const errors = validateCpu(packageData.cpu);

validateDependencies(value)

Also: validateDevDependencies(value), validateOptionalDependencies(value), and validatePeerDependencies(value)

These functions validate the value of their respective dependency property. They take the value, and validate it against the following criteria.

• It should be of type an object.
• The object should be a record of key value pairs
• For each property, the key should be a valid package name, and the value should be a valid version

It returns a list of error messages, if any violations are found.

Examples

import { validateDependencies } from "package-json-validator";

const packageData = {
	dependencies: {
		"@catalog/package": "catalog:",
		"@my/package": "^1.2.3",
		"@workspace/package": "workspace:^",
	},
};

const errors = validateBin(packageData.dependencies);

validateDescription(value)

This function validates the value of the description property of a package.json. It checks that the value is a non-empty string, and returns a list of error messages, if a violation is found.

Examples

import { validateDescription } from "package-json-validator";

const packageData = {
	description: "The Fragile",
};

const errors = validateDescription(packageData.description);

validateDirectories(value)

This function validates the value of the directories property of a package.json. It takes the value, and validates it against the following criteria.

• the property is an object
• its keys are non-empty strings
• its values are all non-empty strings

It returns a list of error messages, if any violations are found.

Examples

import { validateDirectories } from "package-json-validator";

const packageData = {
	directories: {
		bin: "dist/bin",
		man: "docs",
	},
};

const errors = validateDirectories(packageData.directories);

validateExports(value)

This function validates the value of the exports property of a package.json. It takes the value, and validates it against the following criteria.

• It should be of type string or object.
• If it's a string, it should be a path to an entry point.
• If it's an export condition object, its properties should have values that are either a path to an entry point, or another exports condition object.

It returns a list of error messages, if any violations are found.

Examples

import { validateExports } from "package-json-validator";

const packageData = {
	exports: "./index.js",
};

const errors = validateExports(packageData.exports);

/* eslint-disable perfectionist/sort-objects */
import { validateExports } from "package-json-validator";

const packageData = {
	exports: {
		".": {
			types: "./index.d.ts",
			default: "./index.js",
		},
		"./secondary": {
			types: "./secondary.d.ts",
			default: "./secondary.js",
		},
	},
};

const errors = validateExports(packageData.exports);
/* eslint-enable perfectionist/sort-objects */

validateLicense(value)

This function validates the value of the license property of a package.json. It takes the value, and validates it using validate-npm-package-license, which is the same package that npm uses.

It returns a list of error messages, if a violation is found.

Examples

import { validateLicense } from "package-json-validator";

const packageData = {
	license: "MIT",
};

const errors = validateLicense(packageData.license);

validateScripts(value)

This function validates the value of the scripts property of a package.json. It takes the value, and validates it against the following criteria.

• the property is an object
• its keys are non-empty strings
• its values are all non-empty strings

It returns a list of error messages, if any violations are found.

Examples

import { validateScripts } from "package-json-validator";

const packageData = {
	scripts: {
		build: "rollup -c",
		lint: "eslint .",
		test: "vitest",
	},
};

const errors = validateScripts(packageData.scripts);

validateType(value)

This function validates the value of the type property of a package.json. It takes the value, and validates it against the following criteria.

• the property is a string
• its value is either 'commonjs' or 'module'

It returns an error message, if a violation is found.

Examples

import { validateType } from "package-json-validator";

const packageData = {
	type: "module",
};

const errors = validateType(packageData.type);

validateVersion(value)

This function validates the value of the version property of a package.json. It takes the value, and validates it using semver, which is the same package that npm uses.

It returns a list of error messages, if a violation is found.

Examples

import { validateVersion } from "package-json-validator";

const packageData = {
	version: "1.2.3",
};

const errors = validateVersion(packageData.version);

Specification

This package uses the npm spec along with additional supporting documentation from node, as its source of truth for validation.

Deprecation Policy

We never want to remove things, when we're building them! But the reality is that libraries evolve and deprecations are a fact of life. Following are the different timeframes that we've defined as it relates to deprecating APIs in this project.

RFC Timeframe (6 weeks)

When some aspect of our API is going to be deprecated (and eventually removed), it must initially go through an RFC phase. Whoever's motivating the removal of the api, should create an RFC issue explaining the proposal and inviting feedback from the community. That RFC should remain active for at least 6 weeks. The RFC text should make clear what the target date is for closing the RFC. Once the RFC period is over, if the removal is still moving forward, the API(s) should be officially deprecated.

Removal Timeframe (6 months)

Once an API has been marked as deprecated, it will remain intact for at least 6 months. After 6 months from the date of deprecation, the API is subject to removal.

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 💖

Contributors

Alan 🤔	Amila Welihinda 💻	Andreas Brekken 💻	August Valera 💻	Azat S. 💻	Brad Jorsch 💻	Brett Zamir 🤔
Chris Montgomery 💻	Clay Carpenter 💻	Daniel Bayley 🐛	Dav Glass 💻	Denis 💻	DjDCH 🐛	Eli 🐛 💻
Eric Cornelissen 🐛	Gord Tanner 💻	Hannah Wolfe 🤔	Hemanth HM 💻	J Rob Gant 🐛	Jason Jarrett 🤔	Jason Karns 🤔
Jatin Chopra 💻	Josh Goldberg ✨ 🐛 💻 📖 🤔 🚧 🔧 🖋 🚇 📆	L N M Anudeep 💻	Linus Unnebäck 🚧	Matthew Holloway 🐛	Nick Sullivan 🐛 💻 📖 🤔 🚧	Norman Sue 🐛
Peter deHaan 🤔 💻	Reggi 🤔	Sebastien Dubois 💻	Simon 🤔	Slava Fomin II 🤔	Stephen Zhou 💻	Veniamin Krol 💻
gramergrater 🐛	michael faith 💻 🤔 🚇 🔧 🚧 🐛 📖	sarahhagstrom 💻

Appreciation

Many thanks to @TechNickAI for creating the initial version and core infrastructure of this package! 💖

💝 This package was templated with create-typescript-app using the Bingo framework.

Changelog

0.30.0 (2025-08-22)

Features

• deprecate CLI (#413) (f90520f), closes #264 /github.com/JoshuaKGoldberg/package-json-validator/issues/264#issuecomment-3212272711