Let’s say you’ve written a super handy little bit of JavaScript. Nice! Well done, you. Surely, the world can benefit from this. A handful of people, at least. No need to keep this locked up. You’ve benefitted from open source tremendously in your career. This is the perfect opportunity to give back!
Let’s do this.
You’re going to need to chuck it into a GitHub repo. That’s like table stakes for open source. This is where people can find it, link to it, see the code, and all that. It’s a place you can push changes to if you need to.
You’ll need to pick a license for it. If the point of this is “giving back” you really do need to, otherwise, it’s essentially like you have the exclusive copyright of it. It’s somewhat counter-intuitive, but picking a license opens up usage, rather than tightening it.
You’ll need to put a README in there. As amazingly self-documenting you think your code is, it isn’t. You’ll need some plain-language writing in there to explain what your thing is and does. Usage samples are vital.
You’ll probably wanna chuck some demos in there, too. Maybe a whole `/demos/` directory so the proof can be in the pudding.
While you’ve made some demos, you might as well puts some tests in there. Those go hand-in-hand. Tests give people who might use your thing some peace of mind that it’s going to work and that as an author you care about making sure it does. If you plan to keep your thing updated, tests will ensure you don’t break things as you make changes.
Speaking of people using your thing… just how are they going to do that? You probably can’t just leave a raw function theThing ()
in `the-thing.js`! This isn’t the 1800’s, they’ll tell you. You didn’t even wrap an IIFE around it?! You should have at least made it a singleton.
People are going to want to const theThing = require("the-thing.js");
that sucker. That’s the CommonJS format, which seems reasonable. But that’s kinda more for Node.js than the browser, so it also seems reasonable to use define()
and return a function, otherwise known as AMD. Fortunatly there is UMD, which is like both of those at the same time.
Wait wait wait. ES6 has now firmly arrived and it has its own module format. People are for sure going to want to import { theThing } from './the-thing.js';
, which means you’re going to need to export function theThing() { }
.
So what should you do here? Heck if I know. I’m sure someone smart will say something in the comments.
Whatever you decide though, you’ll probably separate that “module” concern away from your authored code. Perhaps a build process can help get all that together for you. Perhaps you can offer your thing in all the different module formats, so everybody is happy. What do you use for that build process? Grunt? Gulp? Too old? The hip thing these days is an npm script, which is just some terminal commands put into a `package.json` file.
While your build processing, you might as well have that thing run your tests. You also might as well create an uglified version. Every library has a `the-thing.min.js`, right? You might as well put all that auto generated stuff into a `/dist/` folder. Maybe you’ll even be super hip and not check that into the repo. If you want this thing, you grab the repo and build it yourself!
Still, you do want people to use this thing. Having the public repo isn’t enough, it’s also going to need to go on npm, which is a whole different site and world. Hopefully, you’ve done some naming research early, as you’ll need to name your package and that must be unique. There is a variety of other stuff to know here too, like making sure the repo is clean and you’ve ignored things you don’t want everyone to download with the package.
Wait what about Yarn? Isn’t that the new npm or something? You might want to publish there too. Some folks are hanging onto Bower as well, so you might wanna make your thing work there too.
OK! Done! Better take a quick nap and get ready for the demands to start rolling in on the issues board!
Just kidding everything will be fine.
re: README‘s.
Yarn uses the same registry as npm, so that’s one step you don’t need! Hooray, now there’s only 34 instead of 35!
I think of this the same way that I think about framework fatigue – yes, it’s hard, but the problems probably aren’t with the system. They’re with the social obligations we impose.
Most of the steps you’ve listed above are optional, unless you really want people to use your library – ie. you’re not just being purely altruistic, you have a vested interest in seeing your work reused.
Doing more stuff is better, but not required, in the same way that setting up build tools that minify your website is good, but the site will load without it.
If you want your code to be open source, you need to do two things:
put it publicly somewhere (Github/Gitlab is preferable, but even Dropbox is fine if you don’t know Git).
give it a license (unless you have a compelling reason, just use MIT)
That’s it. I’ve forked and used code from Open Source libraries that only did that. It was work, it would have been better if they had documented stuff. But it was good enough – and I was grateful that at the very least I had code I could look at to help me solve a related problem.
If you’re building an Open Source “product” and you’re trying to compete with an existing ecosystem, then yeah, you probably want unit tests, and a website, and documentation, and minified builds, and a code of conduct. And you’ll want to make sure your code is optimized, and compatible with IE 11, and on and on and on.
Because at that point you’re competing with other projects – and you’re putting resources into fixing very real problems that people have.
But it’s not required. You don’t need React or special build tools to set up a website for your local library. You don’t need unit tests to Open Source your hackathon project. Sharing code is valuable, and there a ton of things you can do to make it more valuable. But it’s still much better to release your source code poorly then it is to not release anything at all.
Or just make a gist…
Do you therefore feel that it can just be more trouble than its worth?
Yes you can :P When the code is simple enough (e.g. some simple helper function) then it’s probably easy enough to rewrap into whatever the user of the library needs. If anything, such code probably plays nicer with third party code than anything else.
If the code is complex (e.g. a library) then either it’s already encapsulated properly or it likely has a smelly design if it isn’t the case.
Or just post it, add a readme, profusely thank the first person who clones it, and politely ask if they might contribute back one of the above.
Lather, rinse, repeat, and in 15 years you have the Drupal community.
My recommendation is to use nwb. It will easily allow you to build vanilla JavaScript modules in all the formats you mention, or React/Preact components with tests!
Well, all those are great but I believe the ONLY things you really need is to tell in a humanly-readable kind of way “what it is”, “what it’s for”, “where can it work” or maybe “who it is for”…
There are so many “projects” and so many volatile open-sourcers we can’t even guess!
I was actually wondering about a few of these things. Nice work as always, Chris!
Hi Chris.
Great list! Personally I love when a library is well documented with examples for all the configurations on CodePen. This is what I did on my very own Siema.
One word about exporting. Webpack comes with bunch of helpful configurations options on
output
object. Aoutput.library
to export named variable andoutput.umdNamedDefine
to export it as a UMD build (Universal Module Definition). An example…Thank you for this! I was dreading writing AMD, CJS, and UMD for my libraries. Webpack to the rescue.
I’d also suggest these steps:
• Ask a friend for a code review before you share your repo with the world. (Once it’s shared, it’s hard to make big changes without messing up someone’s customized use of your thing.)
• Find someone who needs this functionality as much as you do and share the maintenance and development. Making friends is the whole point of open source, and, if you’re the sole maintainer, you’ll have no one to laugh/cry/commiserate with when your issues list hits 1000 open issues.