
## The Big Idea

Open source works best when we treat each other like humans - not vending machines for bug fixes.

## How We Patched a Broken Package - and What It Taught Us

Recently at [Craftwork](https://craftwork.com), we hit a snag using the [@payloadcms/storage-uploadthing](https://github.com/payloadcms/payload/tree/main/packages/storage-uploadthing) plugin for image uploads in [Payload CMS](https://payloadcms.com).

One of our engineers dug in, found the issue, and fixed it. We opened a [pull request](https://github.com/payloadcms/payload/pull/14250), hoping to help others in the same situation.

But here's the thing: We couldn't afford to wait for the PR to get merged before moving forward. Publishing a forked npm package is a common fallback - but it can be hard to maintain long-term.

In addition to creating a fork to submit a fix, we used [`pnpm patch`](https://mikebifulco.com/posts/patching-npm-dependencies-with-pnpm-patch) to apply the fix to our repo. It's clean, version-controlled, and works until the upstream package is updated.


## Maintainers Aren't the Problem

It's easy to forget that open source projects are often maintained by small teams under heavy load. At the time of writing, Payload has over 375 open pull requests. Expecting our fix to jump the line would be absurd.

This isn't about neglect or indifference. It's about capacity.

In other repos, we've seen PRs sit untouched for months, with long threads of angsty, impatient comments. I get it - but that doesn't help anyone. Especially not the maintainers.


### A Better Way to Contribute

Here's what we did instead:

- 🛠 Fixed the issue locally using `pnpm patch` (need a tutorial? I [gotchu](https://mikebifulco.com/posts/patching-npm-dependencies-with-pnpm-patch))
- 💬 Shared the patch tutorial in the GitHub PR to unblock others
- 🔁 Opened a new, cleaner PR
- 🤝 Let the maintainers off the hook - no pressure, just help

This approach makes open source better for _everyone_. It gives control back to contributors, and it gives maintainers room to breathe.

It is easy to forget that contributing to open source isn't just Pull Requests - discussion, community building, managing expectations, and creative solutions help us all build a better internet together.

I'm confident you'll get more results if you treat people with humanity - and you will [build a reputation for yourself](https://mikebifulco.com/newsletter/serendipity-isnt-an-accident) that makes people eager to help you when they can.

---

## Want to Do Open Source Better?

Read [*Working in Public*](https://hardcover.app/books/working-in-public) by Nadia Eghbal. It's the best book I've read on the culture of open source: what's broken, what's beautiful, and what's worth fixing.

Also, if you like learning by watching smart people build in public, check out:

- [cmgriffing](https://www.twitch.tv/cmgriffing) streams dev work and product experiments on both Twitch and YouTub
- [Rizel Scarlett](https://www.twitch.tv/blackgirlbytes1) does open source work, conference prep, and interviews on her channel

---

## Give without the expectation of receiving

Open source is a special kind of economy. Show up with something useful. Share what you've learned. Make it easier for the next person.

Let's be better guests in each other's repos.


Contributing to Open Source without being a Jerk

How We Patched a Broken Package - and What It Taught Us

Give without the expectation of receiving


## The Big Idea

Open source is an open invitation to plug into a global braintrust of brilliant people building the future. What you get out of it has a lot to do with what you put in.

<a
  href="https://tiny.outlier.ai/yckz3zcs"
  className="text-xs lg:text-xs xl:text-xs"
>
  Brought to you by Outlier AI
</a>

---

Source control services like GitHub and GitLab are more than just a place to store code. They provide a living, breathing network of ideas, collaboration, and discovery. Contributing to open source is a great way to build your network, learn new things, and get paid. People get hung up on the idea that the _only_ way to contribute to OSS is by opening pull requests or reviewing other peoples' code.

If you're not ready for that yet, that's okay! There are countless ways to contribute that shape the direction of tools you depend on. Active participation can benefit the libraries you rely on _and_ help you get your work done.

## Feedback is fuel

Open source runs on participation. You don't need to submit a Pull Request to be helpful. Star the repos you like, vote on issues that matter to you. Subscribe to threads where you can add meaningful context. Maintainers often decide what to work on based on what gets the most attention. Quiet enthusiasm doesn’t move roadmaps-clicks and comments do.

### Curation is a superpower

Finding great open source tools is a skill, and frankly, it can be a competitive edge. You won’t always be looking for a new library, but building your own mental Rolodex of interesting tools helps when you're deep in a problem later. I run [OpenAPI.Tools](https://openapi.tools/) to share and surface great projects in for API devs, thanks to hundreds of contributors. Day to day, I find most of my favorite new things from Bluesky, YouTube deep dives, and Discord messages that start with "I made a thing."

### Your activity is your brand

No one cares how many green squares you have, but when it really matters, people will notice if you’re actually _doing_ interesting work. When hiring, I take the time to brows every candidate's GitHub profile. If everything’s private, you disappear into the noise. I wrote about this in ["Your Resume Sucks"](https://mikebifulco.com/newsletter/your-resume-sucks), but the TL;DR is: your public footprint matters. Not for the numbers, but for the narrative.

GitHub is more than source control. It’s where modern builders show their work-and shape what gets built next.

---

## Front-end Devs: Get Paid to Critique AI-Generated Code

Outlier (by Scale AI) is hiring frontend devs to help train cutting-edge AI—no AI experience needed. Work remotely, set your own hours, and earn up to $50/hr reviewing code and UI, with weekly payouts.

Help shape the future of dev tools - [apply now](https://tiny.outlier.ai/yckz3zcs)

<a
  href="https://tiny.outlier.ai/yckz3zcs"
  target="_blank"
  rel="noopener noreferrer sponsored"
>
  <Image
    publicId="sponsors/scale-ai/contribute-sq"
    alt="Outlier by Scale AI"
    className="max-w-sm"
  />
</a>

---

## Repos for you to check out

On any given week, there's probably a half dozen repos that I've been sifting through for documentation, examples, or known bugs (as well as the occasional contribution). Here's the ones that have been on my mind this week:

- [Expo](https://github.com/expo/expo) - At [Craftwork](https://craftwork.com?utm_source=mikebifulco&utm_medium=email&utm_campaign=open-source-for-everything) we use Expo with React Native to build the mobile app that our team uses. React-native has come _such_ a long way in the past few years, thanks in no small part to the geniuses on the Expo team.
- [React Native Reusables](https://github.com/mrzachnugent/react-native-reusables) - Is a brilliant collection of reusable components for React Native, that uses tailwind (via the Nativewind library) to recreate Shad CN UI components for react-native. React Native apps can't use `<div>` and other HTML elements, so this library is a huge benefit for us.
- I've spent quite a bit of time usingtThe Typescript SDK for the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/typescript-sdk) as research for connecting AI tools to Craftwork's business logic; I think it's safe to say that I'm squarely in the _early adopted_ phase for this library. It's been a bit bumpy, but it's been evolving quickly.


Open Source your learning with GitHub

Front-end Devs: Get Paid to Critique AI-Generated Code


## Introduction

Sometimes a third-party package breaks, and you can't wait for a PR to make its way into a release. Fortunately, `pnpm patch` makes it dead simple to hotfix packages locally while keeping your version control clean.

Recently, we needed to patch the [`@payloadcms/storage-uploadthing` package](https://www.npmjs.com/package/@payloadcms/storage-uploadthing) to fix a bug with image loading, so that we could continue to use it as our image hosting provider for [Craftwork](https://craftwork.com)'s implementation of [Payload CMS](https://payloadcms.com).

Here's how we handled it, using `pnpm patch`.


### What is pnpm patch?

[`pnpm patch`](https://pnpm.io/cli/patch) is a tool provided by the pnpm package manager that allows you to patch packages locally—and commit those changes cleanly. It works by creating a patch file that contains the changes you want to make to the package. You can then apply the patch file to the package using `pnpm install`.

## The process

Patching a package is a three-step process:
1. Track down the bug
2. Create a patch file
3. Apply the patch file to the package

Let's go through each step in detail.

### Step 1: Track down the bug

In our case, we tracked the bug down by making changes to the `handleUpload` function in `@payloadcms/storage-uploadthing`. You can do this in two ways:

1. Dig into `node_modules/@payloadcms/storage-uploadthing/src/...` directly
2. Or, clone the repo and search from there if you want to keep your project folder clean

We worked directly inside `node_modules` to validate the fix quickly. One thing to keep in mind here is that running `pnpm install` will overwrite your changes to the package -- which is eactly why we need to use `pnpm patch` to create a persistent patch!

### Step 2: Make a Local Fix

Once you've got a fix in mind, try it out directly in your project. You will do this by making temporary edits right inside the installed version of the package within your IDE.

<Aside type="note">
  In our case, the fix for `@payloadcms/storage-uploadthing` involved some minor changes:

  - the `handleUpload` function wasn't setting a `url` field based on the UploadThing API's response, so our Payload db didn't have any image URLs stored.
  - the `disablePayloadAccessControl` setting was commented out, which caused payload to store _local_ image URLs instead of UploadThing's public URLs.
</Aside>

Once we saw that this fix solved the issue in development, it was time to commit it to source control using `pnpm patch`.

### Step 3: Create a Persistent Patch with pnpm patch

<Image
  publicId="posts/patching-npm-dependencies-with-pnpm-patch/patch-process-1"
  alt="A screenshot of the terminal showing the output of the `pnpm patch` command"
  caption="The `pnpm patch` command opens the dependency's code in a temporary directory for you to edit."
/>

To preserve your fix and commit it to source control:

1. run: `pnpm patch <package-name>`. This opens the dependency's code in a temporary directory for you to edit.
2. Reapply the fix in the temporary folder.
3. Test it - do everything you would typically do to make sure the fix works: test functionality, run linters and test suites, etc.
4. To complete your patch and ready it for addition to source control on your project, run: `pnpm patch-commit <package-name>`

That saves the patch to your repo, and pnpm will re-apply it automatically every time you install dependencies. It also modifies your `package.json` to reference the patched version.

This will add a new entry to your `package.json` like this:
```json
"@payloadcms/storage-uploadthing": {
  "patches": {
    "@payloadcms/storage-uploadthing": "patch/@payloadcms/storage-uploadthing.patch"
  }
}
```

...as well as a file in your project's `patches` directory that represents the patch itself, in git diff format. This file type is a little difficult to read. You can re-open your patch file in your code editor to see the changes. Your changes will also be reflected in your `pnpm-lock.yaml` file.

This will cause pnpm to apply the patch every time you install dependencies.

### If you need to edit your patch

This is one part of the workflow that leaves a bit to be desired - if you need to edit your patch later, the best workflow I've found is to remove the patch from your project by running: `pnpm patch-remove <package-name>`, and then start a fresh patch by running: `pnpm patch <package-name>` (and going through these steps again).

You _can_ edit the `.patch` file directly, but it's finicky. In most cases, it's easier to remove and re-create the patch.


### Closing the loop with the package maintainer

Your dependency is now patched, and you can commit it to source control to use. This can help provide evidence to open source maintainers that the fix is needed, and that it works. It's good practice to [open a pull request](https://github.com/payloadcms/payload/pull/14250) to the package maintainer with your fix so that they can review it and merge it into the main branch.


### When it's time to remove the patch

Once there is an upstream fix in place, you can remove the patch from your project by running: `pnpm patch-remove <package-name>`.

This will remove the patch from your `package.json` and the `patches` directory, and you can then commit the changes to source control.

Remember that this doesn't automatically update the dependency in your project to the latest version - you'll still need to use `pnpm install` to do that.

---

## Why this process is useful

- You don't need to wait on library maintainers to merge PRs to get your fix into your project
- Your fix lives in version control, so teammates and CI builds stay in sync
- It's a fast, repeatable way to patch packages without publishing a fork


## Not using pnpm?
If your team is using a package manager other than pnpm, there are other options that are very similar:

- for `yarn` you can use [`yarn patch`](https://yarnpkg.com/cli/patch)
- for `bun` you can use [`bun patch`](https://bun.com/docs/pm/cli/patch)
- for `npm` you can use [`npx patch package`](https://www.npmjs.com/package/patch-package)
- if you're using ruby's `bundler`, you're in the wrong place, and you have my sympathies.

The specifics of each of these options are very similar, but vary slightly - refer to the docs linked above for a walkthrough of each.


Patching NPM Dependencies with pnpm patch

Step 3: Create a Persistent Patch with pnpm patch

Closing the loop with the package maintainer

#devtools: 3 posts tagged

Contributing to Open Source without being a Jerk

Open Source your learning with GitHub