0
# validate-npm-package-name
1

2
Validates npm package names according to current and legacy npm registry rules, returning detailed validation results with specific error and warning messages. This library helps determine if a string is valid as an npm package name, distinguishing between packages that can be newly published versus those that were valid under older naming rules.
3

4
## Package Information
5

6
- **Package Name**: validate-npm-package-name
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install validate-npm-package-name`
10

11
## Core Imports
12

13
```javascript
14
const validate = require("validate-npm-package-name");
15
```
16

17
For ES modules:
18

19
```javascript
20
import validate from "validate-npm-package-name";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const validate = require("validate-npm-package-name");
27

28
// Valid package names
29
const result1 = validate("some-package");
30
// { validForNewPackages: true, validForOldPackages: true }
31

32
const result2 = validate("@npm/scoped-package");
33
// { validForNewPackages: true, validForOldPackages: true }
34

35
// Invalid package names with errors
36
const result3 = validate(" leading-space");
37
// {
38
//   validForNewPackages: false,
39
//   validForOldPackages: false,
40
//   errors: ['name cannot contain leading or trailing spaces', 'name can only contain URL-friendly characters']
41
// }
42

43
// Legacy names with warnings
44
const result4 = validate("UPPERCASE-NAME");
45
// {
46
//   validForNewPackages: false,
47
//   validForOldPackages: true,
48
//   warnings: ['name can no longer contain capital letters']
49
// }
50

51
const result5 = validate("crazy!");
52
// {
53
//   validForNewPackages: false,
54
//   validForOldPackages: true,
55
//   warnings: ['name can no longer contain special characters ("~\'!()*")']
56
// }
57
```
58

59
## Capabilities
60

61
### Package Name Validation
62

63
The main validation function that checks npm package names against all naming rules.
64

65
```javascript { .api }
66
/**
67
 * Validates an npm package name according to current and legacy rules
68
 * @param {any} name - The package name to validate (expected to be string)
69
 * @returns {ValidationResult} Validation result with validity flags and messages
70
 */
71
function validate(name);
72
```
73

74
**Validation Rules:**
75

76
**Error Conditions** (invalid for both new and old packages):
77
- Name is `null`, `undefined`, or not a string
78
- Name length is zero
79
- Name starts with period (`.`) or underscore (`_`)
80
- Name contains leading or trailing spaces
81
- Name matches reserved names (`node_modules`, `favicon.ico`)
82
- Name contains non-URL-friendly characters (except valid scoped packages)
83

84
**Warning Conditions** (invalid for new packages, valid for legacy):
85
- Name matches Node.js core module names (`http`, `events`, etc.)
86
- Name length exceeds 214 characters
87
- Name contains uppercase letters
88
- Name contains special characters: `~`, `'`, `!`, `(`, `)`, `*`
89

90
**Special Handling:**
91
- **Scoped packages**: Names like `@scope/package` receive special validation
92
- **Core modules**: Automatically detected using Node.js built-in module list
93
- **URL safety**: Validated using `encodeURIComponent` comparison
94

95
## Types
96

97
```javascript { .api }
98
/**
99
 * Result object returned by the validate function
100
 */
101
interface ValidationResult {
102
  /** True if the name is valid for newly published packages */
103
  validForNewPackages: boolean;
104
  /** True if the name is valid under legacy npm naming rules */
105
  validForOldPackages: boolean;
106
  /** Array of warning messages for legacy rule violations (omitted if empty) */
107
  warnings?: string[];
108
  /** Array of error messages for naming rule violations (omitted if empty) */
109
  errors?: string[];
110
}
111
```
112

113
## Usage Examples
114

115
### Valid Names
116

117
```javascript
118
const validate = require("validate-npm-package-name");
119

120
// Simple package names
121
validate("lodash");           // { validForNewPackages: true, validForOldPackages: true }
122
validate("express");          // { validForNewPackages: true, validForOldPackages: true }
123
validate("my-package");       // { validForNewPackages: true, validForOldPackages: true }
124
validate("under_score");      // { validForNewPackages: true, validForOldPackages: true }
125
validate("example.com");      // { validForNewPackages: true, validForOldPackages: true }
126
validate("123numeric");       // { validForNewPackages: true, validForOldPackages: true }
127

128
// Scoped package names
129
validate("@babel/core");      // { validForNewPackages: true, validForOldPackages: true }
130
validate("@types/node");      // { validForNewPackages: true, validForOldPackages: true }
131
validate("@my-org/utils");    // { validForNewPackages: true, validForOldPackages: true }
132
```
133

134
### Invalid Names
135

136
```javascript
137
// Names that were never valid
138
validate("");                 // { validForNewPackages: false, validForOldPackages: false, errors: ['name length must be greater than zero'] }
139
validate(null);               // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot be null'] }
140
validate(undefined);          // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot be undefined'] }
141
validate(42);                 // { validForNewPackages: false, validForOldPackages: false, errors: ['name must be a string'] }
142
validate(".hidden");          // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot start with a period'] }
143
validate("_private");         // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot start with an underscore'] }
144
validate(" spaces ");         // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot contain leading or trailing spaces', 'name can only contain URL-friendly characters'] }
145
validate("node_modules");     // { validForNewPackages: false, validForOldPackages: false, errors: ['node_modules is not a valid package name'] }
146
validate("favicon.ico");      // { validForNewPackages: false, validForOldPackages: false, errors: ['favicon.ico is not a valid package name'] }
147
```
148

149
### Legacy Names (Warnings)
150

151
```javascript
152
// Names valid under old rules but not new ones
153
validate("UPPERCASE");        // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain capital letters'] }
154
validate("crazy!");           // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain special characters ("~\'!()*")'] }
155
validate("http");             // { validForNewPackages: false, validForOldPackages: true, warnings: ['http is a core module name'] }
156

157
// Very long names (214+ characters)
158
const longName = "a".repeat(215);
159
validate(longName);           // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain more than 214 characters'] }
160
```
161

162
### Scoped Package Validation
163

164
```javascript
165
// Valid scoped packages
166
validate("@user/package");     // { validForNewPackages: true, validForOldPackages: true }
167
validate("@org/my-lib");       // { validForNewPackages: true, validForOldPackages: true }
168

169
// Scoped packages with legacy warnings
170
validate("@user/CAPS");        // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain capital letters'] }
171
validate("@user/special!");    // { validForNewPackages: false, validForOldPackages: true, warnings: ['name can no longer contain special characters ("~\'!()*")'] }
172

173
// Scoped packages with errors
174
validate("@user/.dotfile");    // { validForNewPackages: false, validForOldPackages: false, errors: ['name cannot start with a period'] }
175

176
// Note: Scoped packages have relaxed rules - they can contain core module names
177
validate("@user/http");        // { validForNewPackages: true, validForOldPackages: true }
178
validate("@user/node_modules"); // { validForNewPackages: true, validForOldPackages: true }
179
```