0
# NP - A Better NPM Publish
1

2
NP is an enhanced npm publishing tool that automates and improves the entire package publishing workflow. It provides an interactive CLI that ensures proper release management with version bumping, automated testing, git integration, and comprehensive validation.
3

4
## Package Information
5

6
- **Package Name**: np
7
- **Package Type**: npm (CLI tool)
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install --global np`
10

11
## Core Imports
12

13
For programmatic usage:
14

15
```javascript
16
import np from "np";
17
```
18

19
CommonJS:
20

21
```javascript
22
const np = require("np");
23
```
24

25
## Basic Usage
26

27
### CLI Usage
28

29
```bash
30
# Interactive release with patch version bump
31
np
32

33
# Specify version increment
34
np minor
35

36
# Specific version
37
np 1.2.3
38

39
# Preview mode (dry run)
40
np --preview
41

42
# Skip tests and cleanup (not recommended)
43
np --yolo
44
```
45

46
### Programmatic Usage
47

48
```javascript
49
import np from "np";
50
import { readPackage } from "np/source/util.js";
51

52
// Read package information first
53
const { package_, rootDirectory } = await readPackage();
54

55
// Basic usage with default options
56
const newPackage = await np("patch", {
57
  cleanup: true,
58
  tests: true,
59
  publish: true,
60
  preview: false
61
}, {
62
  package_,
63
  rootDirectory
64
});
65

66
console.log(`Published ${newPackage.name}@${newPackage.version}`);
67
```
68

69
## Architecture
70

71
NP is built around several key components:
72

73
- **Core Workflow**: Main `np` function orchestrates the complete publishing pipeline
74
- **Task System**: Modular task execution using Listr with prerequisite validation, git operations, and publishing steps
75
- **Package Manager Support**: Abstraction layer supporting npm, Yarn (Classic/Berry), pnpm, and Bun
76
- **Git Integration**: Comprehensive git operations for branch validation, tagging, and pushing
77
- **NPM Operations**: Registry interactions, publishing, and 2FA management
78
- **Interactive UI**: User prompts and confirmations for safe publishing
79
- **Configuration System**: Flexible configuration from files and CLI options
80

81
## Capabilities
82

83
### Core Publishing Workflow
84

85
The main publishing function that orchestrates version bumping, testing, publishing, and git operations.
86

87
```javascript { .api }
88
/**
89
 * Main publishing function that handles the complete npm publishing workflow
90
 * @param input - Version increment ('patch'|'minor'|'major'|'prerelease'|'prepatch'|'preminor'|'premajor') or specific version string (default: 'patch')
91
 * @param options - Publishing configuration options (packageManager will be extracted separately)
92
 * @param context - Package metadata and root directory context
93
 * @returns Promise resolving to updated package.json data
94
 */
95
function np(
96
  input?: string,
97
  options?: Options & {packageManager?: PackageManagerConfig},
98
  context?: {
99
    package_: NormalizedPackageJson;
100
    rootDirectory: string;
101
  }
102
): Promise<NormalizedPackageJson>;
103
```
104

105
[Core Publishing](./core-publishing.md)
106

107
### Version Management
108

109
Advanced semver version handling with validation, formatting, and increment operations.
110

111
```javascript { .api }
112
class Version {
113
  constructor(version: string, increment?: string, options?: object);
114
  setFrom(input: string, options?: object): void;
115
  format(options?: object): string;
116
  satisfies(range: string): boolean;
117
  isPrerelease(): boolean;
118
  toString(): string;
119
}
120

121
const SEMVER_INCREMENTS: string[];
122
```
123

124
[Version Management](./version-management.md)
125

126
### Git Operations
127

128
Comprehensive git integration for branch validation, tagging, history management, and pushing.
129

130
```javascript { .api }
131
// Git information
132
function latestTag(): Promise<string>;
133
function getCurrentBranch(): Promise<string>;
134
function defaultBranch(): Promise<string>;
135
function hasUpstream(): Promise<boolean>;
136

137
// Git validation
138
function verifyWorkingTreeIsClean(): Promise<void>;
139
function verifyCurrentBranchIsReleaseBranch(releaseBranch: string): Promise<void>;
140
function verifyRemoteHistoryIsClean(): Promise<void>;
141
```
142

143
[Git Operations](./git-operations.md)
144

145
### NPM Registry Operations
146

147
NPM registry interactions including package validation, publishing, and 2FA management.
148

149
```javascript { .api }
150
// NPM information
151
function version(): Promise<string>;
152
function username(options: {externalRegistry?: boolean}): Promise<string>;
153
function isPackageNameAvailable(package_: object): Promise<{isAvailable: boolean; isUnknown: boolean}>;
154

155
// Publishing
156
function getPackagePublishArguments(options: Options): string[];
157
function runPublish(arguments_: string[]): ChildProcess;
158
```
159

160
[NPM Operations](./npm-operations.md)
161

162
### Package Manager Support
163

164
Multi-package-manager abstraction supporting npm, Yarn, pnpm, and Bun with unified configuration.
165

166
```javascript { .api }
167
interface PackageManagerConfig {
168
  id: string;
169
  cli: string;
170
  installCommand: [string, string[]];
171
  installCommandNoLockfile: [string, string[]];
172
  versionCommand(input: string): [string, string[]];
173
  publishCommand?(args: string[]): [string, string[]];
174
  throwOnExternalRegistry?: boolean;
175
}
176

