How do I apply a patch given to me?

how-to-patch.md

So, I sent a patch as a workaround for some library and you don't know how to apply it? No problem, this should give the information you need to apply it without issues. If you do have issues, please let me know.

Tip

A patch is a way of us modifying the built code of a library in a way that is safe and painless for anyone else coming across the code-base, it is something generated using git so they all follow the same syntax.

I am going to show how to do it with two options here only, either with pnpm or with patch-package for when you are using something other than pnpm.

Modifying the patch from pnpm to patch-package and vice-versa

First and foremost you will need to identify for what was the patch made to be applied with, because pnpm has paths relative to a different place than patch-package. This means that they will both fail if you don't do the appropriate changes before applying the patches.

Identifying if the patch is meant for pnpm or patch-package

Tip

If this patch came from me, be sure that it was meant for pnpm so no need to do this analysis, click either to the guide for migrating it to patch-package or applying the patch with pnpm

First, to identify if the patch needs any changes you can either try running and seeing it error or seeing inside of the email looking to see if the paths inside of the patch's content are pointing from the root of your project.

Here's an exmaple for a patch for patch-package:

diff --git a/node_modules/@react-email/render/dist/index.js b/node_modules/@react-email/render/dist/index.js
index 9708ae6..60edc36 100644
--- a/node_modules/@react-email/render/dist/index.js
+++ b/node_modules/@react-email/render/dist/index.js
@@ -1,8 +1,4 @@
 "use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;

Here's an example of a patch for pnpm:

diff --git a/dist/index.d.mts b/dist/index.d.mts
index 77a03d74798bf4eb14d400325f1866130bfe3256..9447c1eb8034db1178ead7876af5f2e7fe62668f 100644
--- a/dist/index.d.mts
+++ b/dist/index.d.mts
@@ -15,10 +15,8 @@ type Options = {
     htmlToTextOptions?: HtmlToTextOptions;
 });
 
-declare const render: (component: React.ReactElement, options?: Options) => string;
-
-declare const renderAsync: (component: React.ReactElement, options?: Options) => Promise<string>;
+declare const render: (component: React.ReactElement, options?: Options) => Promise<string>;
 
 declare const plainTextSelectors: SelectorDefinition[];
 
-export { Options, plainTextSelectors, render, renderAsync };
+export { Options, plainTextSelectors, render };

From pnpm to patch-package

If it is from pnpm all you need to do is make all paths into the module's code relative to where your node_modules is located. So, a/dist/index.js -> a/node_modules/@react-email/render/dist/index.js.

This means that the example from above meant for pnpm would need to become the following to work with patch-pacakge:

diff --git a/node_modules/@react-email/render/dist/index.d.mts b/node_modules/@react-email/render/dist/index.d.mts
index 77a03d74798bf4eb14d400325f1866130bfe3256..9447c1eb8034db1178ead7876af5f2e7fe62668f 100644
--- a/node_modules/@react-email/render/dist/index.d.mts
+++ b/node_modules/@react-email/render/dist/index.d.mts
@@ -15,10 +15,8 @@ type Options = {
     htmlToTextOptions?: HtmlToTextOptions;
 });
 
-declare const render: (component: React.ReactElement, options?: Options) => string;
-
-declare const renderAsync: (component: React.ReactElement, options?: Options) => Promise<string>;
+declare const render: (component: React.ReactElement, options?: Options) => Promise<string>;
 
 declare const plainTextSelectors: SelectorDefinition[];
 
-export { Options, plainTextSelectors, render, renderAsync };
+export { Options, plainTextSelectors, render };

From patch-package to pnpm

If it is from patch-package all you need to do is remove all the /node_modules/<package-name> occurrences and have them all be relative to the location of where the package is located inside of node_modules. So, a/node_modules/@react-email/render/dist/index.js -> a/dist/index.js.

This means that the example from above meant for patch-package would need to become the following to work with pnpm:

diff --git a/dist/index.js b/dist/index.js
index 9708ae6..60edc36 100644
--- a/dist/index.js
+++ b/dist/index.js
@@ -1,8 +1,4 @@
 "use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;

Applying the patch for pnpm

Important

The content to go into <escaped-package-name> here will need to have all / substituted with __ for it to work properly but you can modify however you prefer. The <package-name> does not need to be changed, should be the same name of the package including its org (i.e. @react-email/render).

1. Create a file called ./patches/<escaped-package-name>@<package-version>.patch and paste in there the contents of the patch that were given to you
2. Add the following substituting the <package-name> and the <package-version>

"pnpm": {
  "patchedDependencies": {
    "<package-name>@<package-version>": "patches/<package-name>@<package-version>.patch"
  }
}

3. Run pnpm install and the patch should be applied!

Applying the patch with patch-package

Important

The content to go into <escaped-package-name> here will need to have all / substituted with + for it to work properly as it will fail otherwise. Example: @react-email/render -> @react-email+render

1. Create a file called ./patches/<escaped-package-name>+<package-version>.patch and paste in there the contents of the patch that either were given to you or that you modified for running with patch-package
2. Install patch-package as a dev dependency:

npm install -D patch-package

2. Add the following script to your package.json:

"scripts": {
    "postinstall": "patch-pacakge"
}

3. Run npm install and it should apply the patch properly!