As a GIS frontend developer, I work extensively with various large-scale graphics libraries: OpenLayers, Leaflet, Mapbox GL JS, Cesium, Turf.js... These libraries often contain tens of thousands of lines of code. I wonder if you've encountered situations during development where you needed to modify the source code within node_modules. For example, in my old projects using OpenLayers 6.x, some third-party plugins were no longer updated. In such cases, upgrading to newer plugin versions would require upgrading the OpenLayers version, which is often an impossible workload for a project delivered years ago.

Traditional Solutions

How to solve this problem? Many newcomers to GIS development might directly modify the code in node_modules. However, the downside of this method is obvious: it works locally, but as soon as someone else pulls the code and runs npm install, the bug returns; CI/CD pipelines also fail during builds.

Another method I often use is to download the entire library, modify it, and publish it as a private package. This requires the company to have its own private NPM repository. Not all companies have such infrastructure. For instance, although my company has a private NPM repository, it requires various permissions to access. Therefore, I usually place the modified code in a Git repository and introduce it into the project using npm + Git.

npm i https://github.com/user_name/node_project_name

A More Elegant Solution: patch-package

Recently, I encountered this problem again. Using NPM + Git for library introduction still felt cumbersome, as it requires creating a new repository and configuring access permissions each time. I knew I couldn't be the only one facing this issue, and sure enough, I discovered a more elegant solution: patch-package.

How to Use It?

Suppose your project uses Mapbox GL JS to load vector tiles with UTM projection (EPSG:32650), and you find that at zoom level 10 and above, POI labels deviate from the feature center. After troubleshooting, you locate a coordinate calculation error in the projection transformation within mapbox-gl.js. How should we use patch-package to fix this?

Step 1: Install patch-package

npm install patch-package --save-dev
# or using yarn
yarn add patch-package postinstall-postinstall

Note: If using yarn, it's best to add postinstall-postinstall for compatibility.

Step 2: Directly modify node_modules

Locate node_modules/mapbox-gl/dist/mapbox-gl.js in your project and find the projection-related code (e.g., search for the projectToScreen method). Fix the coordinate calculation logic:

// Original erroneous code (simplified example)
const projected = this.projection.project(coords);
const x = projected.x * this.scale;
const y = projected.y * this.scale;

// Fixed code (adding UTM projection offset compensation)
const projected = this.projection.project(coords);
const x = projected.x * this.scale - (this.projection.isUTM ? 10 : 0);
const y = projected.y * this.scale - (this.projection.isUTM ? 5 : 0);

Step 3: Generate the patch file

npx patch-package mapbox-gl

After execution, a patches/mapbox-gl+2.9.1.patch file will be generated in the project root directory. This file records your code modifications and must be committed to the Git repository.

Step 4: Apply the patch

Add a postinstall script to package.json to ensure the patch is automatically applied every time npm install or yarn install is run:

{
  "scripts": {
    "postinstall": "patch-package" // Add this line
  }
}

After other team members pull the code, they only need to run npm install, and the patch will be automatically applied to node_modules—no extra steps required.

Summary

Although patch-package can solve this problem, I advise against overusing it unless absolutely necessary, as it can make the code increasingly difficult to maintain. It should only be used when the original npm package is no longer maintained or for urgent production fixes. Additionally, always lock the version when using it to avoid version conflicts.

What dependency library issues have you encountered in your GIS projects? Feel free to share your solutions in the comments!