This article is part 2 of the “The dilemmas you’ll face when creating a web component library” series. If this is the first article in the series you’ve come across, I’d recommend giving the introduction a read first.
Photo by Hunter Haley
With your sights on using a monorepo, your next dilemma is choosing the right tool(s) to manage it.
Dilemma 1: Which tool to manage your monorepo?
The two choices presented here, Lerna and Yarn workspaces, are two popular repo management tools. I chose them based on a discussion in the Lit & Friends slack group, where several UI library authors discussed their repo’s tooling. Others exist, but might not be suited for small-scale component library development.
Lerna
Lerna’s often the first name that comes up in monorepo management, and it’s still very popular. For our use case, it ticks all of the boxes, Lerna has support for managing dependencies, running scripts, versioning, and publishing. There are more features too, but for the sake of this article series, these are the four we’ll be most concerned with.
For you, Lerna might be the way to go if you want an all-in-one monorepo workflow tool.
If you don’t want to use Lerna but need a full-featured monorepo management tool (but you probably don’t), check one of these out:
- Rush, designed for very large projects.
- Nx, a framework to help “architect, test, and build at any scale”.
Yarn workspaces
While Yarn workspaces doesn’t match feature parity with Lerna, you can use some other rad tools to pick up the slack. Yarn + Changesets + WSRun, is a burgeoning stack to tackle dependency management, versioning/publishing, and running scripts.
Note: If you use npm or pnpm, have a look to see if their workspaces feature-set has you covered, you might be able to use your preferred package manager instead of Yarn
As for oui-ui, I ended up choosing the WYC stack. My main motivator was that I wanted to explore Changesets, which we’ll bring up a little later.
It might sound like a lot to take in, but that’s fine as each tool focuses on solving a specific problem. These problems include:
Dependency management
If you’re already using Yarn to install dependencies, y’all get Yarn workspaces for free. The API surface is small and requires little more than some config changes.
Versioning and publishing
Library versioning is a scary topic (at least for me), but Changesets promotes an approach that better integrates versioning management into the development cycle. If this sounds confusing or vague, I cover versioning and publishing in a lot more detail here.
Running scripts
Yarn workspaces doesn’t have a way to run scripts across multiple packages easily. It might be tempting to roll your own bug-ridden file system traversal script, but why not pick something a little more robust?
WSRun is designed to bolster Yarn workspaces’ existing feature set with additional running modes and options.
As an aside, I should clarify that this behaviour does exist in Yarn…
TIL yarn has a "workspaces foreach <script>" to run a script against each package in a monorepo.
— Andrico Karoulla (@AndricoKaroulla) July 5, 2021
I also learnt it's only available on Yarn 2.
He giveth, He taketh away
Why not both?
Nothing’s stopping you from using both Lerna and Yarn workspaces. Vaadin is an example of a repo that uses both. Since Vaadin’s component library contains over 5000 tests, running them all takes over 10 minutes.
To counter this Vaadin uses Lerna in their test’s utility scripts to retrieve a list of the packages that have changed since branching off main. The script is used to build the test suite’s config, which tells the test runner to only run the tests from the changed packages. This saves Vaadin developers ~10 minutes every time the suite is run.
Next steps
Your repo is finally set up and you’ve got a suite of management tools at your disposal. It’s time to write some web components.