5 Things I Learned Building Snowpack to 20,000 Stars

Update: Part two has been posted!

My name is Fred, and I created Snowpack. If you're not familiar, Snowpack is a web build tool that fundamentally unlocked the "unbundled web development" movement that Snowpack, Vite, SvelteKit and other modern dev tools leverage today.

In this post, I want to share 5 things that I learned growing Snowpack from the initial commit to almost 20,000 GitHub stars and over 1,000,000+ downloads.

This post is meant for anyone interested in Open Source software. The highlighted lessons are directed at anyone who is interested in starting their own open source project or contributing to an existing project.

This will be a 2-part series: In this first post I focus on lessons learned creating Snowpack from scratch and finding our first set of users. In part two, I will focus what it's like to maintain a popular open source project, at scale.

Background

A couple of years ago, I started an experimental JavaScript project. Codename: Pika. It had a cute, blue mouse mascot and a fun vibe that a bunch of smaller experimental projects could live under. Its unifying mission could be best summarized as, "ESM is this cool new technology, lets do more stuff with it."

That first year of Pika may have been the most productive year of my life. I created @pika/pack (a publishing tool for npm package authors), Pika CI (a Github action that let you npm install or even import() any GitHub PR), a failed in-browser code editor, and a next-gen JavaScript CDN that went on become Skypack.

The biggest standout of the bunch was @pika/web, which let you install any npm package to run directly in the browser without a bundler (ex: react -> /react.js). You probably know this project better under its newer name: Snowpack.

Below are five lessons that I learned while growing Snowpack from its first commit to the official v1.0 release, and how we found our first set of users.

Lesson 1: Start with a personal frustration

Snowpack began as a tool to convert any npm package to a single JavaScript file that you could run in the browser. Sounds boring, right? Wrong!

This small, straightforward tool would unlock an entirely new mode of web development that is now referred to as "Unbundled Web Development". Unbundled development introduced features like instant reloads and near-instant startup time during development, using a process that wouldn't slow down as your project grows to 1,000 or even 10,000+ files. Compare this to more traditional bundled dev environments, where multi-second startup and reload times are still the norm today.

The original idea for Snowpack came out of a simple, personal frustration that I had been having at work. I was working on the Polymer team at Google, where I had helped create some alterative build tools for the (now dead) HTML Imports spec. The tool itself was lovely, but it didn't work well with npm and very few people ever used it.

I eventually left the Polymer team, but that problem still stuck in my head: Why had bundlers like webpack become the only way to use npm packages in the browser? Something has to solve the problem of getting npm packages to run in the browser, but did it have to involve bundling your entire website? Snowpack was my attempt to find out whether another path was possible.

Lesson for open source maintainers: Build for yourself, first. If you're frustrated by something, chances are other developers are too. Question everything.

Lesson 2: move fast, stay small

When you're working on a new project, you rarely know what code will be important long-term and what code is about to be deleted. I've thrown away enough code in my career to have learned that there's sometimes value in fast, messy coding. When you're starting a new project, it's okay to be a bit messy.

Internally, almost all of Snowpack's complexity was handled by Rollup. Snowpack was really just a wrapper around Rollup that would bundle only your npm packages instead of your entire website. Realizing that Snowpack could leverage Rollup internally saved me weeks (or maybe even months) of development time.

To be honest, Snowpack was just a single index.js file for the majority of its life.

To keep the project on track, I focused on a single feature: "give me a package name, and I'll convert it to ESM." This would be too low-level for most web developers. In fairness, Snowpack really didn't take off with a large audience until we added a built-in dev server and build command in v2.0. But even without the dev server, Snowpack's small v1.0 focus was enough for a certain kind of low-tooling/no-tooling web developer.

My overeall recommendation is to test your idea and get together a working demo as quickly as possible. In practice, this means four things:

1. Use existing tools! Fork a similar open source project or use an existing tool internally if it can save you time.
2. Write messy code! At the earliest stage, you probably don't know exactly know what you're building. Premature refactoring can sometimes be worse than never refactoring at all, so keep your code flexible for as long as possible.
3. Keep scope small! Don't build half-baked, half-working features. Instead, focus on doing one thing very well.
4. Skip tests! Confirm that you're building something useful before spending your free time writing tests for it. Nothing is worse than writing tests for something that you end up never using.

