Open Source

Fixing a Next.js Documentation Issue

How a small bug in the MSW example led me to contribute my first merged PR to Next.js, and what it taught me about open source.

Hamad Ullah

24 Oct 2025 — 4 min read

A few months ago, I was assigned a ticket to integrate Mock Service Worker in to Ruby for API mocking. While trying to make things work, I stumbled upon a confusing issue, not in my code, but in the Next.js documentation itself. What began as a simple debugging session turned into a pull request that’s now officially merged into the Next.js repository.

This is a blog post on of how I found an issue, what I did to fix it, and why contributing to open source is essential.

How I Found the Issue

I setting up API mocking using MSW in our Next.js application. For local development, MSW is incredibly useful, it intercepts network requests and allows us to simulate API behaviour without touching the backend.

I followed the Next.js documentation example for MSW setup carefully, but something just wasn’t working. The worker setup wasn’t behaving as described, in fact the imports were unrecognized.

After digging into the issue for a bit, I realized the example itself had a outdated setup, something subtle that could easily trip up any developer trying to follow it step by step.

I checked GitHub, and someone had already opened an issue describing the same problem. I realized the documentation is outdated and added a to-do for future reference to fix it in my free time.

What I Did

I cloned the Next.js repo, navigated to the documentation example, and made the necessary fix. The goal was simple, make the MSW example actually work as advertised.

After verifying the fix locally and ensuring that it didn’t break anything else, I submitted a pull request with a short, clear explanation of what the problem was and how my change resolved it.

The Pull Request I made is the following:

Soon after, one of the maintainers reviewed it, validated the change, and merged it.

That was a really satisfying moment, not just because my code was now part of Next.js, but because other developers wouldn’t need to waste their time figuring out why the setup isn't working as expected.

Why I Think It Got Merged

Open source maintainers get hundreds of PRs. What I did was review the ones that actually got merged. I think that’s what worked in my case:

I explained why the fix was needed, not just what it did.
I referenced the existing issue and made it easy to verify the bug and the fix.
The PR didn’t introduce extra complexity. It was a focused, single-purpose fix.
I followed the repo’s contribution guide and conventions closely.
I added a demo video which made it easier for reviewers to glance over my changes. Even though they'd still test locally, it establishes trust.

I tried to make it as contextual and easy to review as possible, because open-source reviewers are often doing this work in their free time - it's best to utilize their time in the best possible way, in the rare hours they get it.

Why is open source development important?

Open source is the invisible backbone of modern web development. Majority of the frameworks, libraries, and tools we use, from React to Next.js, MSW, Tailwind, and beyond, are built on the collective effort of thousands of developers who share their work openly.

Contributing back isn’t just a nice gesture, it’s how the web keeps evolving. When you fix a bug, improve documentation, or clarify an example, you’re helping thousands of other developers avoid the same confusion.

What makes open source especially powerful in the JavaScript ecosystem is how interconnected everything is. A small fix in one project can ripple across others, improving developer experience far beyond a single codebase.
In a world where frameworks constantly transform and build on each other, collaboration is what keeps innovation moving forward.