Core Publishing Workflow

The core publishing functionality that orchestrates the complete npm publishing pipeline with automated version bumping, testing, git operations, and registry publishing.

Capabilities

Main Publishing Function

The primary entry point for all publishing operations, handling the complete workflow from validation to publication.

/**
 * Main publishing function that handles the complete npm publishing workflow
 * @param input - Version increment ('patch'|'minor'|'major'|'prerelease'|'prepatch'|'preminor'|'premajor') or specific version string (default: 'patch')
 * @param options - Publishing configuration options
 * @param context - Package metadata and root directory context
 * @returns Promise resolving to updated package.json data
 */
function np(
  input?: string,
  options?: Options,
  context?: {
    package_: NormalizedPackageJson;
    rootDirectory: string;
  }
): Promise<NormalizedPackageJson>;

Usage Examples:

import np from "np";

// Basic patch release
const result = await np("patch", {
  cleanup: true,
  tests: true,
  publish: true
}, {
  package_: require('./package.json'),
  rootDirectory: process.cwd()
});

// Prerelease with custom tag
const prerelease = await np("prerelease", {
  tag: "beta",
  message: "Beta release v%s",
  releaseDraft: false
}, context);

// Preview mode (dry run)
const preview = await np("minor", {
  preview: true,
  packageManager: "pnpm"
}, context);

// Skip tests and cleanup (YOLO mode)
const quick = await np("patch", {
  yolo: true,
  publish: true
}, context);

CLI Implementation

CLI implementation with argument parsing and interactive prompts.

/**
 * Get parsed CLI options and configuration
 * @returns Promise resolving to options, package context, and root directory
 */
function getOptions(): Promise<{
  options: Options;
  rootDirectory: string;
  package_: NormalizedPackageJson;
}>;

Task Execution Pipeline

The publishing workflow consists of sequential tasks executed using Listr:

1. Prerequisite Check - Validate environment and requirements
2. Git Operations - Branch validation, clean working tree verification
3. Cleanup - Optional node_modules cleanup
4. Dependencies - Reinstall dependencies if cleanup enabled
5. Testing - Run test suite if enabled
6. Version Bump - Update package version and create git tag
7. Publishing - Publish to npm registry
8. 2FA Setup - Enable 2FA on new packages if enabled
9. Git Push - Push commits and tags to remote
10. Release Draft - Create GitHub release draft if enabled

Error Handling and Rollback

Automatic rollback functionality in case of publishing failures.

/**
 * Rollback function that reverts changes on publish failure
 * Removes the latest git tag and commit if version was bumped
 */
const rollback: () => Promise<void>;

Rollback Process:

• Detects if package version was bumped
• Removes the latest git tag
• Removes the latest commit
• Provides status feedback

Preview Mode

Dry-run functionality that shows what commands would be executed without making changes.

interface PreviewOptions extends Options {
  preview: true;
}

Preview Features:

• Shows all commands that would be executed
• Validates configuration without making changes
• Displays version bump without committing
• Shows publish command without uploading
• Previews git operations without pushing

Release Draft Only Mode

Mode for creating GitHub release drafts for already published versions.

interface ReleaseDraftOptions extends Options {
  releaseDraftOnly: true;
}

Publishing Workflow Details

Version Input Handling

The input parameter accepts:

• Semver increments: patch, minor, major, prepatch, preminor, premajor, prerelease
• Specific versions: 1.2.3, 2.0.0-beta.1, 1.0.0-alpha.2
• Default: patch if no input provided

Context Requirements

The context parameter must provide:

interface PublishContext {
  package_: NormalizedPackageJson;  // Parsed package.json
  rootDirectory: string;           // Absolute path to project root
}

Options Processing

Options are merged from multiple sources in priority order:

1. CLI flags (highest priority)
2. Configuration files (.np-config.json, .np-config.js, etc.)
3. Default values (lowest priority)

Private Package Handling

Private packages (with "private": true in package.json) are handled specially:

• Publishing to npm is automatically disabled
• Version bumping and git operations still proceed
• Release drafts can still be created
• All other validation steps are performed

External Registry Support

Limited support for external npm registries:

• Some package managers throw errors with external registries
• 2FA setup is disabled for external registries
• Package name availability checks may not work
• Publishing commands are adjusted for registry URL

Error Conditions

Common error scenarios and their handling:

Publishing Errors

• Network failures: Automatic retry with OTP prompt for 2FA
• Permission errors: Clear error messages with suggestions
• Registry errors: Detailed npm error output with context
• Validation failures: Early exit with specific validation messages

Git Errors

• Dirty working tree: Clear error with uncommitted changes list
• Remote out of sync: Automatic fetch with conflict resolution guidance
• No upstream: Warning with option to skip push
• Tag conflicts: Validation against remote tags before creation

Environment Errors

• Missing dependencies: Clear requirements list (Node.js, npm, git versions)
• Package manager issues: Detection and switching guidance
• Permission issues: File system and registry permission guidance