0
# npm Publishing
1

2
The npm plugin provides comprehensive npm package publishing functionality including registry validation, authentication checks, collaborator verification, and publishing with 2FA support.
3

4
## Capabilities
5

6
### npm Plugin Class
7

8
Main npm publishing plugin for package registry operations.
9

10
```javascript { .api }
11
/**
12
 * npm publishing plugin for package registry operations
13
 * Handles authentication, validation, and publishing to npm registry
14
 */
15
class npm extends Plugin {
16
  /**
17
   * Check if npm plugin should be enabled
18
   * @param options - npm plugin options
19
   * @returns Boolean indicating if package.json exists and npm is not disabled
20
   */
21
  static isEnabled(options: any): boolean;
22
  
23
  /** Initialize npm plugin with registry validation and authentication */
24
  init(): Promise<void>;
25
  
26
  /** Get package name from package.json */
27
  getName(): string;
28
  
29
  /** Get latest version from package.json (unless ignoreVersion is true) */
30
  getLatestVersion(): string | null;
31
  
32
  /**
33
   * Bump package version using npm version command
34
   * @param version - New version to bump to
35
   * @returns Promise resolving to boolean indicating success
36
   */
37
  bump(version: string): Promise<boolean>;
38
  
39
  /**
40
   * Publish package to npm registry
41
   * @returns Promise resolving to boolean indicating success
42
   */
43
  release(): Promise<boolean>;
44
  
45
  /** Log package URL after successful release */
46
  afterRelease(): void;
47
  
48
  /** Registry connectivity and authentication */
49
  isRegistryUp(): Promise<boolean>;
50
  isAuthenticated(): Promise<boolean>;
51
  isCollaborator(): Promise<boolean>;
52
  
53
  /** Version and registry information */
54
  getLatestRegistryVersion(): Promise<string | null>;
55
  getRegistryPreReleaseTags(): Promise<string[]>;
56
  resolveTag(version: string): Promise<string>;
57
  guessPreReleaseTag(): Promise<string>;
58
  
59
  /** Registry and package information */
60
  getRegistry(): string | undefined;
61
  getPublicPath(): string;
62
  getPackageUrl(): string;
63
  
64
  /** Publishing operations */
65
  publish(options?: PublishOptions): Promise<boolean | void>;
66
}
67
```
68

69
### Registry Operations
70

71
Methods for interacting with npm registry and validating connectivity.
72

73
```javascript { .api }
74
/**
75
 * Check if npm registry is accessible
76
 * @returns Promise resolving to boolean indicating registry availability
77
 */
78
isRegistryUp(): Promise<boolean>;
79

80
/**
81
 * Check if user is authenticated with npm registry
82
 * @returns Promise resolving to boolean indicating authentication status
83
 */
84
isAuthenticated(): Promise<boolean>;
85

86
/**
87
 * Check if authenticated user is a collaborator for the package
88
 * @returns Promise resolving to boolean indicating collaborator status
89
 */
90
isCollaborator(): Promise<boolean>;
91

92
/**
93
 * Get latest version of package from npm registry
94
 * @returns Promise resolving to version string or null if not found
95
 */
96
getLatestRegistryVersion(): Promise<string | null>;
97

98
/**
99
 * Get pre-release tags from npm registry
100
 * @returns Promise resolving to array of pre-release tag names
101
 */
102
getRegistryPreReleaseTags(): Promise<string[]>;
103

104
/**
105
 * Get npm registry URL for this package
106
 * @returns Registry URL string
107
 */
108
getRegistry(): string;
109

110
/**
111
 * Get public path for package URL
112
 * @returns Public path string
113
 */
114
getPublicPath(): string;
115

116
/**
117
 * Get full package URL on npm registry
118
 * @returns Complete package URL
119
 */
120
getPackageUrl(): string;
121
```
122

123
### Version and Tag Management
124

125
Methods for handling version bumping and npm tag resolution.
126

127
```javascript { .api }
128
/**
129
 * Resolve npm tag for given version
130
 * @param version - Version string to resolve tag for
131
 * @returns Promise resolving to npm tag (latest, next, etc.)
132
 */
133
resolveTag(version: string): Promise<string>;
134

135
/**
136
 * Guess pre-release tag from registry or use default
137
 * @returns Promise resolving to pre-release tag name
138
 */
139
guessPreReleaseTag(): Promise<string>;
140
```
141

142
### Publishing Operations
143

144
Methods for publishing packages to npm registry with 2FA support.
145

146
```javascript { .api }
147
/**
148
 * Publish package to npm registry
149
 * @param options - Publishing options
150
 * @returns Promise that resolves when publishing completes
151
 */
152
publish(options?: PublishOptions): Promise<void>;
153

154
interface PublishOptions {
155
  /** One-time password for 2FA authentication */
156
  otp?: string;
157
  /** Callback function for OTP prompt when 2FA is required */
158
  otpCallback?: (callback: (otp: string) => Promise<void>) => Promise<void>;
159
}
160
```
161

162
### npm Configuration Options
163

164
Complete configuration options for the npm plugin.
165

