Sharing React Components with Lerna

At NearForm, we've mostly become accustomed to creating well-architected applications with components in React. We've been doing it for quite some time, but we see the same stumbling block over and over: how do you effectively share front-end components across various projects within an organisation?

Where do you start? Do you create a repository for each component? One repo for everything? A toolkit?

For me, this is where the monorepo approach steps in. It's a convenient way to manage your small distributable pieces of code without the overhead of many repositories and the setup involved with that. That's not to say that a monorepo doesn't have its own drawbacks but we're able to alleviate the majority of that pain with a tool called Lerna .

In short, we have one repository with all our code. We set up a containing repository for all our packages to live in which allows us to manage a single setup at the top. By setup I mean testing, linting, build processes, continuous integration and the like.

This allows our packages to stay extremely small and manageable and any change in our setup can just be reflected in a single place.

To get started let's initialise Lerna and NPM.

Now let's initialise Lerna with lerna init --independent . This will create a lerna.json and package.json file. In this case were using Lerna in independent mode which allows us to individually manage the version of each package.

There is also a default mode called fixed/locked which uses a single version number in the lerna.json file to publish packages when they've been updated, this method is what babel use in their Lerna setup and is less involved than manually bumping versions for each changed package.

The mode you choose will come down to personal preference and what you're using the Monorepo for. Independent mode allows me to control each package as I choose and prevents me releasing major versions unnecessarily, this might not be a concern depending on what you're publishing.

We're going to use Lerna as a home for a set of React components wed like to share. For this were going to add a few common libraries like Babel, Storybook and Jest in, a copy of our package.json is below:

Now we add in a .babelrc file:

We're now going to add some basic Storybook configuration to allow it to find our packaged stories using glob-loader . Create a directory called .storybook . Within that we need to create two files: config.js

stories.pattern

We're ready to start putting packages into our Lerna repo. Start by creating a packages directory which is the default Lerna directory. This can be changed in the lerna.json configuration if you want a different name for your packages.

To save time, clone down our example repository . Open the examples directory and copy our test-package into your packages directory. If you've got some extra time, feel free to create your own package similar to ours!

The example package contains a small React component with a Jest test and a Storybook story.

So an obvious drawback of having all our packages in one repository is having to go into each package and npm install as the Monorepo grows this would quickly become unmanageable and time-consuming. Lerna has various built-in commands to ease the drawbacks and bootstrap is one of them!

Simply run lerna bootstrap at the top level and Lerna will automatically install the required dependencies for each package as well as resolving internal dependencies by creating symlinks.

Now that we're set up and have an example package to test with, we can start to see the benefits of Lerna. Let's add some scripts into our package.json :

Once you've added the scripts, try running each of them! Storybook should automatically detect any stories within our packages allowing us to have a live documentation of our components for everyone to see. Equally, Jest will do the same, looking in our packages for any tests that need running, we can even add coverage with a few lines of code.

Another great feature of Lerna is the exec command. Essentially Lerna allows us to run a command within each of our packages. In our case this is really useful for building our components ready to be published onto npm.

Heres an example of how we go about compiling each of our React components:

Demonstrating this on a single package is probably fairly underwhelming but as the Monorepo grows you can easily see the benefit of being able to do this in a single line of code. Again if your build process changes it's in one place.

But I want a different build process for each package? - Simple, just use lerna exec npm run build and define a custom build script within each repositories package.json !

So, we've got a great setup that's all managed in one place, we have a great developer environment but the final piece of the puzzle is using publish .

Publish is another great time and hassle saver, it automatically pushes up all of your packages to Git and NPM, specifically Lerna documents it by doing the following:

If the post hadn't already given it away, I'm really onboard with Lerna. I see the huge benefits of having a Monorepo and all our code in a single place and, from a developer perspective, it feels like a great step towards making our own lives easier when it comes to maintaining everything.

The Monorepo architecture combined with Lerna resolves the majority, if not all, of the drawbacks that come with maintaining and using a Monorepo and its something I'm keen to see become more commonplace.