README.md
1# validate-npm-package-name
2
3Give me a string and I'll tell you if it's a valid `npm` package name.
4
5This package exports a single synchronous function that takes a `string` as
6input and returns an object with two properties:
7
8- `validForNewPackages` :: `Boolean`
9- `validForOldPackages` :: `Boolean`
10
11## Contents
12
13- [Naming rules](#naming-rules)
14- [Examples](#examples)
15 + [Valid Names](#valid-names)
16 + [Invalid Names](#invalid-names)
17- [Legacy Names](#legacy-names)
18- [Tests](#tests)
19- [License](#license)
20
21## Naming Rules
22
23Below is a list of rules that valid `npm` package name should conform to.
24
25- package name length should be greater than zero
26- all the characters in the package name must be lowercase i.e., no uppercase or mixed case names are allowed
27- package name *can* consist of hyphens
28- package name must *not* contain any non-url-safe characters (since name ends up being part of a URL)
29- package name should not start with `.` or `_`
30- package name should *not* contain any leading or trailing spaces
31- package name should *not* contain any of the following characters: `~)('!*`
32- 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:
33 + http
34 + stream
35 + node_modules
36 + favicon.ico
37- package name length cannot exceed 214
38
39
40## Examples
41
42### Valid Names
43
44```js
45var validate = require("validate-npm-package-name")
46
47validate("some-package")
48validate("example.com")
49validate("under_score")
50validate("123numeric")
51validate("excited!")
52validate("@npm/thingy")
53validate("@jane/foo.js")
54```
55
56All of the above names are valid, so you'll get this object back:
57
58```js
59{
60 validForNewPackages: true,
61 validForOldPackages: true
62}
63```
64
65### Invalid Names
66
67```js
68validate(" leading-space:and:weirdchars")
69```
70
71That was never a valid package name, so you get this:
72
73```js
74{
75 validForNewPackages: false,
76 validForOldPackages: false,
77 errors: [
78 'name cannot contain leading or trailing spaces',
79 'name can only contain URL-friendly characters'
80 ]
81}
82```
83
84## Legacy Names
85
86In the old days of npm, package names were wild. They could have capital
87letters in them. They could be really long. They could be the name of an
88existing module in node core.
89
90If you give this function a package name that **used to be valid**, you'll see
91a change in the value of `validForNewPackages` property, and a warnings array
92will be present:
93
94```js
95validate("eLaBorAtE-paCkAgE-with-mixed-case-and-more-than-214-characters-----------------------------------------------------------------------------------------------------------------------------------------------------------")
96```
97
98returns:
99
100```js
101{
102 validForNewPackages: false,
103 validForOldPackages: true,
104 warnings: [
105 "name can no longer contain capital letters",
106 "name can no longer contain more than 214 characters"
107 ]
108}
109```
110
111## Tests
112
113```sh
114npm install
115npm test
116```
117
118## License
119
120ISC
121