0
# patch-package
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: patch-package
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install patch-package` or `yarn add patch-package postinstall-postinstall`
10

11
## Core Imports
12

13
```typescript
14
// CLI usage - primary interface
15
npx patch-package some-package
16

17
// Programmatic usage - main functions
18
import { makePatch } from "patch-package/dist/makePatch";
19
import { applyPatchesForApp } from "patch-package/dist/applyPatches";
20
import { detectPackageManager } from "patch-package/dist/detectPackageManager";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { makePatch } = require("patch-package/dist/makePatch");
27
const { applyPatchesForApp } = require("patch-package/dist/applyPatches");
28
```
29

30
## Basic Usage
31

32
### CLI Workflow
33

34
```bash
35
# 1. Edit a broken file in node_modules
36
vim node_modules/some-package/brokenFile.js
37

38
# 2. Generate a patch file
39
npx patch-package some-package
40

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

45
# 4. Add postinstall hook to package.json
46
# "scripts": { "postinstall": "patch-package" }
47
```
48

49
### Programmatic Usage
50

51
```typescript
52
import { makePatch } from "patch-package/dist/makePatch";
53
import { applyPatchesForApp } from "patch-package/dist/applyPatches";
54
import { detectPackageManager } from "patch-package/dist/detectPackageManager";
55

56
// Create a patch programmatically
57
makePatch({
58
  packagePathSpecifier: "lodash",
59
  appPath: process.cwd(),
60
  packageManager: detectPackageManager(process.cwd(), null),
61
  includePaths: /.*/,
62
  excludePaths: /^package\.json$/,
63
  patchDir: "patches",
64
  createIssue: false,
65
  mode: { type: "overwrite_last" }
66
});
67

68
// Apply patches programmatically
69
applyPatchesForApp({
70
  appPath: process.cwd(),
71
  reverse: false,
72
  patchDir: "patches",
73
  shouldExitWithError: false,
74
  shouldExitWithWarning: false,
75
  bestEffort: false
76
});
77
```
78

79
## Architecture
80

81
patch-package is built around several key components:
82

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

90
## Capabilities
91

92
### CLI Interface
93

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

96
```typescript { .api }
97
// Main CLI entry point
98
// Usage: patch-package [package-name...] [options]
99

100
// Patch application mode (default)
101
patch-package [options]
102

103
// Patch creation mode  
104
patch-package <package-name> [package-name...] [options]
105

106
// Rebase mode
107
patch-package --rebase <target> <package-name>
108
```
109

110
[CLI Interface](./cli-interface.md)
111

112
### Patch Creation
113

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

116
```typescript { .api }
117
function makePatch(options: MakePatchOptions): void;
118

119
interface MakePatchOptions {
120
  packagePathSpecifier: string;
121
  appPath: string;
122
  packageManager: PackageManager;
123
  includePaths: RegExp;
124
  excludePaths: RegExp;
125
  patchDir: string;
126
  createIssue: boolean;
127
  mode: PatchMode;
128
}
129

130
type PatchMode = 
131
  | { type: "overwrite_last" }
132
  | { type: "append", name?: string };
133
```
134

135
[Patch Creation](./patch-creation.md)
136

137
### Patch Application
138

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

141
```typescript { .api }
142
function applyPatchesForApp(options: ApplyPatchesForAppOptions): void;
143

144
interface ApplyPatchesForAppOptions {
145
  appPath: string;
146
  reverse: boolean;
147
  patchDir: string;
148
  shouldExitWithError: boolean;
149
  shouldExitWithWarning: boolean;
150
  bestEffort: boolean;
151
}
152

153
function applyPatch(options: ApplyPatchOptions): boolean;
154
```
155

156
[Patch Application](./patch-application.md)
157

158
### Patch Rebasing
159

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

162
```typescript { .api }
163
function rebase(options: RebaseOptions): void;
164

165
interface RebaseOptions {
166
  appPath: string;
167
  patchDir: string;
168
  packagePathSpecifier: string;
169
  targetPatch: string;
170
}
171
```
172

173
Rebase operations support multiple target types:
174
- Patch file names (e.g., `"lodash+4.17.21.patch"`)
175
- Sequence numbers (e.g., `"3"`)
176
- Sequence names (e.g., `"security-fix"`)
177
- Reset to beginning (use `"0"`)
178

179
[Rebase Operations](./rebase-operations.md)
180

181
### Package Management Integration
182

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

185
```typescript { .api }
186
type PackageManager = "yarn" | "npm" | "npm-shrinkwrap";
187

188
function detectPackageManager(
189
  appRootPath: string, 
190
  overridePackageManager: PackageManager | null
191
): PackageManager;
192

193
function getPackageResolution(options: PackageResolutionOptions): string;
194
```
195

196
[Package Management](./package-management.md)
197

198
### Utility APIs
199

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

202
```typescript { .api }
203
interface PackageDetails {
204
  humanReadablePathSpecifier: string;
205
  pathSpecifier: string;
206
  path: string;
207
  name: string;
208
  isNested: boolean;
209
  packageNames: string[];
210
}
211

212
interface PatchedPackageDetails extends PackageDetails {
213
  version: string;
214
  patchFilename: string;
215
  isDevOnly: boolean;
216
  sequenceName?: string;
217
  sequenceNumber?: number;
218
}
219
```
220

221
[Utility APIs](./utility-apis.md)