Source code patch artifact—patch-package

1. Background

In the vue project, the vue-pdf third-party plug-in is used to preview pdf, the written business code runs perfectly, and the pdf file content is previewed normally without any problems. Later, the needs changed, and the electronic signature function was added to the business needs. At this time, the content of the pdf file can be displayed, but the company's electronic signature cannot be displayed. This is frustrating because a lot of code has been written that is specific to this dependency and will most likely be wasted if the dependent library is replaced. What's more important is that it is already running in a production environment.

Without making major changes to the dependent libraries, first find the problem. After investigation, it was found that this is an official bug and the signature cannot be displayed . Further inquiries revealed that the root cause was that the electronic signature of its dependent package pdf.js was not displayed .

The problem has been located. The code to modify the electronic signature is in the dependency package of node_modules.

How to solve this problem?

2. Commonly used methods

1. File an issue for the dependent package and wait for others to fix it and release it.

2. Submit a PR to the dependent package, fix it yourself and wait for release

3. Overall copy project method

direct quotation

Directly copy the source code of the dependent package, reference it locally, and no longer reference it through npm package.

Publication of Private Treasury Law

Suitable for scenarios where the same dependency package is used in multiple projects. The modified source code can be published to a private warehouse.

4. Modify the citation method

Configure a webpack alias , such as 'reference path of the original file': 'reference path of the modified file' , so that the final modified file is referenced, such as:

resolve: {  
    alias: {  
        'pdfjs': path.resolve(__dirname, './patched/pdfjs/*'), 
    }
}

All the above methods have disadvantages:

The first two have a long repair cycle and rely on third parties. The repair time is uncertain and are not suitable for solving the current problem.

The latter methods are more complicated and will lead to a bloated project. It is easier to forget which part of the source code you have modified. Moreover, updating is troublesome. You need to manually update the code every time and cannot update it synchronously with the plug-in.

Is there a way to gracefully modify the source code of node_modules?

3. patch-package

patch-package lets program developers instantly fix and preserve npm dependencies. A perfect solution for patching dependencies.

# fix a bug in one of your dependencies
vim node_modules/some-package/brokenFile.js

# run patch-package to create a .patch file
npx patch-package some-package

# commit the patch file to share the fix with your team
git add patches/some-package+3.14.15.patch
git commit -m "fix brokenFile.js in some-package"

Instructions:

1.Installation _

npm i patch-package

If you don't need to run in production

npm i patch-package --save-dev

For yarn, pnpm, and docker installation commands, please check their git official website.

2. Modify npm package

Change the files in the node_modules folder to modify the dependent packages

3. Generate patches

npx patch-package package-name

4. Add automatic execution command

In package.json

 "scripts": {
    +  "postinstall": "patch-package"
 }

In the example of this article, find the dependent package pdfjs-dist to be modified in node_modules, and modify the code as follows:

Execute npx patch-package pdfjs-dist to generate patches. A patches folder will be generated in the file directory, as follows:

So far, the bug in the project has been fixed. How can I make the changes executed after other colleagues in the team pull the code?

Add the self-executing command as follows, which will be executed after npm install.

What is a patch file?

In fact, it is some git diff record description.

Principle : patch-package will git diff the source code under the current node_modules and the original source code, and generate a patch file in the project root directory.

How to self-test whether the patch is effective?

Manually delete node_modules in the project and re-execute the npm install command to install the dependent packages. After successful installation, check the files in the previously modified node_modules dependency package to see if the modified code still exists. If the previously modified code still exists, it means that the patch file has taken effect. If the code you modified before does not exist, it means that the patch file has not taken effect.

4. Benefits of patch-package

Version preflight

When a dependency changes, you are notified in red capital letters that you need to check whether the fixes you made are still valid. npx patch-package will directly report the error **ERROR** Failed to apply patch for package xxxx at path . The prompt can make it easier to locate the problem.

save space

There is no need to copy the source code. Using git diff to record patches saves space, is safe and convenient.

Reviewable

Patches can be reviewed as part of the normal review process.

5. Things to note

◦Directly modifying the code under node_modules is not recommended and should only be considered in emergency situations

◦In the long term, it is still necessary to completely fix the defects of third-party packages and gradually remove the .patch files in the project

Author: JD Insurance Zhang Jie

Source: JD Cloud Developer Community Please indicate the source when reprinting