In this project we will set up a mono repo with:

A workspace build system
Storybook
Typescript
Visual regression tests
Jest testing
Prettier formatting
Two simple React components
A Build Test Lint pipeline

Here is the completed Github project: czearing/my-ui-library: An example React UI library (github.com)

Why do I need a UI library

A broad rule of thumb in good UX is Jakob Nielsen’s 10 usability heuristics. The 4th heuristic consistency and standards specifically applies here. Users shouldn’t be put into situations where something unexpected hits them. When the button on the sign in page is abnormally large compared to the rest of your site, users notice that. Having a UI library helps developers maintain heuristic #4 by enforcing standards. As your project scales and more apps and developers are introduced this becomes even more crucial.

Requirements

Make sure that you have the following installed beforehand:

Walkthrough

Let’s start building the UI library.

1. Create directory

Start by creating your project directory folder. Create a new directory and call it whatever you like. I’m naming mine my-ui-library. Then open up your code editor. I personally prefer vscode.

2. Initialize the package.json

Open up your terminal and run the following command to generate your package.json:

npm init -y

3. Configure your package.json and setup yarn workspaces

Now we are going to introduce a few things to our package json now:

Install nrwl (cli, jest, nx cloud, and tao)
Install prettier
Setup yarn workspaces

Assuming you understand how to install dependencies (if not here is a tutorial), I’m going to focus on explaining yarn workspaces.

Yarn workspaces allows you to install all of your dependencies in one place. For an example if we were to introduce a new package json in a button component:

- packages
    - button
      - package.json

- package.json

Running yarn from the root would install dependencies in the button.

We are planning on introducing an apps, packages, and scripts folder so we could add something like this to our package.json:

"workspaces": [    
  "apps/*",    
  "scripts",    
  "packages/*"  
]

Here is my package json for reference:

https://medium.com/media/d3b2a71fd286c155c3497ad39cb0d010/href

4. Setting up Prettier

Prettier helps you save time while writing code by automatically formatting. Setup a .vscode directory with your configuration. Here is what mine looks like:

https://medium.com/media/50d79d2490f800f89f281033d8e6422a/href

Next you should make sure to include a .prettierignore in your root directory so you aren’t formatting unnecessary files (node_modules). Here is what I use:

https://medium.com/media/3d2484283e0ad7c1482a0419520237e9/href

Optional: You can also setup a pre commit hook here to ensure all files are formatted before they are committed. Prettier has a helpful tutorial if you are interested in doing this.

5. Setting up Scripts Package

Next we are going to setup a shared script package. This will hold most of our dependencies (React, Typescript, Jest) and our configurations.

Start by creating a new private package.json
Name it “@…/scripts”
Install dependencies that you plan to share in all your component packages (react, typescript, jest…)

Here is what I’m planning on using:

https://medium.com/media/5a79bc2c29c21168bf249e54004b4a67/href

6. Configuring Typescript

Now we are going to configure a typescript preset for all of our components. Create a tsconfig.base.json file in scripts with your preset. Here is what I use:

https://medium.com/media/f1321f37e87dcc54daed476983aebc2d/href

Now we are going to enable our preset in the root and scripts directory. Add a tsconfig.json in both the root and scripts directory to extend off the preset. Be aware that the path will change based on the location of the tsconfig. Here is what it could look like in the root directory:

https://medium.com/media/b3526bb28235405dd64f166ecab6c8e4/href

7. Configuring Jest

Now we are going to configure Jest for unit testing. Add a jest.config.js file to your scripts folder to use as a preset. Here is what I use:

https://medium.com/media/ad3e2ffda4465a5b20b702d532632027/href

8. First component!

Now that we have the package setup it is time to finally add our first component!

Add a new packages directory in the root to organize your components.
Create a new directory called react-button within packages.
Create a package.json within react-button.
Create a new src folder within react-button.

- .vscode
-scripts
...

- packages
    - react-button
      - src
      - package.json

- package.json

5. Configure your react-button package.json

https://medium.com/media/a55195704e642e2ad4252af0e2aa4073/href

6. Add the tsconfig.json preset

https://medium.com/media/ee3a6704413d6cc7f635b973ae8fde08/href

7. Add the jest config preset

https://medium.com/media/7aa6d19d7c77d1a713788a070063f60b/href

8. Add a Button.tsx file within your src directory.

- .vscode
- scripts
...

- packages
    - react-button
      - src
        - Button.tsx
      - jest.config
      - package.json
      - tsconfig.json

- package.json

9. Add your Button component within the Button.tsx file

This can be anything you want. You could even do something like this:

import React from 'react';

export const Button = () => {

return <button>Hello World</button>;

};

10. Add a Button.test.tsx file.

- packages
    - react-button
      - src
        - Button.tsx
        - Button.test.tsx
      - jest.config
      - package.json
      - tsconfig.json

11. Add your tests.

In this example I created a basic snapshot test.

https://medium.com/media/fce753e65818687e864658edb17e9e4e/href

12. Create an index file and export your component

- packages
    - react-button
      - src
        - Button.tsx
        - Button.test.tsx
        - index.ts
      - jest.config
      - package.json
      - tsconfig.json

The index.ts should look something like this:

export { Button } from './Button';

Great job for making it this far! 🎉 🎉 🎉

