Component Libraries

Lego Blocks

Purpose of React Component Libraries

The most important element of React Component Libraries is the purpose behind them. The holy grail of open-source software is building software that others not only consume but also contribute back to. Think about the active communities around certain projects that you use and possibly contribute.

If you are a developer building an app, you are likely meeting a need that isn’t already met by an existing app or differs so much from existing ones that it just doesn’t make sense to fork it and adapt it to meet your use case. Too often we fumble through their codebase to see what we can borrow only to realize that what we’re after isn’t clearly abstracted. If you build yet another application using a monolithic codebase, you are blocking others from leveraging your code in their codebases too.

Many developers of open-source applications have learned that the phrase, “if you build it they will come” is simply not true. In the spirit of collaboration, we want to create versatile building blocks, not monolithic React applications.


React Components

A React Component is the building block of a React App’s user interface. Components should be as simple and light-weight as possible avoiding complexity. To understand React Component Libraries let’s first look at what a React Component is.

  • An abstraction of data and logic as UI.
  • Input Props and Output UI Elements.
  • They can be atomic without dependencies.
  • They can be a composite of other atomic components:

Atomic component

const Greeting = ({name}) => ( <li>Hello {name}!</li> );

Composite component

function Greetings({names})  {
  return (
    <ul>
      { names.map(name => <Greeting name={name} />) }
    </ul>
  );
}

This is an oversimplification since there are other types and variations as React has evolved. Not to mention that, in the above code samples, parsing in the return is frowned upon due to readability and performance reasons. There are also differing opinions of philosophies and design patterns of React Components.


React Component Libraries

A Component Library is a collection of functionally related Components.

  • Solves a set of highly related real problems.
  • Has a limited scope of what it intends to solve and does it well.
  • Mostly if not all UI Element based.
  • Can be used in compatible projects needing to solve the defined problem set.
  • Core library functionality is exposed to improve flexibility.
    • Exported in the same library.
    • Abstracted via an external library.

This feels like the natural progression of Component Oriented Programming. It’s not just a trend. It will be here for a while.

How Modules Differ

Javascript modules exposed through NPM is vague and can cover any arbitrary module of code. This is definitely good. Some times modules are extracted out of existing applications. The approach of extraction can complicate the ideal standalone nature of what is intended. Starting from the opposite approach of creating self-contained building blocks addresses this from the start.

Difficulties with Extracted Modules

  • Independence from the codebase it was extracted from.
  • An abstraction of logic and data.
  • Separation of concerns.

Bright Spots

In the past, our team has successfully created self-contained modules that have been used in multiple projects. They may not be widely used outside of our organization but have nothing preventing them from being used in other projects.

What is holding them back from being used in more projects? I’m convinced that it has little to do with the performance, architectural approach, or even functionality. Limited documentation has prevented developers from easily understanding what they do and how to use them.


Awesome React Component Libraries

When researching the successful React Component Libraries, there were some common elements to the successful projects.

They are fairly attractive and easy for a third-party developer to know if it will meet their needs. The documentation quickly guides the developer through installation, setup and shows how to use them. The best ones also provide a playground to interact with the code samples. This effectively lets developers try them out without setting anything up.

Material-UI React Component Library is Awesome. What makes it an awesome component library?

High-Level Description

  • It does one thing well.
  • It is well documented.
  • It is easy to see it in action via a browser.
  • It accepts minimal uncomplicated input.
  • It manages its own concerns.
  • It abstracts complicated logic.
  • It has minimal boilerplate, setup, and config.

Priority Checklist

Some of the things that make a component library awesome seem daunting and overwhelming. It is important to prioritize a few attributes to ensure we don’t create something we end up abandoning for the seemingly easier approach of giving up.

Maintainable: is readable, organized and composed with best practices.
Abstracted: is broken down further if complicated.
Documented: has an understandable explanation of what it does and how to use it.
Styleguide: has a playground to try it out in seconds with zero-config.
Testable: has good test coverage of real-world input.
Flexible: can pass a theme, styles, or customize to flow with the consuming app.

Here’s a great writeup on some guiding principles on building highly customizable component libraries:


organized legos

Example React Component Libraries

Our team is on a journey to rethink our approach to building our React applications. Starting with a proof of concept to quickly test our assumptions, we then build out component libraries from the features and functionality of a successful PoC. Once all the required stand-alone component libraries function well enough, we build our apps from those building blocks. We were concerned that it would add to development time. Especially when it took longer than expected to complete all of the component libraries. When it came time to put them together in the application we were pleasantly surprised how quickly it all came together ahead of schedule.

The Stack

There are many alternatives to each layer referenced here. However, many of the alternatives add a great deal of complexity to the initial setup and long term maintenance which prevents it from being practical.

  • Javascript + React (functional components & hooks)
  • MaterialUI for UI/UX baseline design components
  • Styleguidist for Playground Documentation
  • Yarn for dependencies, publishing, and deploying
  • Github + NPM + Github Pages for Hosting

Our Component Libraries

Gitea React Toolkit abstracts Git API calls as visual components, with full repo and file CRUD.
Markdown Translatable provides WYSIWYG editing/translating components for markdown.
Datatable Translatable provides WYSIWYG editing/translating data tables including MD syntax.
GL Translation Suite uses the above to load, edit/translate, save directly to a Gitea server.

Are these Awesome yet?

Sadly, no. They are still lacking some of the checklist items that make a React Component Library awesome.

Maintainable: continually improving maintainability as they are matured.
Abstracted: continually being abstracted as they are matured.
Documented: each is at a different state of documentation depth.
Styleguide: nearly all components are exposed visually testable via the web.
Testable: no testing library has been selected or implemented yet.
Flexible: still some work needing to be done pending more implementations.


Where to start?

Most likely you are already in the middle of a project. It is grossly overwhelming to imagine rearchitecting an existing React application into component libraries. Much like the above difficulty of carving out modules from an existing application, it isn’t the best place to start. I recommend looking at a new feature as an opportunity to start building component libraries. Build out the new functionality as a stand-alone component library that meets the checklist. Then integrate it in your app as if it were a third-party library.

In order to see the essence of a React component library, we plan to maintain a barebones one here: Hello World React Component Library. Feel free to check it out and offer feedback using Github issues to help us improve it.

Other Resources

Here’s a great writeup that walks you through a slightly different stack: