A year ago, I thought the hardest part of open source would be building the package....
It was not.
The code mattered, of course. But building snappycart in public taught me that writing the package is only one layer of the job. The harder part is making the project visible, understandable, trustworthy, and worth coming back to. And knowing what I knew did not mean that everyone could get the same vibe and go along with it. So what actually happened? Read on!
snappycart started as a practical React cart package, something developers could integrate into ecommerce and SaaS products without dragging in a messy setup. The main reason I created it was to save money on cart and checkout integrations and I immediately saw gap there which prompted me to release my snappycart to the world. Over time, though, it became much more than a package. It became a product, a repository, a contributor space, a testing surface, and a public signal of how seriously I take quality. And this can be easily proven by how much time snappycart contributors invest in testing an developing the package. Surely anyone can release a package, but would that anyone be able to get the momentum out of contributors around it? Probably, but not instantly.
That changed how I think about open source.
Here are seven mistakes I learned the hard way that I am eager to share with you because I want our open source community to strive and produce more free solutions for all of us devs out there. Enjoy...
1. I thought publishing the package meant people would find it
This was the first big misunderstanding. Man, if I only knew...
Like a lot of developers, I assumed that once the package was live on npm and GitHub, the right people would eventually come across it. I thought the quality of the thing itself would do more of the work, just like they show us in the movies.
It does not.😬
Publishing is not distribution in the same way as shipping is not visibility. Open source is not some magical meritocracy where good code automatically floats to the top just because one day you woke up, had some coffee, sat in your wonderful London garden and DEVELOPED IT... Most people are busy, distracted, and already overloaded with libraries, tools, and repos they have not had time to evaluate. But even worse, not many devs are even considering other tools. I mean who really wants to trade some tool they learnt back in 2020 during the COVID-19, when they had the time, to something that Viola (@idncod) decided to release to 'solve' their problem? What problem?...
That means if you build something useful, you still have to explain why it exists, who it is for, and why someone should care right now and for others it's fine to pass it by.
The lesson for me was simple: if I want snappycart to grow (organically), I cannot just build it and leave it. I have to talk about it, demo it, document it, and repeat the message consistently. Otherwise it just becomes another repo in the pile and nobody gets to see those cute big odd eyes!
2. I underestimated how much people need examples
I originally put too much faith in the package API doing the talking.
In reality, developers do not want to imagine how something works. They'd rather see it working. They (actually, we!) want to know how the provider wraps the app, how state moves through the UI, what the cart drawer looks like, how quantity updates behave, and whether the integration feels smooth or annoying. You know, the sacred DEMO that we desire to play with and get to know the package.
That means examples are not a nice extra. They are part of adoption! (knowing myself too well, I must have thought about this from day one but just didn't feel the urge yet. Well, too bad.)
One of the most important shifts I made with snappycart was thinking beyond the package internals and focusing more on the actual developer journey. A demo app, realistic usage flows, and clear visual examples do far more than a technically correct API description on its own.
A lot of open-source projects lose people because they make users do too much interpretation which is a big mistake. Imagine if someone has to mentally assemble your product before they can trust it, you are already asking for too much without providing any value upfront.
3. I treated docs like support material instead of part of the product
This is such an easy trap. And I am glad I get it now.
At the start, it is tempting to think: let me finish the code first, then I will polish the docs later. That sounds reasonable, but it is wrong.
For most users, the docs are the first product they touch.
They are not meeting your architecture first. They are meeting your README, your install instructions, your project structure, your usage examples, and the speed at which they can get to their first success. If that experience feels messy, the whole project feels messy.
Working on snappycart forced me to take documentation more seriously, not as a cleanup task but as part of the interface. The docs are where confidence starts. They are where people decide whether this project feels maintained, understandable, and safe to try.
Bad docs do not always create loud complaints. More often they create silent drop-off, which is worse.
Now that I have made some drastic changes to my README in the latest version 1.2.3, I am over the moon to hear from my contributors and people who see my product for the first time things like: 'Well, this README is actually well-structured and it's very easy to understand how I can contribute' (-Zinaida, contributor) and 'The README is so detailed that I can tell what I am dealing with' (-Jay Saadana).
4. I assumed contributors would just figure the repo out
That was naive.
If you want contributions, you have to design for contribution. People need a way in. They need to understand the structure, the setup, the workflows, the standards, the frameworks, and the straightforward release process. They need to know where the package lives, where the demo app lives, how to run tests, what sort of changes are welcome, and how not to break everything.
A public repo is not automatically a collaborative project. It only becomes collaborative when it is legible.
That was a big lesson for me with snappycart. The more I thought about contributors seriously, the more obvious it became that open source is not just about making code available. It is about reducing the friction of joining the effort. If you're into React or Nextjs, join us on Telegram and help us build a better tool!
Good contributor experience is not accidental. It is engineered.
5. I underestimated how much release discipline matters
This one became way more obvious over time.
It is easy to think the main signal of progress is writing new features. But in open source, release hygiene matters a lot more than many people admit. Versioning, changelogs, package structure, visible updates, and a clean release process all shape how serious the project feels.
People do not just look at what your project can do. They look at how it moves.
When a package has chaotic releases, unclear versioning, or no visible update trail, it feels unstable. When it has structure, clear releases, and a proper rhythm, it feels alive and trustworthy.
That matters because open source is not just consumed technically. It is judged operationally too.
With snappycart, I learned that keeping the package, demo, docs, and release flow aligned is part of the product experience. It tells people this is not abandoned, not random, and not being held together with luck.
6. I thought momentum would take care of itself
It does not. Momentum is fragile.
Even if good work is happening, the project can still look dead from the outside if there is no visible cadence. No updates. No release notes. No discussion. No signs that someone is actively steering the thing forward.
That was a hard lesson because silence can erase progress very quickly.
Open source needs continuity. Not fake hype, not constant noise, but rhythm. Small updates. Honest posts (like this one). Improvements people can actually see. A sense that the project is being maintained with intent rather than occasional bursts of energy.
For me, this also reinforced that community is not built off one good week. It is built through repetition and over time.
7. I started by thinking like an engineer instead of a maintainer
This is probably the biggest lesson of the whole year.
An engineer asks whether the package works.
A maintainer has to ask much more than that.
Can people understand it fast? Can they trust it? Can they integrate it without pain? Can they contribute without feeling lost? Can they tell whether the project is healthy? Can they see where it is going?
That mindset changes everything.
With snappycart, I started to see that the project was not just a code artifact. It was also a public product, a contributor surface, a QA playground, and a reflection of how I build things in the open. That means the responsibility is bigger than "it works on my machine" or even "the API is clean."
Maintaining open source properly means owning the whole experience around the code, not just the code itself.
Closing thoughts
A year of building snappycart in public taught me that open source is not just about writing useful software or having the complete remedy to all the devs' problems.
It is about making that software understandable, visible, maintainable, and easy to trust. Trust is the part that so many top quality npm packages are missing even if they have an excellent testing suite in place.
Some of the hardest lessons were not about engineering in the narrow sense. They were about discoverability, examples, contributor clarity, release discipline, documentation, and consistency. Those are the parts that often look secondary at the start, but in practice they shape whether a project actually grows.
One thing I am glad I took seriously early was testing and quality. But even that fits the bigger pattern: the strongest open-source projects are not just built well. They are presented well, maintained well, and made easy for other people to believe in.
That is the standard I want snappycart to keep growing into.
If you are building in open source right now, my advice is simple: do not just ship the package. Build the path around it too.
Top comments (1)
Many of us have been there. Thank you for sharing your journey with us, these are good lessons to learn from.