DEV Community: Vittorio Zamboni

borrow-ui: a React component library starter

Vittorio Zamboni — Wed, 15 Sep 2021 16:34:26 +0000

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, with a project website 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 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 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!

Mix Netlify DNS and other subdomains

Vittorio Zamboni — Sun, 14 Jul 2019 17:16:23 +0000

Cover image: Wicklow Mountains, Co. Wicklow, Ireland

The last time I created a blog was few years ago, and WordPress was still the most popular choice to reduce the effort and have a decent piece of functionality.
Recently, after learning some React and following the community choices, I really liked Gatsby.

Creating a static blog can reduce the complexity of the architecture: no more database, no more host running PHP, simpler configurations for Nginx.

A plus is also the possibility to use services like Netlify to host your blog's build. The main points are: it's free, it builds automatically after a new commit is pushed to your preferred brach and it manages DNS for you.

Last part is a little bit tricky if you already own a domain and you already have other applications running on different subdomains.

Deploy to Netlify

With few easy steps, it is possibly to deploy your repository directly to Netlify. A blog post in their website explains really well how to do this.
In summary, you will:

add your respository from your Netlify dashboard by clicking on "New site from GIT" (and choose one of Github, GitLab or Bitbucket);
grant Netlify's app the required permissions;
proceed with default settings and deploy.

This will generate one subdomain for you, like my-netlify-generated-subdomain.netlify.com: if you navigate to this URL your blog will be there!

DNS Provider settings

Following Netlify's guide, I set the domain name (my-domain.io) as Primary Domain and WWW subdomain as domain alias.
This worked perfectly for both of them, but unfortunately I lost access to my other applications reachable by different subdomains (second-app.my-domain.io).

I then moved my main configuration to my DNS provider built in service (I am using Gandi as DNS provider and Linode as VM provider).

I wanted to have my domain (without subdomain), blog and www subdomains to point to Netlify, but all other subdomains to point to my Linode instance (with1.2.3.4 as IP address).

This is the result:

@ 10800 IN A 1.2.3.4
@ 10800 IN MX 10 spool.mail.gandi.net.
@ 10800 IN MX 50 fb.mail.gandi.net.
@ 10800 IN TXT "v=spf1 include:_mailcust.gandi.net ?all"
blog 1800 IN CNAME my-domain.io.
second-app 1800 IN CNAME my-domain.io.
www 10800 IN CNAME my-netlify-generated-subdomain.netlify.com.

The first entry says that my primary domain has to be routed to my Linode instance (the other starting with @ are just the default example of a Gandi configuration).
blog and second-app subdomains are routed to my-domain.io;
www subdomain is routed to my netlify subdomain.

Note: you will need DNS entries to propagate before testing, this might take few hours

Configure Nginx for redirect

The first line of the configuration alone will not allow us to have our main domain pointing to Netlify's instance: we need to tell it to route to our www subdomain destination.

This is the simple Nginx configuration use to redirect:

server {
    server_name my-domain.io;
    rewrite ^/(.*)$ http://www.my-domain.io/$1 permanent;
}

If you also want to have your blog subdomain to point to Netlify, add:

server {
    server_name blog.my-domain.io;
    return 301 https://www.my-domain.io$request_uri;
}

Additional rules will handle your second-app subdomain.
A standard configuration might be like this:

upstream second-app {
    server 127.0.0.1:8085;  # stram to a different port
}

server {
    server_name second-app.my-domain.io;
    listen 80;
    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://127.0.0.1:8085;
    }
}

Netlify DNS configuration

The last step is to configure your domain in Netlify.
By default, guides tells you to set the primary domain as primary domain (obviously!).

When you do this, a www subdomain configuration is also added:

In this way however you will see some errors in the console due to our configuration, like this:

To avoid this, we need to swap the configuration in Netlify, by setting our www domain as primary domain:

Et voila'! All our DNS are setup to work correctly by mixing our host and Netlify.

Include different repositories in a create-react-app project

Vittorio Zamboni — Tue, 09 Jul 2019 22:33:25 +0000

Cover image: Bunbeg Beach, Co. Donegal, Ireland

When I started writing React applications all the codebase was under a single repository. No code sharing, no context separation.

As soon as I gain interested in exploring new solutions, I wanted to build a small dashboard at home as a playground to test new libraries, React hooks or integration with other frameworks like Vue.

Creating the Dashboard backbone was a straightforward operation: a few components for the scaffold, a basic authentication module, a Routes component with few switch cases and an apps folder to contain the different projects.

Coming from a Python/Django background, I wanted to organize my code in different repositories as I was doing with all my previous projects. Unfortunately this operation has not been as straightforward as expected.

In Python there are a couple of tools which I am familiar with and that helped me to manage this requirement: virtualenvwrapper is one of these.
One of its functionalities (add2virtualenv) is the ability to link different repositories together under the same environment and still being able to modify them without any re-installation or deployment - another option would be pip install -e from the repository folder.

