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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

patch-package

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

patch-package lets app authors instantly make and keep fixes to npm dependencies. It's a vital band-aid for those of us living on the bleeding edge, enabling developers to create patches for broken node modules without waiting for upstream fixes.

Package Information

Package Name: patch-package
Package Type: npm
Language: TypeScript
Installation: npm install patch-package or yarn add patch-package postinstall-postinstall

Core Imports

// CLI usage - primary interface
npx patch-package some-package

// Programmatic usage - main functions
import { makePatch } from "patch-package/dist/makePatch";
import { applyPatchesForApp } from "patch-package/dist/applyPatches";
import { detectPackageManager } from "patch-package/dist/detectPackageManager";

For CommonJS:

const { makePatch } = require("patch-package/dist/makePatch");
const { applyPatchesForApp } = require("patch-package/dist/applyPatches");

Basic Usage

CLI Workflow

# 1. Edit a broken file in node_modules
vim node_modules/some-package/brokenFile.js

# 2. Generate a patch file
npx patch-package some-package

# 3. Commit the patch to version control
git add patches/some-package+3.14.15.patch
git commit -m "fix brokenFile.js in some-package"

# 4. Add postinstall hook to package.json
# "scripts": { "postinstall": "patch-package" }

Programmatic Usage

import { makePatch } from "patch-package/dist/makePatch";
import { applyPatchesForApp } from "patch-package/dist/applyPatches";
import { detectPackageManager } from "patch-package/dist/detectPackageManager";

// Create a patch programmatically
makePatch({
  packagePathSpecifier: "lodash",
  appPath: process.cwd(),
  packageManager: detectPackageManager(process.cwd(), null),
  includePaths: /.*/,
  excludePaths: /^package\.json$/,
  patchDir: "patches",
  createIssue: false,
  mode: { type: "overwrite_last" }
});

// Apply patches programmatically
applyPatchesForApp({
  appPath: process.cwd(),
  reverse: false,
  patchDir: "patches",
  shouldExitWithError: false,
  shouldExitWithWarning: false,
  bestEffort: false
});

Architecture

patch-package is built around several key components:

CLI Interface: Command-line tool with comprehensive argument handling for both patch creation and application
Patch Creation Engine: Generates patch files from modifications made to node_modules using git diff
Patch Application Engine: Applies patches automatically during package installation via postinstall hooks
Package Manager Integration: Supports npm, yarn, and npm-shrinkwrap with lockfile analysis
State Management: Tracks applied patches and handles sequencing, rebasing, and validation
File System Operations: Cross-platform path handling and file manipulation utilities

Capabilities

CLI Interface

Complete command-line interface for creating and applying patches to npm dependencies. Supports both interactive and CI/CD workflows with comprehensive error handling.

// Main CLI entry point
// Usage: patch-package [package-name...] [options]

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

CLI Interface

Patch Creation

Core functionality for creating patch files from modified node_modules. Generates diffs, handles file filtering, and supports patch sequences.

function makePatch(options: MakePatchOptions): void;

interface MakePatchOptions {
  packagePathSpecifier: string;
  appPath: string;
  packageManager: PackageManager;
  includePaths: RegExp;
  excludePaths: RegExp;
  patchDir: string;
  createIssue: boolean;
  mode: PatchMode;
}

type PatchMode = 
  | { type: "overwrite_last" }
  | { type: "append", name?: string };

Patch Creation

Patch Application

Robust patch application system that applies patches during package installation with support for error handling, partial application, and reverse operations.

function applyPatchesForApp(options: ApplyPatchesForAppOptions): void;

interface ApplyPatchesForAppOptions {
  appPath: string;
  reverse: boolean;
  patchDir: string;
  shouldExitWithError: boolean;
  shouldExitWithWarning: boolean;
  bestEffort: boolean;
}

function applyPatch(options: ApplyPatchOptions): boolean;

Patch Application

Patch Rebasing

Advanced patch sequence management for reordering, editing, and managing complex patch workflows. Enables developers to modify patch history and insert changes at specific points.

function rebase(options: RebaseOptions): void;

interface RebaseOptions {
  appPath: string;
  patchDir: string;
  packagePathSpecifier: string;
  targetPatch: string;
}

Rebase operations support multiple target types:

Patch file names (e.g., "lodash+4.17.21.patch")
Sequence numbers (e.g., "3")
Sequence names (e.g., "security-fix")
Reset to beginning (use "0")

Rebase Operations

Package Management Integration

Package manager detection, version resolution, and lockfile integration for npm, yarn, and npm-shrinkwrap environments.

type PackageManager = "yarn" | "npm" | "npm-shrinkwrap";

function detectPackageManager(
  appRootPath: string, 
  overridePackageManager: PackageManager | null
): PackageManager;

function getPackageResolution(options: PackageResolutionOptions): string;

Package Management

Utility APIs

Supporting utilities for path handling, file operations, state management, and type definitions used throughout the patch-package ecosystem.

interface PackageDetails {
  humanReadablePathSpecifier: string;
  pathSpecifier: string;
  path: string;
  name: string;
  isNested: boolean;
  packageNames: string[];
}

interface PatchedPackageDetails extends PackageDetails {
  version: string;
  patchFilename: string;
  isDevOnly: boolean;
  sequenceName?: string;
  sequenceNumber?: number;
}

Utility APIs