Next we are going to set up storybook so you can actually see the component you made.

9. Storybook

Storybook is a helpful tool for building UI components and pages in an isolated environment.

Let’s set it up.

Install @storybook/react in your root package.json devDependencies
Create a .storybook directory in root and react-button.

- .storybook
- scripts
...

- packages
    - react-button
      - .storybook 
      - src
   ...
      - jest.config
      - package.json
      - tsconfig.json

- package.json

3. Add a main.js file in both .storybook directories.

4. Add this in the root main.js

module.exports = {

stories: [],

addons: [],

};

5. Add this in the react-button main.js

const root = require('../../../.storybook/main');

module.exports = {

stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],

addons: [...root.addons],

};

6. Set up a stories directory in react-button/src and add a Button.stories.tsx file.

- react-button
      - .storybook
      - src
        - Button.tsx
        - stories
- Button.stories.tsx
      - jest.config
      - package.json
      - tsconfig.json

7. Configure a story within Button.stories.tsx

https://medium.com/media/fb956e8371e3a606577fa7c43a87e2bc/href

8. Run yarn start-storybook within the react-button directory

You now have a storybook for you Button component! Next we are going to look at what adding a new component looks like.

9. Adding a second component

Since we already built the first component, adding a second component should be a smooth process.

Duplicate the react-button
Rename it to react-checkbox
Update the package.json name
Update the name of the files to Checkbox (Button.tsx becomes Checkbox.tsx)
Update the component to a checkbox. Example:

import React from 'react';

export const Checkbox = () => {

return <input type="checkbox" />;

};

6. Update the index.ts and Checkbox.stories.tsx files to reflect the new component

7. Run yarn start-storybook

You now have a Checkbox component!!!

10. Publishing to Github

Before continuing on to setting up the CI and NX prepare and publish the repo to Github. Make sure to add a .gitignore so the lib, lib-commonjs, and node_modules, … don’t make it into your repo. Here is the .gitignore that I use.

11. Setting up NX and NX Cloud

Think about how you would validate that all of the packages in your repo can build? One way you could do this is to go into each package run build, go into the next, and so fourth. Once the instructions have all run we now know that the code can build. NX makes this possible. NX Cloud also allows for the result of the script to be cached to save time.

Setting up NX is as easy as running a single command:

In your the root directory of your project run npx add-nx-to-monorepo
If you are interested in using NX Cloud to speed up your build select yes.
Push Github and try running nx run-many — target=build — all in the root directory

12. Circle CI

Now that scripts can easily be run in all of the monorepo, creating a build test lint pipeline is possible. There are a number of potential tools to be used to set this up. In the tutorial I will show how to use CircleCI as they are very affordable and simple to setup.

Navigate to https://app.circleci.com/ and sign-in using Github.
Set up your project.

3. Select fast

3. Select hello world for a sample config

3. Delete hello world and add a configuration. This is what I like to use:

https://medium.com/media/3588e2358bf5405ec16ba3b236a18698/href

4. Press the commit and run button.

5. Verify it passes and merge the pull request on Github

6. Add a branch protection rule for the repo under settings/branches.

13. Chromatic

Chromatic is visual regression testing tool. Visual regression tests involve rendering the actual code in a browser in comparing snapshots of previous behavior. It also includes a number of other helpful features such as DOM diffing and the ability to share your Storybook stories online.

Add monorepo support to storybook (running yarn storybook-start at the root should work for all packages). One way to do this is to update the .storybook/main.js file in the root directory to include:

stories: ['../packages/**/src/stories/*.stories.tsx']

Navigate to Chromatic: Storybook deployment, review, and test and create an account using your Github.
Select the add project button.

3. Select choose from Github.

4. Select your project and follow their helpful tutorial all the way through.(you may need to configure your package.json with some new scripts such as build-storybook).

"scripts": {

  "build": "nx run-many --target=build --all",

  "lint": "nx run-many --target=lint --all",

  "test": "nx run-many --target=test --all",

  "start": "start-storybook",

  "build-storybook": "build-storybook",

},

Now that chromatic is setup we are going to create a Github action to run a check for each pull request.

14. Chromatic Github Action

Create a new file in .github/workflows called chromatic.yml

- .github
- workflows
    - chromatic.yml- scripts
- packages
- package.json
...

2. Add the following content to the file.

https://medium.com/media/12be8c0057c4776b54ef8588b9377967/href

3. Add your CHROMATIC_PROJECT_TOKEN environmental variable to github actions by navigating to settings/secrets/actions and selecting create a new repository secret.

(if you are unsure of what it is equal to, go to your chromatic project and select manage/configure and copy the project token)

4. Merge the new action in to your Github repository.

5. Update your Github branch protection rules to include both the new action and UI Tests from chromatic.

Your checks should look something like this now:

Conclusion 🥳

Congrats for completing the tutorial! You should now have a fully function component library that is ready for development. Some things you can do from here to improve it are to add some more components, investigate versioning automation, and investigating a styling and theming system.

Here is the completed Github project: czearing/my-ui-library: An example React UI library (github.com)

Articles

How To Build Your Portfolio Using NextJS, TypeScript, Vercel, and CircleCI

How to Truncate Text using CSS

How To Build a React Component Library Using NX, Storybook, Chromatic, and CircleCI