Unfortunately, it's not the same with npm/yarn and create-react-app; they both allows to link but each repository must resolve it's own dependencies and have them installed.

Project structure

The currenct project structure is based on the standard create-react-app example.

package.json
src/
    apps/
        ...
    libs/
        ...
    scaffold/
        ...
    App.js
    index.js

My idea was to share the code inside libs folder to all the applications and to keep each application in it's own repository.

The first thing I tried was yarn link, but it didn't worked well. This approach assumes that the code inside the application is already packaged with it's own dependencies resolved.

Something was missing!

Avoid ejecting

The first thing I did was to eject to explore the configuration opportunities.
This is actually a good way to test out configurations if you can revert (which is pretty easy if you are under a version controlled folder).

Ejecting (and keeping each config file) however is not my preferred solution because when you go manual for a long period and starts to customize a lot of things you can't easily go back, and you need to maintain the dependencies one by one.

On the opposite side, create-react-app does not allow you to modify the configuration files in order to keep the project as generic and standard as possible.

Few solutions has been suggested on the web: switch to razzle.js, use next.js, rethink the project structure with lerna (the monorepo approach - one owner only) or fork create-react-app.

In order to keep the project simple I didn't want to introduce next.js or razzle.js. I hope to reuse my dashboard code for other projects and using a framework might not be the best solution.

Fork

Of all solutions I opted for forking create-react-app repository, following this guide.

On react-scripts package, I added the following lines to config/webpack.config.js.

saving the content to a variable instead of returing the configuration directly:

// remove the return statement and save the content
-  return {
+  let config = {
     mode: isEnvProduction ? 'production' : isEnvDevelopment &&  'development',

checking if a file called customWebpack.config.js exists in the project root folder and, if it has a modify function, override the config with the function's result:

     // our own hints via the FileSizeReporter
     performance: false,
   };
+  console.log('Checking for custom webpack config');
+  if (fs.existsSync('./customWebpack.config.js')) {
+    console.log('  -- custom config found!');
+    const customWebpackConfig = require(path.resolve(
+      __dirname,
+      '../../../../customWebpack.config'
+    ));
+    if (customWebpackConfig.modify) {
+      config = customWebpackConfig.modify(config, { webpackEnv });
+    }
+  }
+
+  return config;
};

This similar approach is used by razzle (in a much fancier way).

On my project then I had to do three things:

Adding a customWebpack.config.js file:

module.exports = {
    modify: (config, { webpackEnv }) => {

        // List of external repositories that have to be added
        // to the testers to being correctly processed       
        let externalRepositories = [];
        if (process.env.REACT_APP_EXTERNAL_REPOSITORIES) {
            externalRepositories = process.env.REACT_APP_EXTERNAL_REPOSITORIES.split(',');
        }

        // Set a list of repositories required for this project
        const projectRepositories = [ 
            'my-test-repo'           
        ];

        // Validate that all repositories have been set before starting
        projectRepositories.forEach(repo => {
        if (externalRepositories.filter(eRepo => eRepo.endsWith(repo)).length !== 1)
            throw new Error(`==> Repository ${repo} must be included in ` +
                `.env.local REACT_APP_EXTERNAL_REPOSITORIES variable`);
        });

        config.module.rules[2].oneOf.forEach((test, index) => {
        if (test.include) {
            config.module.rules[2].oneOf[index].include = [
            ...(Array.isArray(test.include) ? test.include : [test.include]),
            ...externalRepositories,
            ];
        }
        });
    }
    return config;
};

add the repositories to REACT_APP_EXTERNAL_REPOSITORIES in .env.local file:

REACT_APP_EXTERNAL_REPOSITORIES=~/repositories/my-test-repo

and finally created a link

ln -s ~/repositories/my-test-repo dashboard-ui/src/apps/

Final considerations

This approach is not a standard approach in JS/React applications/modules development, but allows me to have the advantages I have when I develop python applications:

every module is in it's own repository: different repositories might have different visibility, permissions, follow different merging strategies and have it's own wiki (or even different team);
changes are picked up immediately by CRA without extra compile steps;
the application is bundled from one single point (however, this is also a disadvantage in terms of CI/CD, but node_modules can be cached to speed up build operations).

There are also some disadvantages, but for my pipeline they are not a problem:

as mentioned, one change in a single repository requires the full application to be bundled again. A mixed approach can be adopted by adding the external repositories only in development leveraging webpackEnv variable, building single modules with their own pipeline;
setup for a new repository is not straightforward: we need to create a link and add the repository to an env variable (this might be automated as well), and we need to do this in order to build.

Can you see a simpler way to achieve this result? You think this is a terrible approach? Please share your opinion!