You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Patches created by `patch-package` are automatically and gracefully applied
21
-
when you use `npm`(>=5) or `yarn`.
20
+
Patches created by `patch-package` are automatically and gracefully applied when
21
+
you use `npm`(>=5) or `yarn`.
22
22
23
-
No more waiting around for pull requests to be merged and published.
24
-
No more forking repos just to fix that one tiny thing preventing your app from working.
23
+
No more waiting around for pull requests to be merged and published. No more
24
+
forking repos just to fix that one tiny thing preventing your app from working.
25
25
26
26
## Set-up
27
27
@@ -39,25 +39,32 @@ Then
39
39
40
40
npm i patch-package
41
41
42
-
You can use `--save-dev` if you don't need to run npm in production, e.g. if you're making a web frontend.
42
+
You can use `--save-dev` if you don't need to run npm in production, e.g. if
43
+
you're making a web frontend.
43
44
44
45
### yarn
45
46
46
47
yarn add patch-package postinstall-postinstall
47
48
48
-
You can use `--dev` if you don't need to run yarn in production, e.g. if you're making a web frontend.
49
+
You can use `--dev` if you don't need to run yarn in production, e.g. if you're
50
+
making a web frontend.
49
51
50
-
To understand why yarn needs the `postinstall-postinstall` package see: [Why use postinstall-postinstall](#why-use-postinstall-postinstall-with-yarn)
52
+
To understand why yarn needs the `postinstall-postinstall` package see:
53
+
[Why use postinstall-postinstall](#why-use-postinstall-postinstall-with-yarn)
51
54
52
55
### yarn workspaces
53
56
54
-
Same as for yarn ☝️ Note that if you want to patch un-hoisted packages you'll need to repeat the setup process for the child package. Also make sure you're in the child package directory when you run `patch-package` to generate the patch files.
57
+
Same as for yarn ☝️ Note that if you want to patch un-hoisted packages you'll
58
+
need to repeat the setup process for the child package. Also make sure you're in
59
+
the child package directory when you run `patch-package` to generate the patch
60
+
files.
55
61
56
62
## Usage
57
63
58
64
### Making patches
59
65
60
-
First make changes to the files of a particular package in your node_modules folder, then run
66
+
First make changes to the files of a particular package in your node_modules
67
+
folder, then run
61
68
62
69
yarn patch-package package-name
63
70
@@ -67,29 +74,31 @@ or use npx (included with `npm > 5.2`)
67
74
68
75
where `package-name` matches the name of the package you made changes to.
69
76
70
-
If this is the first time you've used `patch-package`, it will create a folder called `patches` in
71
-
the root dir of your app. Inside will be a file called `package-name+0.44.0.patch` or something,
72
-
which is a diff between normal old `package-name` and your fixed version. Commit this to share the fix with your team.
77
+
If this is the first time you've used `patch-package`, it will create a folder
78
+
called `patches` in the root dir of your app. Inside will be a file called
79
+
`package-name+0.44.0.patch` or something, which is a diff between normal old
80
+
`package-name` and your fixed version. Commit this to share the fix with your
81
+
team.
73
82
74
83
#### Options
75
84
76
85
-`--use-yarn`
77
86
78
-
By default, patch-package checks whether you use npm or yarn based on
79
-
which lockfile you have. If you have both, it uses npm by default.
80
-
Set this option to override that default and always use yarn.
87
+
By default, patch-package checks whether you use npm or yarn based on which
88
+
lockfile you have. If you have both, it uses npm by default. Set this option
89
+
to override that default and always use yarn.
81
90
82
91
-`--exclude <regexp>`
83
92
84
-
Ignore paths matching the regexp when creating patch files.
85
-
Paths are relative to the root dir of the package to be patched.
93
+
Ignore paths matching the regexp when creating patch files. Paths are relative
94
+
to the root dir of the package to be patched.
86
95
87
96
Default value: `package\\.json$`
88
97
89
98
-`--include <regexp>`
90
99
91
-
Only consider paths matching the regexp when creating patch files.
92
-
Paths are relative to the root dir of the package to be patched.
100
+
Only consider paths matching the regexp when creating patch files. Paths are
101
+
relative to the root dir of the package to be patched.
93
102
94
103
Default value: `.*`
95
104
@@ -103,7 +112,9 @@ which is a diff between normal old `package-name` and your fixed version. Commit
103
112
104
113
#### Nested packages
105
114
106
-
If you are trying to patch a package at, e.g. `node_modules/package/node_modules/another-package` you can just put a `/` between the package names:
115
+
If you are trying to patch a package at, e.g.
116
+
`node_modules/package/node_modules/another-package` you can just put a `/`
117
+
between the package names:
107
118
108
119
npx patch-package package/another-package
109
120
@@ -113,7 +124,8 @@ It works with scoped packages too
113
124
114
125
### Updating patches
115
126
116
-
Use exactly the same process as for making patches in the first place, i.e. make more changes, run patch-package, commit the changes to the patch file.
127
+
Use exactly the same process as for making patches in the first place, i.e. make
128
+
more changes, run patch-package, commit the changes to the patch file.
117
129
118
130
### Applying patches
119
131
@@ -125,9 +137,12 @@ Run `patch-package` without arguments to apply all patches in your project.
125
137
126
138
Un-applies all patches.
127
139
128
-
Note that this will fail if the patched files have changed since being patched. In that case, you'll probably need to re-install `node_modules`.
140
+
Note that this will fail if the patched files have changed since being
141
+
patched. In that case, you'll probably need to re-install `node_modules`.
129
142
130
-
This option was added to help people using CircleCI avoid [an issue around caching and patch file updates](https://github.com/ds300/patch-package/issues/37) but might be useful in other contexts too.
143
+
This option was added to help people using CircleCI avoid
144
+
[an issue around caching and patch file updates](https://github.com/ds300/patch-package/issues/37)
145
+
but might be useful in other contexts too.
131
146
132
147
-`--patch-dir`
133
148
@@ -145,22 +160,32 @@ or `patch` in unixy environments:
145
160
146
161
### Dev-only patches
147
162
148
-
If you deploy your package to production (e.g. your package is a server) then any patched `devDependencies` will not be present when patch-package runs in production. It will happily ignore those patch files if the package to be patched is listed directly in the `devDependencies` of your package.json. If it's a transitive dependency patch-package can't detect that it is safe to ignore and will throw an error. To fix this, mark patches for transitive dev dependencies as dev-only by renaming from, e.g.
163
+
If you deploy your package to production (e.g. your package is a server) then
164
+
any patched `devDependencies` will not be present when patch-package runs in
165
+
production. It will happily ignore those patch files if the package to be
166
+
patched is listed directly in the `devDependencies` of your package.json. If
167
+
it's a transitive dependency patch-package can't detect that it is safe to
168
+
ignore and will throw an error. To fix this, mark patches for transitive dev
169
+
dependencies as dev-only by renaming from, e.g.
149
170
150
171
package-name+0.44.0.patch
151
172
152
173
to
153
174
154
175
package-name+0.44.0.dev.patch
155
176
156
-
This will allow those patch files to be safely ignored when `NODE_ENV=production`.
177
+
This will allow those patch files to be safely ignored when
178
+
`NODE_ENV=production`.
157
179
158
180
## Benefits of patching over forking
159
181
160
-
- Sometimes forks need extra build steps, e.g. with react-native for Android. Forget that noise.
161
-
- Get told in big red letters when the dependency changed and you need to check that your fix is still valid.
182
+
- Sometimes forks need extra build steps, e.g. with react-native for Android.
183
+
Forget that noise.
184
+
- Get told in big red letters when the dependency changed and you need to check
185
+
that your fix is still valid.
162
186
- Keep your patches colocated with the code that depends on them.
163
-
- Patches can be reviewed as part of your normal review process, forks probably can't
187
+
- Patches can be reviewed as part of your normal review process, forks probably
188
+
can't
164
189
165
190
## When to fork instead
166
191
@@ -170,18 +195,30 @@ This will allow those patch files to be safely ignored when `NODE_ENV=production
170
195
171
196
## Isn't this dangerous?
172
197
173
-
Nope. The technique is quite robust. Here are some things to keep in mind though:
198
+
Nope. The technique is quite robust. Here are some things to keep in mind
199
+
though:
174
200
175
-
- It's easy to forget to run `yarn` or `npm` when switching between branches that do and don't have patch files.
176
-
- Long lived patches can be costly to maintain if they affect an area of code that is updated regularly and you want to update the package regularly too.
177
-
- Big semantic changes can be hard to review. Keep them small and obvious or add plenty of comments.
178
-
- Changes can also impact the behaviour of other untouched packages. It's normally obvious when this will happen, and often desired, but be careful nonetheless.
201
+
- It's easy to forget to run `yarn` or `npm` when switching between branches
202
+
that do and don't have patch files.
203
+
- Long lived patches can be costly to maintain if they affect an area of code
204
+
that is updated regularly and you want to update the package regularly too.
205
+
- Big semantic changes can be hard to review. Keep them small and obvious or add
206
+
plenty of comments.
207
+
- Changes can also impact the behaviour of other untouched packages. It's
208
+
normally obvious when this will happen, and often desired, but be careful
209
+
nonetheless.
179
210
180
211
## Why use postinstall-postinstall with Yarn?
181
212
182
-
Most times when you do a `yarn`, `yarn add`, `yarn remove`, or `yarn install` (which is the same as just `yarn`) Yarn will completely replace the contents of your node_modules with freshly unpackaged modules. patch-package uses the `postinstall` hook to modify these fresh modules, so that they behave well according to your will.
213
+
Most times when you do a `yarn`, `yarn add`, `yarn remove`, or `yarn install`
214
+
(which is the same as just `yarn`) Yarn will completely replace the contents of
215
+
your node_modules with freshly unpackaged modules. patch-package uses the
216
+
`postinstall` hook to modify these fresh modules, so that they behave well
217
+
according to your will.
183
218
184
-
Yarn only runs the `postinstall` hook after `yarn` and `yarn add`, but not after `yarn remove`. The `postinstall-postinstall` package is used to make sure your `postinstall` hook gets executed even after a `yarn remove`.
219
+
Yarn only runs the `postinstall` hook after `yarn` and `yarn add`, but not after
220
+
`yarn remove`. The `postinstall-postinstall` package is used to make sure your
221
+
`postinstall` hook gets executed even after a `yarn remove`.
0 commit comments