validate-npm-package-name

What is validate-npm-package-name?

The validate-npm-package-name package is used to check if a given string is a valid npm package name. It ensures that the package name meets the npm naming constraints, such as length, format, and character restrictions. It is useful for developers who are creating new npm packages and want to validate their package names before publishing to the npm registry.

What are validate-npm-package-name's main functionalities?

Validation of package names

This feature allows you to validate a string to see if it would be a valid npm package name. It checks against rules for both new packages and old packages that were allowed before stricter rules were applied. The result object contains two boolean properties: 'validForNewPackages' and 'validForOldPackages'.

{"validForNewPackages": true, "validForOldPackages": true}

Error and warning messages

If the package name is invalid, the function will return an object with 'errors' and 'warnings' arrays that provide information about why the name is invalid. This is useful for giving feedback to users so they can correct their package names.

{"validForNewPackages": false, "validForOldPackages": false, "errors": ["name cannot start with a dot"], "warnings": ["name is discouraged"]}

Other packages similar to validate-npm-package-name

npm-name

The npm-name package checks whether a package name is available on the npm registry. It differs from validate-npm-package-name in that it specifically checks for name availability rather than just format validity.

package-name-regex

This package provides a regular expression to test if a string is a valid npm package name. It is similar to validate-npm-package-name but offers a lower-level approach using regex matching instead of a function that returns an object with details.

README

validate-npm-package-name

Give me a string and I'll tell you if it's a valid npm package name.

This package exports a single synchronous function that takes a string as input and returns an object with two properties:

• validForNewPackages :: Boolean
• validForOldPackages :: Boolean

Contents

• Naming rules
• Examples
  • Valid Names
  • Invalid Names
• Legacy Names
• Tests
• License

Naming Rules

Below is a list of rules that valid npm package name should conform to.

• package name length should be greater than zero
• all the characters in the package name must be lowercase i.e., no uppercase or mixed case names are allowed
• package name can consist of hyphens
• package name must not contain any non-url-safe characters (since name ends up being part of a URL)
• package name should not start with . or _
• package name should not contain any spaces
• package name should not contain any of the following characters: ~)('!*
• package name cannot be the same as a node.js/io.js core module nor a reserved/blacklisted name. For example, the following names are invalid:
  • http
  • stream
  • node_modules
  • favicon.ico
• package name length cannot exceed 214

Examples

Valid Names

var validate = require("validate-npm-package-name")

validate("some-package")
validate("example.com")
validate("under_score")
validate("123numeric")
validate("@npm/thingy")
validate("@jane/foo.js")

All of the above names are valid, so you'll get this object back:

{
  validForNewPackages: true,
  validForOldPackages: true
}

Invalid Names

validate("excited!")
validate(" leading-space:and:weirdchars")

That was never a valid package name, so you get this:

{
  validForNewPackages: false,
  validForOldPackages: false,
  errors: [
    'name cannot contain leading or trailing spaces',
    'name can only contain URL-friendly characters'
  ]
}

Legacy Names

In the old days of npm, package names were wild. They could have capital letters in them. They could be really long. They could be the name of an existing module in node core.

If you give this function a package name that used to be valid, you'll see a change in the value of validForNewPackages property, and a warnings array will be present:

validate("eLaBorAtE-paCkAgE-with-mixed-case-and-more-than-214-characters-----------------------------------------------------------------------------------------------------------------------------------------------------------")

returns:

{
  validForNewPackages: false,
  validForOldPackages: true,
  warnings: [
    "name can no longer contain capital letters",
    "name can no longer contain more than 214 characters"
  ]
}

Tests

npm install
npm test

License

ISC

Changelog

6.0.0 (2024-09-24)

⚠️ BREAKING CHANGES

• validate-npm-package-name now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• d14349c #131 align to npm 10 node engine range (@hashtagchris)

Chores

• e78d90d #131 run template-oss-apply (@hashtagchris)
• 3b308e9 #128 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (@dependabot[bot])
• 5f444c8 #129 postinstall for dependabot template-oss PR (@hashtagchris)
• a75975a #129 bump @npmcli/template-oss from 4.23.1 to 4.23.3 (@dependabot[bot])