166
```javascript { .api }
167
interface NpmOptions {
168
  /** Enable/disable npm plugin entirely */
169
  disabled?: boolean;
170
  
171
  /** Skip registry connectivity and authentication checks */
172
  skipChecks?: boolean;
173
  
174
  /** Ignore version in package.json and don't update it */
175
  ignoreVersion?: boolean;
176
  
177
  /** Enable/disable publishing to npm registry */
178
  publish?: boolean;
179
  
180
  /** npm tag to use for published version (default: "latest" or "next" for prereleases) */
181
  tag?: string;
182
  
183
  /** One-time password for 2FA authentication */
184
  otp?: string;
185
  
186
  /** Registry connection timeout in seconds (default: 10) */
187
  timeout?: number;
188
  
189
  /** Additional arguments for npm version command */
190
  versionArgs?: string[];
191
  
192
  /** Allow npm version to set same version (useful for rebuilds) */
193
  allowSameVersion?: boolean;
194
  
195
  /** Path/directory to publish (default: current directory) */
196
  publishPath?: string;
197
  
198
  /** Additional arguments for npm publish command */
199
  publishArgs?: string[];
200
  
201
  /** Custom npm registry URL (overrides package.json publishConfig) */
202
  registry?: string;
203
}
204
```
205

206
### Package Configuration Support
207

208
The npm plugin respects package.json configuration:
209

210
```javascript { .api }
211
interface PackageJson {
212
  /** Package name */
213
  name: string;
214
  /** Current version */
215
  version: string;
216
  /** Private package flag (prevents publishing) */
217
  private?: boolean;
218
  /** Publishing configuration */
219
  publishConfig?: {
220
    /** Custom registry URL */
221
    registry?: string;
222
    /** Custom public path for package URL */
223
    publicPath?: string;
224
    /** Scoped registry configurations */
225
    [key: string]: any;
226
  };
227
}
228
```
229

230
**Usage Examples:**
231

232
```javascript
233
// Basic npm publishing configuration
234
const result = await runTasks({
235
  npm: {
236
    publish: true,
237
    skipChecks: false
238
  }
239
});
240

241
// Advanced npm configuration with custom registry
242
const result = await runTasks({
243
  npm: {
244
    publish: true,
245
    registry: "https://npm.internal.company.com",
246
    tag: "beta",
247
    timeout: 30,
248
    publishArgs: ["--access", "public"],
249
    versionArgs: ["--no-git-tag-version"]
250
  }
251
});
252

253
// npm configuration for pre-release workflow
254
const result = await runTasks({
255
  increment: "prerelease",
256
  npm: {
257
    publish: true,
258
    tag: "next",                    // Use 'next' tag for prereleases
259
    allowSameVersion: true          // Allow republishing same version
260
  }
261
});
262

263
// Skip npm publishing but still bump version
264
const result = await runTasks({
265
  npm: {
266
    publish: false,                 // Don't publish to registry
267
    skipChecks: true               // Skip registry validation
268
  }
269
});
270

271
// Handle 2FA authentication programmatically
272
const result = await runTasks({
273
  npm: {
274
    publish: true,
275
    otp: "123456"                  // Provide OTP directly
276
  }
277
});
278
```
279

280
### Registry Validation
281

282
The npm plugin performs several validation checks during initialization:
283

284
1. **Registry Connectivity**: Verifies npm registry is accessible
285
2. **Authentication**: Confirms user is logged in (`npm whoami`)
286
3. **Collaborator Status**: Validates user has write permissions
287
4. **Version Consistency**: Compares package.json version with registry
288

289
These checks can be skipped with `skipChecks: true` for faster execution or offline scenarios.
290

291
### 2FA Support
292

293
The npm plugin provides comprehensive Two-Factor Authentication support:
294

295
- **Automatic Detection**: Recognizes 2FA requirement from publish errors
296
- **OTP Prompting**: Interactive prompt for OTP when needed
297
- **Programmatic OTP**: Accept OTP via configuration or callback
298
- **Error Recovery**: Retry publishing with correct OTP
299

300
### Pre-release Handling
301

302
The npm plugin intelligently handles pre-release versions:
303

304
- **Tag Resolution**: Automatically uses "next" tag for prereleases
305
- **Registry Tags**: Discovers existing pre-release tags from registry
306
- **Custom Tags**: Supports custom pre-release tag configuration
307
- **Version Parsing**: Extracts pre-release identifiers from version strings
308

309
### Private Package Support
310

311
Private packages are automatically detected and handled:
312

313
```json
314
{
315
  "name": "@company/private-package",
316
  "private": true,
317
  "publishConfig": {
318
    "registry": "https://npm.internal.company.com"
319
  }
320
}
321
```
322

323
The plugin will:
324
- Skip publishing if `private: true` is set
325
- Use custom registry from `publishConfig`
326
- Handle scoped package authentication
327
- Support organization-specific configurations
328

329
### Error Handling
330

331
The npm plugin includes robust error handling for:
332

333
- **Network Issues**: Timeout and retry logic for registry operations
334
- **Authentication Failures**: Clear error messages for login issues
335
- **Permission Errors**: Detailed feedback for collaborator access issues
336
- **2FA Errors**: Automatic OTP retry with user feedback
337
- **Version Conflicts**: Detection and reporting of version mismatches