Publishing an npm package is easy. Maintaining it is not
Publishing a package to npm needs three things: code, a package.json and one command. It takes a day.
I have published three packages. And the main thing I learned about them is not the publishing process — it is what happens afterwards.
Because the moment a package is out, it stops being only yours. People use it, their code depends on yours, and you are no longer free.
This article is about that.
Before publishing: three mandatory things
The technical side is easy, but three things need to be right from the start, because changing them later is expensive.
1. Declare explicitly what is exported.
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
},
"files": ["dist"]
}The files field matters: without it, test files, configs and random debris end up in the package. Before publishing, run npm pack --dry-run to see what is actually going out — a one-second habit that saves a lot of embarrassment.
2. Keep dependencies minimal.
Every dependency becomes mandatory for whoever uses your package. Writing ten lines of code instead of pulling in a library for a small helper is almost always the better call.
If your package works with a framework, put it in peerDependencies, not dependencies. Otherwise your user ends up with two copies of the framework and confusing errors.
3. The README should open with a working example above the fold.
People do not read documentation, they copy. Put a working, complete, copy-pasteable example in the first twenty lines of the README. Everything else goes below.
Versioning: misunderstanding what a breaking change is
Everyone knows semantic versioning: the major number is a breaking change, the minor a new capability, the patch a fix.
The problem is the definition. Many people take "breaking change" to mean an API change only. The real list is much longer:
- A function name or parameter order changed — that one is obvious
- A default value changed — same API, different behaviour
- An error type changed — somebody may have been checking it inside a
catch - The minimum Node or framework version went up — the package stops working for people on older environments
- The output shape changed — a field was added to a returned object and somebody was comparing it wholesale
That last one is debatable, but the practical rule is this: if a change can break somebody's working code, it is breaking.
I have watched something I shipped as a "small fix" break someone's code more than once. Now, when in doubt, I bump the major. A version number is cheap; trust is expensive.
The biggest time sink: issues
Writing code is a small part of maintaining a package. Most of the time goes to talking with people.
Issues split into roughly three kinds.
Real bugs. These are the most valuable — somebody has done free testing for you. But they usually arrive without reproduction details. I added an issue template and it improved things noticeably: version, environment, expected and actual result.
Usage questions. "How do I do this?" That usually signals a documentation gap. When I answer, I also add the answer to the README — then the question does not come a second time.
Feature requests. The hardest kind, because this is where you have to say no.
Learning to say no
This was the hardest part for me.
Somebody is using your package and asking for something. Refusing feels awkward. But every capability you add is a permanent obligation: it has to be maintained, tested, documented, and protected from incompatible changes.
My criterion is: does the request belong to the package's core job?
If yes, let us discuss it. If no, I say so honestly: this is outside the package's scope, but here is how you can do it yourself.
That answer helps people too. A vague "I'll look into it" leaves them waiting. A clear "no" lets them go find another solution.
Documenting the scope in the README works well: what the package does, and what it does not do. The second list is no less useful than the first.
An honest word about burnout
Maintaining an open source package is voluntary, but it starts to feel like an obligation.
An issue is open, you have not answered, and it hangs over you. A few months later you are avoiding the repository.
Three things helped me.
Write down expectations. One sentence in the README is enough: this package is maintained in personal time, replies may be delayed. That is honest and it removes pressure.
Declare the package finished. Not all code has to keep growing. If a package does its job, it can be "stable and complete". That is a state, not abandonment.
If you are stepping away, say so. The worst option is disappearing quietly. If you will no longer maintain a package, write it in the README. People can plan, and somebody might take it over.
Is it worth it
Yes, but not for the reason people expect.
Open source will not make you famous, and job offers are rare. The real return is elsewhere.
The first is that your code quality changes. When you write code others will read and use, you treat names, documentation and edge cases completely differently. That habit then carries into your work code.
The second is that you see your own assumptions. What is obvious to you turns out not to be obvious to anyone else. No book on API design teaches that.
If you are thinking about publishing a package, my advice is simple: keep the scope small. A package that does one thing well can be maintained for years. A package that does everything will exhaust you in six months.