patch-package: The Lifesaver for both Bleeding Edge and Legacy Projects

In the dynamic landscape of software development, managing dependencies is an integral part of building and maintaining any project. Developers frequently rely on a variety of third-party packages to optimize their work and avoid duplicating efforts. However, dealing with dependencies can present unique challenges, especially when working on modern, cutting-edge projects as well as legacy systems. While bleeding-edge projects might grapple with bugs or incomplete features in newly released dependencies, legacy projects often face issues with outdated or abandoned packages. The good news is that there's a versatile tool to help you tackle these challenges: patch-package.

patch-package is a powerful npm package that allows developers to apply patches to dependencies in their Node.js projects, effectively fixing bugs or applying temporary workarounds without the need to fork or modify the original package. This can be a game-changer when waiting for official fixes from package maintainers or dealing with deprecated packages. In this blog post, we'll cover how to use patch-package and explore its benefits for addressing the distinct challenges faced by both modern and legacy projects.

How to patch a dependency using patch-package

Let us look at an example. We have a React Native app and are stuck at an old version, but need to apply a fix to an outdated dependency. In this particular case, it is the Yoga framework that needs some patching since we can nog longer build on the latest version of Xcode and upgrading React Native versions is not easy for barebone projects (not using Expo).

Here is the steps we need to take:

1. Install patch-package as devDependency
2. Modify dependency code in node_modules}
3. Run patch-package with package name
4. Generate .patch file in patches directory
5. Add postinstall script to package.json
6. Commit .patch file and package.json changes to version control

Installing Patch-Package

To begin using patch-package, first, install it as a development dependency in your project:

npm install --save-dev patch-package

or

yarn add --dev patch-package

Modifying the Code

Locate the code inside the node_modules folder of the dependency you want to patch and make the necessary changes. This could be a bug fix, a feature enhancement, or a temporary workaround.

In our case, we need to change a bitwise operator to an OR operator in this file:
node_modules/react-native/ReactCommon/yoga/yoga/Yoga.cpp

That way we will fix this error that occurs in Xcode 14.3:

Creating a Patch

Once you've made the required changes, run patch-package followed by the package name:

npx patch-package package-name

In our case we want to patch the react-native package where the Yoga framework resides:

npx patch-package react-native

This command creates a .patch file in your project's patches directory. This file records the differences between the original and modified code and should be included in your version control system (e.g., git).

Applying Patches Automatically

To ensure that the patches are applied whenever dependencies are installed or updated, add a postinstall script to your package.json:

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

Now, when you or your team members run npm install or yarn, the patches will be applied automatically, maintaining consistency across all environments.

Useful in both bleeding edge and legacy code

patch-package provides a range of benefits for both modern and legacy projects, making it an indispensable tool in any developer's toolbox.

For modern, bleeding-edge projects:

• Quickly resolve issues with third-party dependencies without waiting for official fixes.
• Enable seamless collaboration with team members by maintaining consistency in patched dependencies.
• Enhance performance or security by applying custom optimizations or patches.

For legacy projects:

• Even if you are stuck on an outdated version of third party libraries you can pull in critical fixes.
• Breathe new life into abandoned packages by applying necessary bug fixes or updates.
• Ensure compatibility with newer Node.js versions or other dependencies.
• Minimize the risk of breaking changes by selectively applying patches, rather than updating entire packages.

patch-package is a valuable tool that simplifies dependency management and offers a flexible solution for handling issues that arise when working with third-party packages. Its versatility and ease of use make it an essential asset for developers working on both modern and legacy projects. By incorporating patch-package into your workflow, you can mitigate dependency-related challenges and focus on building robust, high-quality software.

Comments

[Jarod Wong]

Thanks Andreas! Very helpful!