Creating a modern JS library: Introduction

Using the modern JavaScript ecosystem is, for the most part, a pretty good experience. Sure, there may be too many frameworks to count, but if you've been using JS for long enough, you already know exactly which packages you'll be using in each new project, and at worst you'll be using something like Create React App to get off the ground.

// Magic! React now works
import React from 'react';

Although using libraries is simple, creating and maintaining one can be an absolute nightmare.

The problem

You need to support as many versions of as many different platforms as possible to satisfy your users. Even if you're making a package for only Node.js or only browsers, getting exports to work properly can be tricky.

// ES Modules
import myPackage from 'my-package';

// CommonJS
const myPackage = require('my-package');

// UMD
document.write('<script src="//unpkg.com/my-package"></script>');

You want to minimize bundle size for browser users, but there are very few resources that describe the best way to go about doing so. If your library is anything more than a hundred kilobytes, your users will complain that it now takes an extra second or two to load their website on a cheap mobile device.

You may want to support TypeScript and Flow users by adding typings for your package, but it's unclear whether you should add them to DefinitelyTyped/flow-typed or include them within your package. If you aren't familiar with TypeScript or Flow, managing types as your library evolves can become incredibly difficult.

There are a plethora of other concerns too. How do you write good documentation? How do you fix bugs quickly and manage issues when they start to pile up? How do you encourage community contributions? How do you make your library easy to understand for novices?

Why listen to my suggestions?

To keep it short: I've worked on Parcel for a few months and therefore have investigated in great depth the fine details of making a package bundler-friendly. I've also published and maintained various successful packages, the most popular of which is is a high-performance compression library that reached over 4 million downloads in 6 months and is currently depended on by large projects such as SheetJS and Three.js. I've dealt with many of the problems new library authors face multiple times, so I'm familiar with the workarounds.

The solution

This series will describe the do's and don'ts of creating a JavaScript library that your users will love to use and you will love to maintain. Even if you aren't planning on creating a library any time soon, these articles will help you learn more about the JavaScript ecosystem and its many quirks. Don't worry about following any particular order; you won't need to read any entry in the series to understand the next. I hope this information will help you design your next awesome addition to the JS ecosystem!