normalize-package-data
Advanced tools
The normalize-package-data npm package is used to normalize the metadata of a package.json file according to the npm and Node.js specifications. This includes cleaning up various fields, ensuring required fields are present, and providing default values where appropriate.
Normalization of package metadata
This feature takes a package.json object and normalizes its metadata. After normalization, the package object is modified in place to meet the standard structure and fields as defined by npm and Node.js.
const normalize = require('normalize-package-data');
let pkg = { name: 'example', version: '1.0.0' };
normalize(pkg);
console.log(pkg);Validation of package data
The package also validates the package data and attaches an array of error messages to the package object if there are any issues found during normalization.
const normalize = require('normalize-package-data');
let pkg = { name: 'example', version: '1.0.0' };
normalize(pkg);
if (pkg.errors) {
console.error('Package data contains errors:', pkg.errors);
}Warning for non-standard fields
If the package data contains non-standard fields, the normalization process will not remove them but will provide warnings about their presence.
const normalize = require('normalize-package-data');
let pkg = { name: 'example', version: '1.0.0', nonStandardField: 'some value' };
normalize(pkg);
if (pkg.warnings) {
console.warn('Package data contains warnings:', pkg.warnings);
}The read-pkg package reads a package.json file, parses it to JSON, and then normalizes the package data. It is similar to normalize-package-data but includes the file reading and parsing step.
This package is similar to read-pkg but goes one step further by searching for the nearest package.json file in the directory tree. It then reads, parses, and normalizes the package data.
pkg-conf is a package that retrieves configuration from package.json properties. It is not a direct alternative to normalize-package-data but can be used in conjunction to retrieve and normalize configuration data.
normalize-package-data exports a function that normalizes package metadata. This data is typically found in a package.json file, but in principle could come from any source - for example the npm registry.
normalize-package-data is used by read-package-json to normalize the data it reads from a package.json file. In turn, read-package-json is used by npm and various npm-related tools.
npm install normalize-package-data
Basic usage is really simple. You call the function that normalize-package-data exports. Let's call it normalizeData.
normalizeData = require('normalize-package-data')
packageData = require("./package.json")
normalizeData(packageData)
// packageData is now normalized
You may activate strict validation by passing true as the second argument.
normalizeData = require('normalize-package-data')
packageData = require("./package.json")
normalizeData(packageData, true)
// packageData is now normalized
If strict mode is activated, only Semver 2.0 version strings are accepted. Otherwise, Semver 1.0 strings are accepted as well. Packages must have a name, and the name field must not have contain leading or trailing whitespace.
Optionally, you may pass a "warning" function. It gets called whenever the normalizeData function encounters something that doesn't look right. It indicates less than perfect input data.
normalizeData = require('normalize-package-data')
packageData = require("./package.json")
warnFn = function(msg) { console.error(msg) }
normalizeData(packageData, warnFn)
// packageData is now normalized. Any number of warnings may have been logged.
You may combine strict validation with warnings by passing true as the second argument, and warnFn as third.
When private field is set to true, warnings will be suppressed.
If the supplied data has an invalid name or version field, normalizeData will throw an error. Depending on where you call normalizeData, you may want to catch these errors so can pass them to a callback.
name field gets trimmed (unless in strict mode).version field gets cleaned by semver.clean. See documentation for the semver module.name and/or version fields are missing, they are set to empty strings.files field is not an array, it will be removed.bin field is a string, then bin field will become an object with name set to the value of the name field, and bin set to the original string value.man field is a string, it will become an array with the original string as its sole member.keywords field is string, it is considered to be a list of keywords separated by one or more white-space characters. It gets converted to an array by splitting on \s+.author, maintainers, contributors) get converted into objects with name, email and url properties.bundledDependencies field (a typo) exists and bundleDependencies field does not, bundledDependencies will get renamed to bundleDependencies.dependencies, devDependencies, optionalDependencies) is a string, it gets converted into an object with familiar name=>value pairs.optionalDependencies get added to dependencies. The optionalDependencies array is left untouched.org/proj, github:org/proj, bitbucket:org/proj, gitlab:org/proj, gist:docid) will have the shortcut left in place. (In the case of github, the org/proj form will be expanded to github:org/proj.) THIS MARKS A BREAKING CHANGE FROM V1, where the shortcut was previously expanded to a URL.description field does not exist, but readme field does, then (more or less) the first paragraph of text that's found in the readme is taken as value for description.repository field is a string, it will become an object with url set to the original string value, and type set to "git".repository.url is not a valid url, but in the style of "[owner-name]/[repo-name]", repository.url will be set to git+https://github.com/[owner-name]/[repo-name].gitbugs field is a string, the value of bugs field is changed into an object with url set to the original string value.bugs field does not exist, but repository field points to a repository hosted on GitHub, the value of the bugs field gets set to an url in the form of https://github.com/[owner-name]/[repo-name]/issues . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.bugs field is an object, the resulting value only has email and url properties. If email and url properties are not strings, they are ignored. If no valid values for either email or url is found, bugs field will be removed.homepage field is not a string, it will be removed.homepage field does not specify a protocol, then http is assumed. For example, myproject.org will be changed to http://myproject.org.homepage field does not exist, but repository field points to a repository hosted on GitHub, the value of the homepage field gets set to an url in the form of https://github.com/[owner-name]/[repo-name]#readme . If the repository field points to a GitHub Gist repo url, the associated http url is chosen.If name field is given, the value of the name field must be a string. The string may not:
/@\s+%node_modules or favicon.ico (case doesn't matter).If version field is given, the value of the version field must be a valid semver string, as determined by the semver.valid method. See documentation for the semver module.
The license/licence field should be a valid SPDX license expression or one of the special values allowed by validate-npm-package-license. See documentation for the license field in package.json.
This package contains code based on read-package-json written by Isaac Z. Schlueter. Used with permission.
normalize-package-data is released under the BSD 2-Clause License. Copyright (c) 2013 Meryn Stol
7.0.0 (2024-09-24)
normalize-package-data now supports node ^18.17.0 || >=20.5.0FAQs
Normalizes data that can be found in package.json files.
The npm package normalize-package-data receives a total of 34,868,169 weekly downloads. As such, normalize-package-data popularity was classified as popular.
We found that normalize-package-data demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.