package
Tools to validate package.json files.
npm install package-json-validatorGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Latest published Nov 15, 2026
mfaith
michael.faith@gmail.com
npm install package-json-validatorimport { validate } from 'package-json-validator';
validate(/* ... */);For tools that run these validations, see:
Following are the types involved in the return type of our granular validate* functions.
The Result type, is the common top-level return type for all of our granular validate* functions.
It provides rich information about the nature of the issues encountered as part of validating.
For complex objects like exports, its tree structure can give information on which parts of the structure have issues.
The full collection of error messages (including errors from child element).
This consists of the Issue.message for all of the items in this Result's issues, as well as the messages of all descendent issues.
Collection of issues for this object (property or array element).
Collection of result objects for child elements (either properties or array elements), if this property is an object or array.
Result object for a child (either a property in an object or an element of an array).
The index of this property in relation to its parent's collection (properties or array elements).
The message with information about this issue.
This function validates an entire package.json and returns a list of errors, if
any violations are found.
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
}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);
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'
// ]
// }Starting in v1.4, you can opt-in to the new Result return type for validate.
This has been the return type for all of the more granular validate* functions for a while now, and gives more specific information about which parts of the package.json are failing validation.
See Result Types for more details about this construct.
If you'd like to opt-in to the new behavior before it becomes the default experience, pass true into the second parameter.
import { validate } from 'package-json-validator';
const data = {
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'],
},
};
let result = validate(data, true);
console.log(result.issues.length); // 0
console.log(result.errorMessages.length); // 0
console.log(result.childResults.length); // 7 (one for each top-level property)
result = validate({}, true);
console.log(result.issues.length); // 2
console.log(result.childResults.length); // 0
console.log(result.errorMessages);
// [
// 'Missing required property: name',
// 'Missing required property: version',
// ]This function validates the value of the author property of a package.json.
It takes the value, and validates it against the following criteria.
name field and, optionally, email and / or url fields.email and url fields should be valid email and url, respectively.It returns a Result object (See Result Types).
import { validateAuthor } from 'package-json-validator';
const packageData = {
author: {
email: 'b@rubble.com',
name: 'Barney Rubble',
url: 'http://barnyrubble.tumblr.com/',
},
};
const result = validateAuthor(packageData.author);import { validateAuthor } from 'package-json-validator';
const packageData = {
author: 'Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)',
};
const result = validateAuthor(packageData.author);This function validates the value of the bin property of a package.json.
It takes the value, and validates it against the following criteria.
string or object.string, it should be a relative path to an executable file.object, it should be a key to string value object, and the values should all be relative paths.It returns a Result object (See Result Types).
import { validateBin } from 'package-json-validator';
const packageData = {
bin: './my-cli.js',
};
const result = 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 result = validateBin(packageData.bin);This function validates the value of the browser property of a package.json, checking that the value is a non-empty string.
It returns a Result object (See Result Types).
import { validateBrowser } from 'package-json-validator';
const packageData = {
browser: 'index.umd.js',
};
const result = validateBrowser(packageData.browser);This function validates the value of the bugs property of a package.json.
It takes the value, and validates that it's one of the following.
string urlobject with either properties email or url (or both)email should be a valid email addressurl should be a valid URLIt returns a Result object (See Result Types).
import { validateBugs } from 'package-json-validator';
const packageData = {
bugs: {
email: 'example@npmjs.com',
url: 'https://github.com/npm/example/issues',
},
};
const result = validateBugs(packageData.bugs);This function validates the value of the bundleDependencies property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateBundleDependencies } from 'package-json-validator';
const packageData = {
bundleDependencies: ['renderized', 'super-streams'],
};
const result = validateBundleDependencies(packageData.bundleDependencies);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 Result object (See Result Types).
import { validateConfig } from 'package-json-validator';
const packageData = {
config: {
debug: true,
host: 'localhost',
port: 8080,
},
};
const result = validateConfig(packageData.config);This function validates the value of the contributors property of a package.json.
It takes the value, and validates it against the following criteria.
Array of objectsname and optionally email and urlemail and url properties, if present, should be valid email and URL formats.It returns a Result object (See Result Types).
import { validateContributors } from 'package-json-validator';
const packageData = {
contributors: [
{
email: 'b@rubble.com',
name: 'Barney Rubble',
url: 'http://barnyrubble.tumblr.com/',
},
],
};
const result = validateContributors(packageData.contributors);This function validates the value of the cpu property of a package.json.
It takes the value, and validates it against the following criteria.
"arm", "arm64", "ia32", "loong64", "mips", "mipsel", "ppc64", "riscv64", "s390", "s390x", "x64"
[!NOTE] These values are the list of possible
process.archvalues documented by Node.
It returns a Result object (See Result Types).
import { validateCpu } from 'package-json-validator';
const packageData = {
cpu: ['x64', 'ia32'],
};
const result = validateCpu(packageData.cpu);Also: validateDevDependencies, validateOptionalDependencies, and validatePeerDependencies
These functions validate the value of their respective dependency property.
They take the value, and validate it against the following criteria.
object.It returns a Result object (See Result Types).
import { validateDependencies } from 'package-json-validator';
const packageData = {
dependencies: {
'@catalog/package': 'catalog:',
'@my/package': '^1.2.3',
'@workspace/package': 'workspace:^',
},
};
const result = validateDependencies(packageData.dependencies);allowNamedRegistries: Relaxes validation on dependency versions to allow for named registries, a feature supported by pnpm since 11.1.0 (Default: false)import { validateDependencies } from 'package-json-validator';
const packageData = {
dependencies: {
'@my/package': '^1.2.3',
'@company/package': 'work:svgo@^1.0.0', // Would have failed validation
},
};
const result = validateDependencies(packageData.dependencies, {
allowNamedRegistries: true,
});This function validates the value of the description property of a package.json, checking that the value is a non-empty string.
It returns a Result object (See Result Types).
import { validateDescription } from 'package-json-validator';
const packageData = {
description: 'The Fragile',
};
const result = validateDescription(packageData.description);This function validates the value of the directories property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateDirectories } from 'package-json-validator';
const packageData = {
directories: {
bin: 'dist/bin',
man: 'docs',
},
};
const result = validateDirectories(packageData.directories);This function validates the value of the devEngines property of a package.json.
It takes the value, and validates it against the following criteria.
object with any of the following properties
cpulibcospackageManagerruntimename (required): the name of the engine, e.g. "node", "npm", "yarn", "bun"version (optional): the version of the engine, which should be a valid semver rangeonFail (optional): should be one of the following values: warn, error, ignore or downloadIt returns a Result object (See Result Types).
import { validateDevEngines } from 'package-json-validator';
const packageData = {
devEngines: {
runtime: {
name: 'node',
version: '^20.19.0 || >=22.12.0',
onFail: 'download',
},
packageManager: {
name: 'pnpm',
version: '^10.0.0',
onFail: 'error',
},
},
};
const result = validateDevEngines(packageData.devEngines);This function validates the value of the engines property of a package.json.
It takes the value, and validates it against the following criteria.
object.It returns a Result object (See Result Types).
import { validateEngines } from 'package-json-validator';
const packageData = {
engines: {
node: '^20.19.0 || >=22.12.0',
},
};
const result = validateEngines(packageData.engines);This function validates the value of the exports property of a package.json.
It takes the value, and validates it against the following criteria.
string or object.string, it should be a path to an entry point.object, its properties should have values that are either a path to an entry point, or another exports condition object.It returns a Result object (See Result Types).
import { validateExports } from 'package-json-validator';
const packageData = {
exports: './index.js',
};
const result = validateExports(packageData.exports);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 result = validateExports(packageData.exports);This function validates the value of the files property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateFiles } from 'package-json-validator';
const packageData = {
files: ['dist', 'CHANGELOG.md'],
};
const result = validateFiles(packageData.files);This function validates the value of the funding property of a package.json.
It takes the value, and validates that it's one of the following.
string urlobject with properties type and url, with url being a valid urlArray consisting of items of the above twoIt returns a Result object (See Result Types).
import { validateFunding } from 'package-json-validator';
const packageData = {
funding: [
{
type: 'individual',
url: 'http://npmjs.com/donate',
},
'http://npmjs.com/donate-also',
{
type: 'patreon',
url: 'https://www.patreon.com/user',
},
],
};
const result = validateFunding(packageData.funding);This function validates the value of the gypfile property of a package.json.
It takes the value, and checks that it's a boolean.
It returns a Result object (See Result Types).
import { validateGypfile } from 'package-json-validator';
const packageData = {
gypfile: false,
};
const result = validateGypfile(packageData.gypfile);This function validates the value of the homepage property of a package.json, checking that the value is a string containing a valid url.
It returns a Result object (See Result Types).
import { validateHomepage } from 'package-json-validator';
const packageData = {
homepage: 'The Fragile',
};
const result = validateDescription(packageData.homepage);This function validates the value of the keywords property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateKeywords } from 'package-json-validator';
const packageData = {
keywords: ['eslint', 'package.json'],
};
const result = validateKeywords(packageData.keywords);This function validates the value of the libc property of a package.json.
It takes the value, and validates that it's either a string or an Array of strings.
It returns a Result object (See Result Types).
import { validateLibc } from 'package-json-validator';
const packageData = {
libc: 'glibc',
};
const result = validateLibc(packageData.man);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 Result object (See Result Types).
import { validateLicense } from 'package-json-validator';
const packageData = {
license: 'MIT',
};
const result = validateLicense(packageData.license);This function validates the value of the main property of a package.json, checking that the value is a non-empty string.
It returns a Result object (See Result Types).
import { validateMain } from 'package-json-validator';
const packageData = {
main: 'index.js',
};
const result = validateMain(packageData.main);This function validates the value of the man property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateMan } from 'package-json-validator';
const packageData = {
man: ['./man/foo.1', './man/bar.1'],
};
const result = validateMan(packageData.man);This function validates the value of the name property of a package.json.
It takes the value, and validates it using validate-npm-package-name, which is the same package that npm uses.
It returns a Result object (See Result Types).
import { validateName } from 'package-json-validator';
const packageData = {
name: 'some-package',
};
const result = validateName(packageData.name);This function validates the value of the os property of a package.json.
It takes the value, and validates it against the following criteria.
"aix", "android", "darwin", "freebsd", "linux", "openbsd", "sunos", and "win32"
[!NOTE] These values are the list of possible
process.platformvalues documented by Node.
It returns a Result object (See Result Types).
import { validateOs } from 'package-json-validator';
const packageData = {
os: ['linux', 'win32'],
};
const result = validateOs(packageData.os);This function validates the value of the packageManager property of a package.json.
It takes the value, and checks that it's a string with a valid package manager and version.
The package manager portion should be npm, pnpm, yarn, bun, or deno, while the version portion should be a valid semver version.
It returns a Result object (See Result Types).
import { validatePackageManager } from 'package-json-validator';
const packageData = {
packageManager: 'pnpm@10.3.0',
};
const result = validatePackageManager(packageData.packageManager);This function validates the value of the peerDependenciesMeta property of a package.json.
It takes the value, and checks that it is an object whose keys are valid package names and whose values are objects with only an optional property.
The optional property must be a boolean.
It returns a Result object (See Result Types).
import { validatePeerDependenciesMeta } from 'package-json-validator';
const packageData = {
peerDependenciesMeta: {
react: {
optional: true,
},
},
};
const result = validatePeerDependenciesMeta(packageData.peerDependenciesMeta);This function validates the value of the private property of a package.json.
It takes the value, and checks that it's a boolean.
It returns a Result object (See Result Types).
import { validatePrivate } from 'package-json-validator';
const packageData = {
private: true,
};
const result = validatePrivate(packageData.private);This function validates the value of the publishConfig property of a package.json.
It takes the value, and validates it against the following criteria.
[!NOTE] These properties are a (non-exhaustive) combination of those supported by
npm,pnpm, andyarn.
It returns a Result object (See Result Types).
import { validatePublishConfig } from 'package-json-validator';
const packageData = {
publishConfig: {
provenance: true,
},
};
const result = validatePublishConfig(packageData.publishConfig);This function validates the value of the repository property of a package.json.
It takes the value, and validates it against the following criteria.
object or string.object, it should have type, url, and optionally directory.type and directory (if present) should be non-empty stringsurl should be a valid repo urlstring, it should be the shorthand repo string from a supported provider.It returns a Result object (See Result Types).
import { validateRepository } from 'package-json-validator';
const packageData = {
repository: {
type: 'git',
url: 'git+https://github.com/michaelfaith/package-json-validator.git',
directory: 'packages/package-json-validator',
},
};
const result = validateRepository(packageData.repository);import { validateRepository } from 'package-json-validator';
const packageData = {
repository: 'github:michaelfaith/package-json-validator',
};
const result = validateRepository(packageData.repository);This function validates the value of the scripts property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateScripts } from 'package-json-validator';
const packageData = {
scripts: {
build: 'rollup -c',
lint: 'eslint .',
test: 'vitest',
},
};
const result = validateScripts(packageData.scripts);This function validates the value of the sideEffects property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateSideEffects } from 'package-json-validator';
const packageData = {
sideEffects: false,
};
const result = validateSideEffects(packageData.sideEffects);This function validates the value of the type property of a package.json.
It takes the value, and validates it against the following criteria.
'commonjs' or 'module'It returns a Result object (See Result Types).
import { validateType } from 'package-json-validator';
const packageData = {
type: 'module',
};
const result = validateType(packageData.type);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 Result object (See Result Types).
import { validateVersion } from 'package-json-validator';
const packageData = {
version: '1.2.3',
};
const result = validateVersion(packageData.version);This function validates the value of the workspaces property of a package.json.
It takes the value, and validates it against the following criteria.
It returns a Result object (See Result Types).
import { validateWorkspaces } from 'package-json-validator';
const packageData = {
workspaces: ['./app', './packages/*'],
};
const result = validateWorkspaces(packageData.cpu);This package uses the npm spec along with additional supporting documentation from node, as its source of truth for validation.
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.
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.
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.
See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md.
Thanks! 💖
Many thanks to @TechNickAI for creating the initial version and core infrastructure of this package! 💖
Daniel Bayley 🐛 |
Dav Glass 💻 |
Denis 💻 |
DjDCH 🐛 |
Gord Tanner 💻 |
gramergrater 🐛 |
Hannah Wolfe 🤔 |
Hemanth HM 💻 |
hh.lohmann 📖 |
Jason Jarrett 🤔 |
Jason Karns 🤔 |
Jatin Chopra 💻 |
Josh Goldberg ✨ 🐛 💻 📖 🤔 🚧 🔧 🖋 🚇 📆 |
L N M Anudeep 💻 |
Matthew Holloway 🐛 |
michael faith 💻 🤔 🚇 🔧 🚧 🐛 📖 |
Morrison Cole 🐛 💻 |
Nick Sullivan 🐛 💻 📖 🤔 🚧 |
Norman Sue 🐛 |
Sebastien Dubois 💻 |
Simon 🤔 |
Slava Fomin II 🤔 |
Stephen Zhou 💻 |
Estimated unpacked size across 13 packages.
3.6 MB
Includes dependencies.