Looking for the perfect boilerplate to create your awesome react components library? Guess what? there isn’t one.

I learnt it the hard way by discarding every library boilerplate out there in the wilds of JavaScript. Setting up a library from scratch may seem like an uphill task but benefits of understanding the process easily outweighs the efforts involved. Besides, you probably don’t want to justify your decisions to your boss by saying, “I just followed some random guy’s article and boilerplate”.

However, if your library is a one off adventure, nothing that’s going to scale and you can sleep peacefully not knowing the nuts and bolts, you may skip to bottom of article for links to some good library starters. And yes, they aren’t perfect!

If you find the terms such as ES5, ES6, ES2015, Compilers, Bundlers, taken from alien language? React glossary should make you feel at home.

Enough rambling, let’s start with the real stuff!

Most important part of figuring out the unknowns correctly is to list down the set of questions to ask. Once you have the right set of questions, finding answers should be easy and Mr. Google doesn’t disappoint.

“One to rule them all”?

Deciphered version, is this library going to contain a lot of stuff and might even have lot of dependencies? If so, you may need to convert the library into multiple smaller scoped packages just like modern libraries. You will often see this pattern at work, @scope/my-package} . This approach provides your users with the liberty of installing and using only the required packages. You don’t need to buy the whole shop when all you need is a single item out of it.

Counting the packages and thinking about the pain of managing the infrastructure? Worry not, Monorepo has got you covered. If that sounds alien to you, Monorepos stand for a single monolith repository containing all the related projects or in our case multiple packages. Monorepos are hot these days and already being used at tech giants such as Facebook and Google. Gone are the days, when it was necessary to shake your head upon the word ‘Monorepos’. A reason behind that might be the sophisticated tools to manage or we can always blame the trends.

Need more information? See the links at bottom.

How do you serve?

There are quite a few ways to do this and no straight answer. Correct answer totally depends upon your users and how they are going to use your library.

More importantly, who do you serve?

User has a modern application build setup with compiling and bundling tools integrated such as babel and webpack to build their applications. Setups like create react app are prime example of this. User doesn’t have any build setup and will likely to use your library as a single script file. Reminds of good ol’ days of Bootstrap and JQuery. Users creating applications for IE — Stay away from such people, they are lethal, they strike in stealth and you never know what hit you.

Majority of your library users belong to the first category if you are reading this in 2019(I see you time travelers).

What do you serve?

Serve it as raw as it comes — serving your code as it is may sound interesting and easier but beware these stunts are performed by professionals who train for years so don't try this at home. Cook it per the recipe — Compile your flavor of JavaScript in to the ES5 standard and serve the code. And yes no bundling, because your user will be using a bundler in his application anyway. Moreover, your library can have have multiple modules as entry points so users can selectively include modules they need resulting in better optimizations.

For instance, import Button from ‘@material-ui/core/Button’; ensures you import the stand alone Button component instead of whole monolith package.

This is the recommended way of serving and consuming libraries.

Ah yes! its opinionated but keeps things simple and doesn’t need people starting out to start digging in to advanced topics such as Tree shaking and all. Wrap it up for unseen — Let’s get the compiled output from the above step and bundle it in a single file. This approach serves all the different user types we discussed earlier. Needs a bit more work to setup and it brings irresistible Rollup vs Webpack vs ‘x’ showdowns in to play. Point being? Think again, if you really need such controversies in your life!

Defining the unseen!

How to accommodate users who don’t have any build setup and will include the library directly in html file as a script?

You need to bundle your library in a single file because of usability and ease of distribution purpose. Caveat involved in this approach is simple, your user’s application size can increase substantially because they will be loading the whole package when they all the needed was a single `function` out of it.

To top it off, if your user also works on legacy browsers such as Internet Explorer or older versions of chrome, blows my mind if some one really is, you will need to change the target module system from `ES` to , one of the legacy module system.

All the module systems, buzzwords if you aren’t acquainted, such as CommonJS, AMD, UMD, are simply patterns designed to work around the lack of native modules. Now that we have native ES Modules, are they the definite answer?

In most cases, yes! They are supported in all the modern browsers, secondly, our users will have a proper build setup so they can easily consume our code and compile in to whatever form they need depending upon end users demographics.

See links at the bottom for more information on module systems.

How about the weaponry, Sarge?

Angular or React? This write up works as a sleeping pill as well! What JS flavor? Vanilla, coffee, typescript, clojurescript, reason everything ultimately compiles to JS and there is no other way around it at least for foreseeable future. Choose wisely, this will affect your team’s productivity in a big way. As far as recommendation goes, you can’t go wrong with Typescript and there is a reason Typescript is popular in Library scene. What CSS flavor? We chose JSS and are happy with it, please do check out it’s feature page but you can’t go wrong with other options such as sass or less either. How do you develop and showcase your component? A demo app will do just fine but you should go for Storybooks especially if the library is to scale, they go a long way in making development productive. Interactive showcase with interactive components deployed somewhere is a treat for your users. It’s simply awesome. How do you test your components? If you are just starting out and have limited information on the topic, I would recommend you to check out Jest as it’s also developed by Facebook and it’s experience really is ‘delightful’ as they put it. Going for Monorepo, eh? You should integrate Lerna for managing your Monorepo . Trust me, it will make your life a whole lot easier. Forgetting about the docs? You could leverage the storybooks for this however if you are to document a huge API and have a lot to write, an independent documentation site is the way to go.

We used Ocular from Uber to generate a static site from markdown files plus its pretty easy to setup and getting started. This really is some magic from Uber.

Is your library public?

Yes? Your path is straightforward. All you need to do is to publish it on npm, it’s no rocket science. A quick google search or digging through npm documentation should do the trick.

No? There are quite a few ways you can deal with it:

Buy npm private accounts for your organization, your users need to have private accounts as well Create/host your own private registry, there are quite a few options available for this such as cnpm, verdaccio Use third party services such as gemfire or myget, these services allow you to host your packages privately in cloud

Show me the code!

A hands on tutorial is in works, stay tuned.

Useful Links and References

Technical Reviewer: Umar Ashfaq

Cover Image designed by: Aiza Chaudry