borrow-ui: a React component library starter
Tags: react, github, testing, javascript
Published: 2021-09-15 16:34:26

Hi all! 
My name is Vittorio and I am working as full-stack engineer in Nuritas, an AI/Biotech company.
During the last few years, I have worked on several projects (small and big) where I had to learn few things, remembering others and combining different domains. 
Almost always these projects required a UI and given my familiarity with React I focused on bootstrapping small POCs/MVPs that had less dependencies as possible (sometimes it was actually a requirement to not rely on any of the big players like Ant, Bootstrap, Material-UI). 
While working on these projects I setup a base that allowed me to share previous knowledge and custom additions. With slow pace I finally put it together in a presentable way, releasing it as a repository to _copy_ or as npm package.

The name of the project is `borrow-ui` and it is available in [GitHub](https://github.com/borrow-ui/borrow-ui), with a [project website](https://www.borrow-ui.dev/) as well.


## Goals of borrow-ui

The goal of this project is to create and maintain a UI component library base for creating POCs/MVPs or new projects (i.e. dashboards), with the following requirements:
* being extendable in an easy way: adding a new component should be an easy and repeatable operation;
* consistency: the overall experience (both for the user and the developer) should be consistent between components and packages;
* well documented: the components should be clear and simple, and they need to have a good documentation and examples;
* being tested: when your components are supposed to be the core of _something_ (a dashboard, a website) you just don't have time to test each single scenario manually on every change;
* should have less dependencies as possible, but still be as much complete as possible without reinventing the wheel (for example, the excellent `react-select` is used);
* work as self-documentation for configuring the most common scenarios (i.e. bundler, integration with CRA, etc);
* being open source: sharing and contributing is the key of being part of a community, and giving something after all the taking is a great feeling!
* being a playground to learn new things: before starting it, I had no idea of the complexity of creating and maintaining a component library, or how to create an npm package, a monorepo with Storybook, etc.

The component library can be either integrated in an existing project or as a monorepo starter. The project website has a [getting started](https://www.borrow-ui.dev/getting-started/getting-started) section that can guide in both ways. If you are _really brave_, there is also an npm package with all the components of the library ready to be used.

## Technical details (and some comments)

Few keywords first: `monorepo`, `yarn 3`, `rollup`, `react-testing-library`, `storybook`, `mdx`, `CRA` and `Next.js`.

borrow-ui started a couple of years ago as a personal project, and given the different requirements the first idea was to organize the library and the actual app/website in different folders. Monorepos are the best solution I could found and initially borrow-ui integrated `lerna`. Unfortunately, the `lerna` project [seems to be unmaintained](https://github.com/lerna/lerna/issues/2703) and the issues arose when working with `yarn` and some deep interdependencies. For this reason, `yarn 3` with workspaces have been chosen: it's more verbose but it does the job.

The library itself has a small number of components which are tested by the amazing `react-testing-library` ("how easy to use is it?!" <- rhetorical question). The coverage of the core components as of today is ~97%. The test suite is run when a pull request is created, using the Travis-CI open source program.

The library is styled with SCSS, following BEM convention. 
Each component also has a Story file written in `.mdx`, and shown using the `docs` plugin in the `documentation` package (a Storybook installation already configured to source the components).

The component library is bundled with `rollup`, which was the lightest choice at the time but still complete for all my use cases. 

## Repository content

The monorepo contains the main package with all the components, called `ui`, and other three small packages:
* `documentation`: a configured Storybook which allows to develop new components very easily, and also produces a good technical reference;
* `dashboard`: a small example of an application created with create-react-app (CRA), which I use as a base and demo for dashboards before starting new projects. It has two apps, one created to show how to use the components of the library and the other one as a "scalability" example. The code is extensively commented; as a side note, I use this dummy project to show how to organize components and files in a React project;
* `website-next`: an example of how to integrate the library in a Next.js app, how to configure it to use `mdx` and how to add additional custom components (all this is explained as blog posts in the demo itself).

## Challenges (so far)

Creating and maintaining a component library can be really difficult and tiring.
The common scenario (of any library) is when you add something and that slightly changes - or breaks! - something else, but this can be mitigated with a good test suite. Or similarly when you need to change the APIs of a component, and you have to update the dependent applications: reducing this changes is a must for a library.
Choosing other libraries and components to integrate is one nice part of it, while the less-nice part is how to make them look consistent with other components. Two examples are `react-select` and `react-day-picker` which have excellent APIs but their style does not match with the library one (few times I was tempted to change again and again the UI library instead of adapting the components, but that desperation went away in the end).
The biggest challenge has been maintain the library up-to-date and consistent. If you need to use different components in the same page, they should look (relatively) well together, otherwise the eye is not satisfied and the functionality compromised.

## Next steps

Where to go from here? 
The two next steps will be creating a dark mode (and possibly treating it as a theme rather then just a binary option) and the conversion to Typescript (or maybe a separated branch?).
Both things are new to me and it will take some time and research before, so any suggestion is welcome (double appreciated if in the issues section of the repository)!
A better roadmap is available on the website, or in the milestones section of the GitHub repository.

I really hope this project and my trial and errors can be useful to anyone that will have to start a similar journey, even to borrow some configurations or a single component. 
It has been hard & funny to work on this project, and I am excited to moving it forward to make it more useful.

Thank you for reading all this long post!