Getting Started

Welcome to borrow-ui guide!

In this guide you will learn how to get ready to start using the components and the other utilities included in this project.

Before you start, make sure you have a NodeJS environment ready. We will use yarn to manage the monorepo.

You can use borrow-ui in different ways:

  • by including the ui/src folder in your project;
  • by using this project as a base;
  • by installing borrow-ui directly from the npm registry.

Goal of this project

borrow-ui project is intended to be a quick-start for a full controlled set of components. Installing and using from npm registry should be done only for a quick look of the components.

Why maintain your components kit?

Often, when we start a new project, we can't or won't use 3rd-party UI Kits such as Material UI, UI Kit or React Bootstrap; each of these is great and is ready to use, with a lot of documentation and examples. However, there is almost no control over the components that are given. Small fixes or changes, or systematic improvements are controlled by the Kit maintainers and might take a lot of time before they are available.

borrow-ui allows you to start and maintain your own Kit. Each component:

  • is minimal and can be used as a starter for more complex scenarios;
  • is consistent with other comonents (code styles, tests, nomenclatures);
  • is tested;
  • has a documentation file written for Storybook;
  • usually has no 3rd party dependencies*.

If you plan to use your application for a long time, the kit you are relying might change version few times with breaking changes, so the documentation will no longer be up to date, new bugs will not be fixed (in your chosen version) and there will be no new components.

On the other side, if you maintain your own component kit you will need to write a lot yourself (you can always wrap 3rd party headless components, like the formidable react-select), but you will have full control over the life of the kit.

* except for flexboxgrid2 and react-media, which are easily swappable with others, and the ones used in forms: react-select, react-dropzone, react-day-picker and date-fns.

Tools and dependencies

Beside the components, borrow-ui offers tests (in form of unit tests) and documentation. As soon as your project is renamed as you wish, you will have this same documentation available. It is strongly recommended to invest time documenting your components, as well as testing them.

Styling is done with scss and few variables can help to customize the Kit.

Installation

As mentioned above, there are different ways to install and use borrow-ui.

  • include the ui's src folder directly in your existing project: this will allow you to import and use all the components directly;
  • use this monorepo as a base for your project, with storybook and examples already setup;
  • by installing it from npm registry (yarn add @borrow-ui/ui or npm install @borrow-ui/ui).

All the installation procedures are explained in the next sections.