1M downloads of an open source project

Recently, a co-maintainer of Hashids tweeted that we've crossed 1 million downloads, so I figured this might be a good time to write a few lessons learned / thoughts from the experience.

Hashids is a small open source library I wrote a few years back that converts numbers into ids (so instead of websites showing a product id as 745_2381 in the URL, they can show zPwiXnZ). It can also convert those ids back to numbers.

hashids example

Since then, the library has been ported to 36 programming languages, it's been on Hackernews, lots of cool websites use it (like CodePen), it's doing 80k installs per month in PHP, 50k/mo in JavaScript and another 50k/mo as a Ruby gem.

It was an amazing experience, and I thought I'd share the good, the bad and the ugly:

  1. It's going to take longer than you think

    I thought development would take a weekend, maybe two. It took 3 months. Granted I did only work on this after work and on weekends, but still — a few months for ~350 lines of code felt like forever. I only finished because I thought someone else might find it useful too.

  2. It has to solve a real problem

    A company needed this, and we ended up using something else that was already available. But it wasn't good, so I thought it could be better. It has to be a real problem. If the reason is "but this library uses promises instead of callbacks", who cares?

  3. Not everything is a success

    I've made more useless stuff than I can count, most of it due to the previous point. At least 15 completed commercial products and many projects + websites. They all took time; they all failed; I learned.

    I also never believe those "how we've made bagillion dollars with $0 advertising" or "here's a unicorn I made in 1 month" stories. They either got lucky, or they're bullshitting.

    Also, keep in mind you only see other people's highlight reel, not their blooper reel.

  4. Pre-release checklist
    • Did you pick a good name? It'll probably stick that way forever (in retrospect, I should've done a better job at this).
    • Release under your username or an organization's? If it's a platform or part of something bigger, create a separate Github username for it so you can invite others and have multiple repos.
    • Does it have a clear description?
    • Are there install instructions?
    • Is there a simple example?
    • What about the demo link? Is it clearly visible in the description?
    • Does it have those pretty shields.io badges? 😍
    • Does it have proper README, LICENSE and CONTRIBUTING files?
    • Any pitfalls or common gotchas you should mention?
    • What about a link to full documentation?
  5. If someone hates you, you've done something right

    A short time after I released Hashids, a guy on StackOverflow cried bloody murder because I used the word "hash" in the name of the library (hashes cannot technically be decrypted). No amount of logic could convince him this wasn't a security library. He eventually went away to troll on something else. Another time a Google developer decided to make it his mission in life to bash on Hashids.

    The world is standing by to tell you you're wrong. That's why when you see a post on popular sites announcing something new, the first/top comment is usually a negative one.

    Building stuff is hard. If people are not constructively helping, pay no attention.

  6. Open source community is amazing

    Shortly after I released the library, a developer from UK cc’d me to say he ported it over to Go. How cool.

    A bit later, another dev from Sweden asked me if I needed help with Ruby. Then came Python from Munich. Java from China. Elixir from Ukraine. C from Bulgaria.

    Later, another developer offered help in maintaining the PHP version. I gave him full access to the repo. He cleaned everything up, improved a few things, and brought the library up to latest standards — all probably twice as fast as I could've done it, and better too.

    If you see rockstars offering help, give them the tools.

  7. Marketing marketing marketing

    When I finished the first version, I submitted it to several websites, a newsletter and answered relevant questions on StackOverflow. That got the word out to people that found it useful. As a developer, it was also a learning experience on how to market (which will be useful when you make commercial apps).

    Some ideas to get you started:

  8. Deal with your mistakes transparently (and hopefully fast)

    If all goes right, you will fuck up. Mistakes happen, you make bugs, you introduce those bugs into projects that aren’t yours. 😖

    Nothing to do but fix them fast, acknowledge you messed up, learn from your mistakes and notify whoever's involved. Don't hide it.

  9. Do customer service for your project

    Every now and then I'll still favorite a tweet about Hashids. It's my way of letting people know I'm here if they have questions and the project is still actively maintained.

    hashids twitter

    People also often open new Github issues, create pull requests, ask questions or just ping to give suggestions. I try to respond in a timely manner (it does not always work out that way). But there's definitely nothing more discouraging than finding out your questions aren't being heard.

    Expect to spend some time in maintenance mode.

  10. Be patient

    Hashids is actually kinda old. First commit was in April 2012.

    hashids traffic

    All good things take time to mature and come around. If your project doesn’t find traction initially, don’t get discouraged. Just learn from it, enjoy the ride, and be persistent.

    Fail often enough and you have to succeed eventually, amirite?

How can I improve this page? Tell me.