I know that some of this could be considered a hot/controversial take. "No testing??? Blasphemy!" All I can say is that this strategy has worked well for me over several popular projects and countless unpopular projects that went nowhere.

The obvious downside to this "move fast" advise is that it is not sustainable long-term. Moving fast means taking on tech debt, which you will absolutely need to repay at some point if your project becomes successful. As soon as you have some users who like what you're doing, you should begin to re-prioritize stability, refactoring and testing. More on this in the next post.

Paying down tech debt can be a slog. But, silver lining: If your project never takes off, then congratulations! You didn't waste any time testing something that no one wanted :)

Lesson for open source maintainers: Write messy code, keep scope small, and skip any unnecessary work until you know that you're building something useful.

Lesson 3: Fix fast

You just received your first bug report. Oh no, someone tried your project out and it broke! But what matters is that they cared enough to tell you about it.

One of the best things that you can do in a new open source project is fix bug reports right as they come in. Prioritizing fixes over everything else becomes much harder as a project grows, so enjoy the freedom to move quickly while you still can.

Sebastian McKenzie (creator of Babel, Yarn, and now Rome) summarizes this theory well:

One of the reasons Babel was successful is how quickly I was able to quickly fix bugs and release new versions. I would regularly have releases out within minutes of a bug report. This was critical during the early days when adoption was low. Being able to unblock users quickly would often make them more excited to use Babel even though they ran into a bug. -- Sebastian McKenzie, Rome

Lesson for open source maintainers: Your first users are essential. Prioritize fixing their issues over everything else.

Lesson 4: Practice good storytelling

Something about marketing always seems to make developers squeamish. Unfortunately, if you want people to use your project you eventually need to tell them about it. Even organic, viral word-of-mouth sensations tend to have a cheerleader acting behind-the-scenes.

To start, just share your project with a friend or colleague and ask them for their thoughts. It's okay if you don't hit the front page of Hacker News on day one, all you're looking for is early feedback and maybe your first users.

When you're ready to share your project with a larger audience, you have a few options for how to do it. One popular choice is to tell your story in small, visual pieces over time. This is how Sebastian built excitement for Rome for almost 2 years before its launch. Mark Dalgleish has also done a great job of promoting vanilla-extract on Twitter this way.

You can also get creative, and do something unique. Ben Holmes has been having a ton of fun recording announcement videos in front of a whiteboard for his new project, Slinkity.

With Snowpack, I decided to tell our story in one big blog post. This took some serious time to write, but gave us the space to really explain the "why" of the project. I figured that we had to make an emotion connection to our bigger goal to change the web. Even though this was just a single post, it made a big splash when it was released and then got re-shared and referenced over the next year.

Lesson for open source maintainers: Promote your work. Find a style of storytelling that fits you and your project.

Lesson 5: Ignore your haters, listen to your users

If your work ever gets posted to Hacker News, expect some haters.

If you're lucky, you can tell the difference between ignorant criticism and constructive criticism. Ignore the ignorant stuff (aka haters) but listen to the constructive feedback if you can. If someone shows that they took the time to at least attempt to understand your project in good faith, their feedback will usually have some value if you can spot.

A common constructive criticism is when someone clearly tried understand your work, but still misunderstood some key part of it. It's easy to call that person dumb and move on, but remember that clear communication is your responsibility. When someone misunderstands your work, it usually means that you could improve your README or documentation or general storytelling in some way.

Lesson for open source maintainers: Haters gonna hate, ignore them. Learn how to spot the good-faith, constructive criticism.

Main Takeaway: Support your early users

If you're starting a new open source project, the best thing that you can do is make sure that your first 10 users are happy. All of the lessons above are really just about finding and supporting these first users in some way. If you do right by them, then you've already built something meaningful.

And if this all sounds like too much work, remember that open source software has no rules. It's supposed to be fun. Building for yourself or a smaller audience is totally fine, in which case you can go ahead and ignore most of this advice.