If you’ve ever hit a wall with a Capacitor plugin — maybe a bug in native code or a missing feature — you know how frustrating it can be to wait on a pull request or maintain your own fork. Luckily, there’s a better way: patch-package.

This post walks you through how to safely patch Capacitor plugins using patch-package, so you can fix or tweak plugins without forking them — and keep those changes consistent across environments and installs.

What Is patch-package?

patch-package is a tool that lets you make changes directly inside node_modules and preserve those changes across reinstalls.

Instead of forking a dependency, you:

• Make the changes you need
• Run a command to generate a .patch file.
• Let patch-package reapply your changes automatically during install or build

It’s an especially handy tool for Capacitor developers (or other npm users), where plugin issues can often involve native Android or iOS code that’s not easily overridden without modifying the source.

How Does patch-package Work?

When I first found out how it works I was just amazed by its simplicity and powerfulness, so I thought it deserves a paragraph in my blog post.

Let’s demystify it. when you run npx patch-package some-package, it:

1. Compares the original package (from node_modules) to your modified version.

2. Generates a .patch file (a Git-style diff) that captures those changes.

3. Stores the patch in a /patches folder in your project.

4. Applies the patch automatically via a script (we’ll use npm'sprepare hook) every time dependencies are installed or the app is built.

This means you get the exact changes you made — even on CI servers or other team members’ machines — without touching the actual package repo or forking it.

Example patch file name:

patches/@capacitor+camera+5.0.3.patch

That file will only apply to version 5.0.3 of the @capacitor/camera plugin.

Why You Might Need It in a Capacitor Project?

Capacitor plugins are unique: they often include native code (Java, Kotlin, Swift, Obj-C) and a JS wrapper. This makes customization hard without digging into internals.

You might use patch-package to:

Fix a bug in Android or iOS code (e.g., permission handling)

Modify a JS wrapper to expose more native functionality

Remove hardcoded behavior that conflicts with your app

Instead of maintaining a fork or waiting for maintainers to respond to an issue or PR, you can patch it immediately.

More over, you can patch it while waiting for the PR to be approved and then get rid of the patch once a new version with your fix is released.

Step-by-Step: Patching a Capacitor Plugin

1. Install patch-package

npm i -D patch-package

2. Then update your package.json:

"scripts": {
    ...
    "prepare": "patch-package"
}

The prepare script runs automatically after npm install and before builds or publishes. It ensures patches are applied reliably across all environments without bloating the install process itself.

3. Make the Changes You Need

Find the plugin you want to modify inside node_modules. For example, if you’re patching the Capacitor Camera plugin:

node_modules/@capacitor/camera/android/src/main/java/com/capacitorjs/plugins/camera/CameraPlugin.java

Make your edits directly to the source file(s). This could be:

• Modifying native code behavior
• Fixing an error
• Changing the way JS interacts with native layers

4. Generate the Patch

Once you’re happy with your changes, run:

npx patch-package @capacitor/camera

This creates a file in the patches/ folder:

patches/@capacitor+camera+5.0.3.patch

Open the patch file and you’ll see a Git-style diff with your changes.

5. Test and commit

Run your app to make sure everything works as expected. Then commit the patch file and updated scripts.

Now any time your app is installed or deployed, the patch will be reapplied automatically.

Things to Watch Out For

Version sensitivity: Patches only apply to the exact version you generated them from. Upgrading the plugin may require redoing the patch.

Conflicts: If the structure of the plugin changes upstream, the patch may fail to apply. You’ll get a clear error if this happens.

Not for large rewrites: patch-package is great for small or temporary fixes. For larger long-term changes, consider forking the plugin.

Make sure the diff is clean by removing any files in the node_modules folder of the package that are not needed (like the build folder in android for example)

Bonus: Patching Native Code? Yes, You Can!

Because patch-package works on files inside node_modules, you can use it to patch native Android or iOS code — something not easily done otherwise.

Just remember to run:

npx cap sync

after making changes to native code so Capacitor rebuilds with the latest.

Final Thoughts

Using patch-package with Capacitor plugins is a lightweight, efficient way to fix bugs or make critical tweaks without losing your mind over forks or upstream delays. It’s also relevant to other npm packages but since TypeScript and JavaScript packages may require an additional steps of cloning and building, the Capacitor example is used in this article, since it’s a lot simpler.

It’s perfect for teams that:

• Need to move fast
• Want reproducible fixes across all environments
• Don’t want to fork every time a plugin needs a minor change

And with the prepare script in place, your patches stay rock solid from dev to CI to production.

Recently, I explored this question by building a proof of concept (POC) to share vector tile slicing logic across platforms. Here’s what I learned.

The Motivation: One Core, Many Targets

maplibre-native is written in C++ and recently was intoduced to a Rust library for color parsing. Meanwhile, maplibre-gl-js powers the browser side. Maintaining separate implementations for the same logic means duplicated effort and potential inconsistencies.

Sharing code would:

• Reduce bugs due to inconsistent behavior.
• Lower maintenance cost.
• Ensure performance optimizations benefit all platforms.

The POC: Using Rust and geojson-vt-rs

To test this, I tried to integrate a library that’s a bit bigger than color parsing called geojson-vt-rs, a Rust implementation of the vector tile slicing algorithm that already exists in both c++ and JavaScript. Rust is a natural fit for this because:

• It’s performant like C++.
• It has great WebAssembly (Wasm) support, making it easier to run in the browser.
• Its ecosystem for cross-compiling is mature.

The idea was to compile the Rust code to WebAssembly, then import it into the maplibre-gl-js TypeScript project.

I must admit that getting it to create a wasm with some javascript wrapping code and typescript definition was the easier part of all this POC.

I added some wrapping impl of the struct I needed to export with some JsValue input and output parameters, #[wasm_bindgen] annotations and used the amazing wasm-pack and tool to built it:

wasm-pack build --target web

This created a few files that allows to create an npm package with the following command:

wasm-pack pack

Unfortunately, it didn’t work out of the box and I did need to edit two files to make it work.

1. Remove the following lines from geojson_vt_rs.js as they created some issue with the (complicated) rollup setup we have.

- if (typeof module_or_path === 'undefined') {
-    module_or_path = new URL('geojson_vt_rs_bg.wasm', import.meta.url);
- }

2. export the wasm file by editing package.json file.

Once the above were done I could create an npm package using npm pack command and install this locally created file in maplibre-gl-js project.

In this next part I needed to use the @rollup/plugin-wasm in order to inline the wasm into the JavaScript code with the wasm({targetEnv:”auto-inline”}) and also import and initialize it in the section of the code that I wanted to change:

// import the relevant code
import init, {GeoJSONVT} from 'geojson-vt-rs';
// @ts-ignore
import wasm from 'geojson-vt-rs/geojson_vt_rs_bg.wasm';

...

// initalizing the wasm, should be done once, 
// !! this is important for rollup to pick it up !!
await init(wasm());

...
// using the wasm code
this._geoJSONIndex = GeoJSONVT.from_jsobjects(pendingData) as any;

The Good: It Works!

Technically, the experiment worked! The Rust code compiled to Wasm, and the TypeScript project could use it for slicing GeoJSON into vector tiles on the fly. The output matched expectations and proved that sharing low-level logic across languages is feasible.

The Bad: Package Size Woes

However, there was a big catch: package size.

The Wasm bundle added significant weight to the final JavaScript bundle (around 30%). For modern web apps, where every kilobyte affects performance and time-to-first-paint, this was unacceptable. The tradeoff didn’t make sense for MapLibre’s goal of delivering fast and lightweight maps.

Next Steps

For now, we’ll continue to use the current implementations for every platform. An idea I had was to bundle all the shared code in a single Rust generated wasm in order to remove some of the overhead related to code sharing, the downside of this idea is that you can’t split the library into smaller pieces to allow tree-shaking in the future as these two idea kinda collide.

Sharing code across C++, TypeScript, and Rust is an exciting frontier for projects like MapLibre. If you’ve experimented with this or have ideas for keeping Wasm bundles slim, I’d love to hear from you!

The history of chainable is pretty long, by now this is far from a new concept. I first encountered this back in the days when I wrote in C# and LINQ was a shiny new addition to the language.

What is chainable?

If you are already familiar with the concept you can skip right ahead to what I think about in the next paragraph, if not, the definition is pretty simple: The ability to chain a few methods one after the other.

for example:

let a = new A();
a.setSomething("something").setSomethingElse(2).doSomething();

The implementation of this is fairly simple, just return the class this method belongs to in every method and you can chain methods one after the other.

Ok, great! I want two to go please!

This is great for some use cases, but not a great for other.

Builder pattern is the most know example of a good usage of chainable — it creates an immutable object, and every method returns a new immutable object, so that you can’t modify an object but only create a new one from an existing on, which guards the immutability of an object.

Another good example is stream manipulation or array manipulation, like was introduced in LINQ, here’s a similar example in javascript:

let a = ["a", "b", "c"];
let b = a.map(item => { return { num: 1, text: item }}).filter(item => item.num > 2);

So, what’s the catch?

The problem with chainable comes from the definition I wrote earlier — “just return the class this method belongs to in every method…”. This is problematic for a few reasons.

The first reason is inheritance, returning the base object for inherited classes can create an awkward code, but you might be dismiss this by saying “don’t inherit, use composition”, which I generally agree so let’s say this is a “weak” argument.

The main reason for me, and probably why I decided to write this blog post, is backward API compatibility issues for methods that in theory should’ve return void and now return this which changing them will break existing code.

Let’s take a look at a real problem I faced while maintaining one my open source projects. In this project, which I inherited, most of the methods were chainable, including the following one:

class Map {
  ...
  // this method allows regitering for an event with the name "type".
  // It returns "this" to allow chaining
  on(type: string, listerner: Listener): this {
    ...
    return this;
  }
}

So the code to use this would be something like:

let map = new Map();
map.on('move', () => { doSomething() });

Great! I can register to a move event and execute my code when this events gets fired. In some cases I would like to unregister from the move event and stop receiving notification about it. In that case I would use the off method, but I need to change my code now in order to achieve that into something like:

let map = new Map();
let listener = () => { doSomething() };
map.on('move', listener);
//...
map.off('move', listener);

That’s not very pretty, and RxJS already showed us that there’s a more elegant way to achieve this using subscription, right?

So if the on method would return something that I can call in order to unsubscribe I could hold onto that and call this unsubscribe later on in my code, something like:

let map = new Map();
let subscription = map.on('move', () => { doSomething() });
//...
subscription.unsubscribe();

This is a lot more elegant, and a lot more modern, but here’s the catch: I can’t change the return value of the method because it is chainable, and chainging that will create a breaking change to the API and users who depend on the chainable functionality will need to change their code.

In this case and in a lot of other cases, I’ve seen places that use a chainable API that can create maintenance problems of keeping an API backwards compatible. Chainable has merit, but in most cases that’s I’ve seen it saves a few clicks on the keyboard of developers at best.

My advice

Don’t force a chainable API where it’s not necessary, your future self will thank you 😊

When it comes to user experience, there are a lot of places you can create a positive and fun user experience, but also a lot of places where you can really frustrate the user…

You can do animations, graphics and some really nice stuff, but the place where most of the apps lack is when things don’t go as expected. The default is usually an unhelpful message like “oops, please try again later”, and when you try again, it doesn’t help, surprisingly…

In the past few days, I have encountered a situation where bad error message and wrong defaults left me, a very seasoned developer, with trial and error to understand how to overcome a problem.

This is my story, hoping anyone who will read this will later on remember it when returning an unhelpful error message or forgetting to set the right defaults.

Here goes. I made a few changes to my library including some CI improvements and wanted to publish a new version to npm, so I used the CI tools to do that and got the following error message:

npm ERR! code ENEEDAUTH
npm ERR! need auth This command requires you to be logged in to https://registry.npmjs.org/
npm ERR! need auth You need to authorize this machine using `npm adduser`

The error message itself seems like a login is needed, which was weird since I didn’t change anything related to my npm token.

I thought it was something I changed related to “who” runs the CI pipeline, so I started to revert stuff, but nothing helped.

After a few hours of reading GitHub issues, I found someone saying that I need to configure my registry-url, which I accidetally removed in one of my commits, apparently.

I then remembered that I have changed the setup-node configuration of my CI to use my .nvmrc file so that everything will use the same node version, both for development and for CI, little did I know that this change will cause a npm publish failure…

For reference here’s the relevant commit change of my CI:

      - uses: actions/setup-node@v3
        with:
-         node-version: lts/*
+         node-version-file: '.nvmrc'

So, I added the relevant parameter and the publish started working again! Yay!

In the above example you can easily see that if the defaults were better, e.g. when not setting registry-url it will use the default npm registry, this issue could have been avoided. A better error message like “registry is not defined” would have allow me to fix the issue a lot faster and lead me in the right path.

I’m hoping you could keep this story in mind the next time you return an error message or define a default 😀

A little story to explain why I hate getters and setters.

I encountered the following seamlessly naive piece of code:

apply(that: Transform) {
  this.tileSize = that.tileSize;
  this.latRange = that.latRange;
  this.width = that.width;
  this.height = that.height;
  this._center = that._center;
  this._elevation = that._elevation;
  this._minEleveationForCurrentTile = that._minEleveationForCurrentTile;
  this.zoom = that.zoom;
  this.angle = that.angle;
  this._fov = that._fov;
  this._pitch = that._pitch;
  this._unmodified = that._unmodified;
  this._edgeInsets = that._edgeInsets.clone();
  this._calcMatrices();
}

This method is not very interesting, it basically applies a Transform onto this which is of type Transform and updates its internal members.

When reading this code, it was obvious to me that this._calcMetrices() is an operation that takes time and should be done only after setting all the values of this.

Little did I know that when setting the value of what appeared to be an innocent property zoom the following is what is being executed:

get zoom(): number { return this._zoom; }
set zoom(zoom: number) {
    const constrainedZoom = Math.min(Math.max(zoom, this.minZoom), this.maxZoom);
    if (this._zoom === constrainedZoom) return;
    this._unmodified = false;
    this._zoom = constrainedZoom;
    this.tileZoom = Math.max(0, Math.floor(constrainedZoom));
    this.scale = this.zoomScale(constrainedZoom);
    this._constrain();
    this._calcMatrices();
}

It took me a few hours to understand that this is the cause of what appeared to be a bug in a new code I introduced.

It is also obvious that this._calcMatrices() is not called at the end of the first method and it’s called more than once!

This is not the first and probably not the last time I’m experiencing this kind of frustration from code that uses get and set.

So, my suggestion to anyone reading this: Stop using those!

You can easily write the following, more readable code:

setZoomAndUpdateState(zoom: number) {
    const constrainedZoom = Math.min(Math.max(zoom, this.minZoom), this.maxZoom);
    if (this._zoom === constrainedZoom) return;
    this._unmodified = false;
    this._zoom = constrainedZoom;
    this.tileZoom = Math.max(0, Math.floor(constrainedZoom));
    this.scale = this.zoomScale(constrainedZoom);
    this._constrain();
    this._calcMatrices();
}

It will achieve the same result and will be a lot more readable in the initial discussed method, here’s how it would look:

apply(that: Transform) {
  this.tileSize = that.tileSize;
  this.latRange = that.latRange;
  this.width = that.width;
  this.height = that.height;
  this._center = that._center;
  this._elevation = that._elevation;
  this._minEleveationForCurrentTile = that._minEleveationForCurrentTile;
  this.setZoomAndUpdateState(that.zoom);
  this.angle = that.angle;
  this._fov = that._fov;
  this._pitch = that._pitch;
  this._unmodified = that._unmodified;
  this._edgeInsets = that._edgeInsets.clone();
  this._calcMatrices();
}

Happy coding!

addProtocol is one of the most powerful capabilities that were added to one of the earlier versions of maplibre-gl-js.

addProtocol basically adds a callback to be called before any ajax request made by the library, which allow intercepting the request, changing the data and returning it for continued processing and rendering.

Let’s see some javascript code:

import maplibregl from 'maplibre-gl-js'

maplibre.addProtocol('my-protocol', (params, callback) => {
    const geojson = { type: 'Feature', geometry: {...} };
    callback(null, geojson, null, null);
    return { cancel: () => { } };
});

const map = new maplibregl.Map({
  container: 'map',
    style: {
      version: 8,
      sources: {
        customSource: {
          type: 'geojson',
          data: 'my-protocol://data.json'
        }
      },
      layers: [{
        id: 'layer'
        type: 'circle'
      }]
  }
});

In the above example we are using a custom protocol: my-protocol and when MapLibre is trying to fetch the data at my-protocol://data.json the code we registered is called and we can, in this case, return a geojson object which will be processed and presented.

Note that the type of the source is important in order to return the right data — for geojson you need to return a geojson object, for raster you need to return arrayBuffer of the image, and for mvt the content the pbf in arrayBuffer format.

That’s it! Super simple, super powerful!

Here’s an example of how it can look (given the right geojson object):