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
```