177
function getPackageManagerConfig(rootDirectory: string, package_: object): PackageManagerConfig;
178
function findLockfile(rootDirectory: string, config: PackageManagerConfig): string | undefined;
179
```
180

181
[Package Manager Support](./package-manager.md)
182

183
### Configuration Management
184

185
Flexible configuration system supporting file-based and CLI-based options.
186

187
```javascript { .api }
188
/**
189
 * Load np configuration from config files
190
 * @param rootDirectory - Project root directory
191
 * @returns Promise resolving to configuration object
192
 */
193
function getConfig(rootDirectory: string): Promise<object>;
194
```
195

196
[Configuration](./configuration.md)
197

198
### Utilities and Helpers
199

200
General utility functions for package analysis, file operations, and display formatting.
201

202
```javascript { .api }
203
// Package utilities
204
function readPackage(packagePath?: string): Promise<{package_: object; rootDirectory: string}>;
205
function getNewFiles(rootDirectory: string): Promise<string[]>;
206
function getNewDependencies(newPackage: object, rootDirectory: string): Promise<string[]>;
207

208
// Display utilities
209
function linkifyIssues(url: string, message: string): string;
210
function linkifyCommit(url: string, commit: string): string;
211
function joinList(list: string[]): string;
212
```
213

214
[Utilities](./utilities.md)
215

216
### Task System
217

218
Internal task modules for the publishing workflow execution.
219

220
```javascript { .api }
221
/**
222
 * Pre-publish validation tasks
223
 * @param input - Version input
224
 * @param package_ - Package object
225
 * @param options - Publishing options
226
 * @param packageManager - Package manager configuration
227
 * @returns Listr task list
228
 */
229
function prerequisiteTasks(input: string, package_: object, options: Options, packageManager: object): object;
230

231
/**
232
 * Git workflow tasks
233
 * @param options - Publishing options
234
 * @returns Listr task list
235
 */
236
function gitTasks(options: Options): object;
237

238
/**
239
 * GitHub release draft creation
240
 * @param options - Publishing options
241
 * @param package_ - Package object
242
 * @param packageManager - Package manager configuration
243
 * @returns Promise resolving when release draft is created
244
 */
245
function releaseTaskHelper(options: Options, package_: object, packageManager: object): Promise<void>;
246

247
/**
248
 * Interactive UI and prompts
249
 * @param options - Initial options
250
 * @param context - Package context
251
 * @returns Promise resolving to final confirmed options
252
 */
253
function ui(options: Options, context: {package_: object; rootDirectory: string}): Promise<Options>;
254
```
255

256
## Options Interface
257

258
```javascript { .api }
259
interface Options {
260
  // Version and publishing
261
  version?: string;           // Version increment or specific version
262
  tag?: string;              // npm dist-tag
263
  contents?: string;         // Subdirectory to publish
264
  message?: string;          // Version bump commit message
265
  
266
  // Branch and git options  
267
  anyBranch?: boolean;       // Allow publishing from any branch
268
  branch?: string;           // Release branch name
269
  
270
  // Process control
271
  cleanup?: boolean;         // Clean node_modules before publish (default: true)
272
  tests?: boolean;           // Run tests before publish (default: true)
273
  yolo?: boolean;           // Skip cleanup and tests
274
  publish?: boolean;         // Actually publish to npm (default: true)
275
  preview?: boolean;         // Show tasks without executing
276
  
277
  // Release options
278
  releaseDraft?: boolean;        // Create GitHub release draft (default: true)
279
  releaseDraftOnly?: boolean;    // Only create release draft
280
  
281
  // Security and access
282
  '2fa'?: boolean;               // Enable 2FA on new packages (default: true)
283
  
284
  // Package manager
285
  packageManager?: string;       // Force specific package manager
286
  testScript?: string;          // Custom test script name (default: 'test')
287
  
288
  // Internal computed properties (set by np)
289
  runPublish?: boolean;         // Whether to actually publish
290
  availability?: {              // Package name availability
291
    isAvailable: boolean;
292
    isUnknown: boolean;
293
  };
294
  repoUrl?: string;            // Repository URL
295
  releaseNotes?: (tag: string) => string; // Release notes generator
296
  confirm?: boolean;           // User confirmation
297
}
298
```
299

300
## Types
301

302
```javascript { .api }
303
// Main types used across the API
304
interface NormalizedPackageJson {
305
  name: string;
306
  version: string;
307
  private?: boolean;
308
  packageManager?: string;
309
  [key: string]: any;
310
}
311

312
interface ValidationError {
313
  path: string;
314
  message: string;
315
  value: any;
316
}
317

318
interface GitPushResult {
319
  reason?: string;
320
  [key: string]: any;
321
}
322

323
interface ChildProcess {
324
  stdout: ReadableStream;
325
  stderr: ReadableStream;
326
  kill(): void;
327
  [key: string]: any;
328
}
329

330
type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun';
331
type SemverIncrement = 'patch' | 'minor' | 'major' | 'prepatch' | 'preminor' | 'premajor' | 'prerelease';
332
type ColorName = string; // Chalk color name or modifier name
333

334
interface PackageManagerConfig {
335
  id: string;
336
  cli: string;
337
  installCommand: [string, string[]];
338
  installCommandNoLockfile: [string, string[]];
339
  versionCommand(input: string): [string, string[]];
340
  publishCommand?(args: string[]): [string, string[]];
341
  throwOnExternalRegistry?: boolean;
342
}
343
```