tessl/npm-patch-package

Fix broken node modules with no fuss - create and apply patches to npm dependencies instantly

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-patch-package
Author: tessl

Complete command-line interface for creating and applying patches to npm dependencies. The CLI supports both interactive development workflows and automated CI/CD environments with comprehensive error handling and flexible configuration options.

Capabilities

Main Command

The primary patch-package command with multiple operation modes.

# Patch application mode (default)
patch-package [options]

# Patch creation mode
patch-package <package-name> [package-name...] [options]

# Rebase mode
patch-package --rebase <target> <package-name>

# Help and version
patch-package --help
patch-package --version

Patch Application Options

Options for applying existing patches during package installation.

--patch-dir <dirname>        # Specify patch directory (default: "patches")
--error-on-fail              # Exit with code 1 on failure (auto-enabled in CI)
--error-on-warn              # Exit with code 1 on warnings
--reverse                    # Un-apply all patches
--partial                    # Best-effort patch application, continue on failures

Usage Examples:

# Apply patches from custom directory
patch-package --patch-dir=custom-patches

# Apply patches with strict error handling
patch-package --error-on-fail --error-on-warn

# Reverse all applied patches
patch-package --reverse

# Apply patches with best-effort mode (continue on failures)
patch-package --partial

Patch Creation Options

Options for creating new patch files from modified node_modules.

--create-issue               # Open GitHub issue creation link
--use-yarn                   # Force use of yarn package manager
--include <regexp>           # Include paths matching regexp (default: .*)
--exclude <regexp>           # Exclude paths matching regexp (default: ^package\.json$)
--case-sensitive-path-filtering  # Make path filters case-sensitive
--append [name]              # Append new patch to sequence (name is optional)

Usage Examples:

# Create patch for single package
patch-package react

# Create patches for multiple packages
patch-package react react-dom lodash

# Create patch with custom include/exclude patterns
patch-package lodash --include="src/.*" --exclude="test/.*"

# Create patch and open GitHub issue
patch-package broken-package --create-issue

# Append to existing patch sequence
patch-package some-package --append="fix-critical-bug"

# Force yarn usage even in npm project
patch-package some-package --use-yarn

Rebase Operations

Advanced functionality for rebasing patch sequences to different targets.

--rebase <target> <package-name>    # Rebase patches to target patch file/number

Usage Examples:

# Rebase to specific patch file
patch-package --rebase patches/lodash+4.17.20.patch lodash

# Rebase to patch sequence number
patch-package --rebase 3 lodash

# Rebase to sequence name
patch-package --rebase security-fix lodash

# Rebase to beginning (un-apply all patches)
patch-package --rebase 0 lodash

Rebase Workflow:

When rebasing, patch-package will:

Un-apply all patches after the target
Put the package in "rebasing" state
Allow you to make changes
Use normal patch creation commands to continue

During Rebase:

# Update the current target patch
patch-package my-package

# Add new patch after target
patch-package my-package --append="new-feature"

Help and Version

--help, -h                   # Show help information
--version, -v                # Show version number

Command Behavior

Automatic Mode Detection

patch-package automatically detects the intended operation mode:

Application Mode: When no package names are provided, applies existing patches
Creation Mode: When package names are provided, creates new patches
Rebase Mode: When --rebase flag is used with target and package name

CI Environment Detection

The CLI automatically detects CI environments and adjusts behavior:

Enables --error-on-fail by default in CI environments
Provides appropriate exit codes for build system integration
Reduces interactive prompts in favor of explicit configuration

Package Manager Integration

Automatically detects and works with:

npm: Uses package-lock.json for resolution
yarn v1: Uses yarn.lock for resolution
npm-shrinkwrap: Uses npm-shrinkwrap.json for resolution

Can be overridden with --use-yarn flag when needed.

Error Handling

Comprehensive error handling with configurable exit behavior:

Default: Logs errors but continues execution
Strict Mode: --error-on-fail exits on any patch failure
Warning Mode: --error-on-warn exits on warnings
Best Effort: --partial continues even when individual patches fail

File Filtering

Advanced file filtering capabilities for patch creation:

Include Patterns: --include regexp to specify which files to patch
Exclude Patterns: --exclude regexp to specify which files to ignore
Case Sensitivity: --case-sensitive-path-filtering for precise control
Default Behavior: Includes all files except package.json

Filtering Examples:

# Only patch TypeScript files
patch-package my-lib --include=".*\.ts$"

# Exclude test and documentation files
patch-package my-lib --exclude="(test|docs|spec)/.*"

# Case-sensitive filtering
patch-package my-lib --include="src/.*" --case-sensitive-path-filtering

Patch Sequences

Support for sequential patches on the same package:

Overwrite Mode: Default behavior replaces existing patches
Append Mode: --append adds to existing patch sequence
Named Sequences: Optional names for patch sequences
Automatic Numbering: Sequential numbering for patch order

Sequence Examples:

# Create first patch
patch-package my-package

# Append additional patch with name
patch-package my-package --append="security-fix"

# Append patch without name (auto-numbered)
patch-package my-package --append

# Append another patch to sequence
patch-package my-package --append="performance-improvement"

This creates a sequence like: