The Dilemmas I Faced When Building a Component Library

♪♪♪ I'm Indrico, and this is my talk, The Dilemmas I Faced When Building My Component Libraries, or also known as The Perfect Sandwich Does Not Exist Unless You're Eating A Sandwich Made by JakeTheDog. So, you're feeling hungry, and you want to make a snack. So maybe you want to make a sandwich. So you start by grabbing some Hovis white bread, or maybe that's Wonder Bread for those in America. For this, you go to Sainsbury's and get some premade egg mayo. You then cut up some delicious raw white onions, throw it on top of the sandwich, and then squirt on heaps of ketchup. And congratulations, you have yourself a delicious treat.

Now, if you've played Legend of Zelda, Tears of the Kingdom, and you threw those ingredients into a pan, you'd probably see this little screen pop up. It's dubious food. It's too gross to even look at. A bizarre smell issues forth from this heap. Eating it won't hurt you, though, probably.

So, let's say you work for a high-end restaurant, and you want to make a fancy sandwich. Well, you can't just serve your customers the sandwich that we just made. You have to make something a little nicer. Instead of just your plain white bread, maybe you go over to a bunch of different bakeries, test their loaves, maybe you go by mouthfeel and texture, and you decide on the perfect sourdough. You can't just squirt any old ketchup on that sourdough. Instead, you make your specialty famous homemade relish. Again, raw white onions, yeah, they take a second to cut, but if you really want to take the time and make something delicious, you're going to caramelize them. That does take a lot longer, but your users, sorry, I mean your customers, will appreciate the time and effort that you put into making those caramelized onions.

But that's just not the only thing that you need to consider when you're making your gourmet sandwich. You have to consider things like the monetary cost to make the sandwich, the dietary requirements of your patrons, maybe you want to cater for celiacs, or maybe dairy-free folks, but that's something that you need to decide the best thing for you. But then you also need the skills and equipment to make that damn sandwich. And a wise man once said, something quick and dirty might work for you now, but it won't be suitable in every situation. And so the same goes for building a component library. I find that building a component library is a really rewarding part of being a web developer, but you can't just throw any old code together and hope that it solves everybody's problems. There's so much to it than that. So this talk is a culmination of all those little choices that I've had to make when building my component libraries. So here we are, the dilemmas you'll face when building a component library. So I did realize that when building a component for a team, or a company, or for the open source community, you'll face a bunch of dilemmas.

Now, these are little choices like, well, maybe not little, actually quite big choices, whether to use a JavaScript framework, you might not need to, how to consider accessibility within your testing strategy, which is something you'll certainly want to do, and whether to use a monorepo to manage your library of three components, and spoilers, don't. And making the wrong decision early on can have lasting headaches for you, your teammates, and your end users. So it's important to just consider these things. And some of these choices that are run through might be things that you can change a little bit down the line. Maybe you realize after doing a little bit of research that an alternative is better than others are more like one-way doors, where if you make a mistake or choose the wrong choice early on, it can have lasting consequences much further down the line.

For this, before we go ahead, let me introduce myself. I'm Andriuko Kirula, and I am a full-stack developer, and I've been in the game for nearly a decade now. And I do specialize in the front end, and I built a few component libraries, mainly for companies, but also a few for fun.

I'm currently on the hunt for my next contract role. So if you need a front-end developer or a full-stack developer, then I might be your guy. So let me talk about some of the component libraries I've built for companies.

At my last role in Anima, we had a bunch of different front-ends that were built in React. And so it made sense that we created a component library in React that we then used across those different front-ends. That meant that all of our front-ends looked and felt the same way. And the same goes for the component libraries that are built at Trin or contributed to at Health Hero.

And as for the ones for fun, I take a slightly different approach from it. A lot of the time I do it to scratch a creative itch or to learn a technology on a deeper level. And you can see my favorite one that I made is A2K, which is a Windows 2000-inspired component library. And you can see here that the different components that it exports kind of gives your interfaces this cool retro feel. And I built a couple of standalone component libraries. And I've also built a React component library called BeautifulSkillTree. I haven't updated it in a while, but it seems to have a bit of a cult following.

Cool. So why do I build component libraries? Or why should you build component libraries? The business-y answer is that building a component library allows you to build your interfaces faster by using reusable components. And then that allows you to have a consistent visual language across your different interfaces. But then on a more personal level, I prefer writing... Well, I like to write component libraries because it allows you to understand a given ecosystem better. If you want to get better at writing React or Svelte, then a really good way of doing that is by writing some complex components in that framework.

The same goes for if you want to learn web components. A great way to do so is to build components. It also helps you improve your understanding of common UI patterns. If you've tried to build a select menu or you've tried to build an accordion from scratch, you'll probably soon realize that it's not as simple as it might seem. You've got a lot of sub-components that you might need to build, a lot of tricky interactions and edge cases that you need to accommodate for as well. And on a meta level, if you want to get better at developing and publishing a library, the best way to do so is to develop and publish a library. So great, we've spoken about the benefits of building a component library.

But it's not so straightforward because as I mentioned earlier, there are a bunch of different decisions that you need to make if you want to make a component library that's suitable for your users.

For this, and these are just some of the questions that I have come up against when building my own component libraries. And I actually pulled this list from a GitHub article I wrote, which details all of my experiences across these different questions. So if that sounds like something that's interesting to you, then awesome, because this talk will take a handful of these questions and dive deeper into those. But if you want to check out that GitHub article and contribute your own experiences, then that's awesome. So please go ahead and do that.

So the first one we'll look at is whether you should write your components from scratch or build your own. So the first question is whether you want to build your component, using a library. And a good way to understand whether that's a good idea or not is to look at all of the different frontends that you plan to use your component library with. If they all use the same framework, then maybe it's a good idea to write your component library in that framework. If you have a Vue frontend, a Svelte frontend, and a React frontend, then maybe consider using Web Components, because you can use them in lots of different frameworks. So we've already kind of hit a fork in the road here. We have like whether to use a Web Components for a component library, whether to use a specific framework, and there are also other options too. And this is something that you're going to see a lot when you build your own, is that answering one question actually often leads to lots of other questions.

So let's take like the left fork, where you use Web Components. Okay, great, but there's still now a whole series of questions that you need to answer. Do you want to write Vanilla Web Components, which is a lower level API, a little bit more complex, but you get complete control over how they behave? Or do you want to use a helper library like Lit or Atomico that kind of smooth some of the trickier edges and give you things like reactivity out of the box? Or do you want to use an existing library like SheLace or WebAwesome, or actually the same thing, but where they offer you a suite of fully functioning components that you can install to suit your needs? And then you kind of find that if you chose to build in a framework, you have like a similar set of questions too, whether to write your components in Vanilla React, whether you want to use a library like Radix or React ARIA that give you unstyled components, but deal with a lot of the more complex interactions for complex UI patterns. Or maybe use a library like Mui or Shadtian, where you get fully functioning components, and then you have the option to customize them.

And so these are kind of more implementation details. But if we take a step back, you'll notice some parallels between those two questions, namely what level of abstraction are you comfortable with dealing with? So different levels of abstractions deal with different problems. Like solutions to different problems. So going from the highest level of abstraction, you might use a component library with functional components that already look great. And so for you as a developer, you have to deal with a lot less complexity, and then you can also build something or deliver something much more quickly. And then again, if you use functional components that are unstyled, you don't have to deal too much with the inner workings of the components and how they behave. You just need to make sure that they look exactly as you need them to. Then you take another step, like go a level lower, and maybe you're using a library to help you write components, but you still need to implement all of the component functionality yourself, or you write components from scratch without a library. And again, that is the kind of most complex out of them all because you're dealing with things like styling and interactivity, and maybe the actual lowest-level APIs that the browser offers. So I have made the wrong choice on several occasions, and I am probably going to make the wrong choice in the future as well. There have been times where I've made components from scratch, and the challenge with that is now I own the complexity of the interactions.

There have been times where I've made components from scratch, and the challenge with that is now I own the complexity of the interactions. And so it makes it harder if you're working in a team and you're building everything from scratch because now you have lots of different folks coming in and tweaking things, and maybe the original vision has gotten muddied, so now you've got this Hero component where you have a button, a link button, and a link all in the same component doing lots of different things. And so now I've got these complex implementations with mixed concerns, and there are going to be heaps of edge cases. And so sometimes it might make more sense to offload all of that complexity to an open-source library, and maybe that library has a team that's dedicated to solving a single issue, and that single issue is building a component library. And that component library may have been used in tens of thousands of different projects, so now you have all of the usage statistics to inform how that component library behaves. And so you don't have that maintenance burden that you might have if you were to build everything yourself. But it's not necessarily the best thing to always offload the complexity to someone else. There are different reasons to choose those level of abstractions. So maybe you want to learn a framework on a deeper level. Well, then maybe it's a good thing to try and build everything from scratch. You also need to consider who's going to be contributing to your component library. If it's just you, then go ahead, and maybe things are a little bit messier, you don't mind that a little bit, but if you're working with a team or you expect open-source contributions, then you need to be a bit more methodical about how you write things and whether to make it as easy as possible for those to contribute.

Cool, so that's the first question we covered, and it pretty much led to another dozen or so questions, but I'm hoping that you have a better understanding about the kind of introspection that you need to do if you want to start building your first component library.

So the next question we're going to look at is whether to export your library as a single package or as scoped packages. And so what do I mean by this?

Well, if you've used component libraries in the past, maybe Material Web, you will know that if you run npm install Material Web or whatever component library, you'll have access to the entire component suite, and this is really useful as a consumer because if you're consuming this kind of component library, then you just need to run the update script against one package to get the latest version of all the components. You can easily look at the changelogs.

And if you're managing the component library yourself, it's way easier to just manage a single version and then publish a single version. For this, and I'll contrast this with scope packages, and this might, well, this is like a Radix UI where you might want to use, say, their select menu and maybe their popover menu components, and so you would need to run npm install Radix UI, select menu, and then npm install Radix UI popover. So installing a single package gives you access to a single component. And so this is useful if you just plan to use, say, a single, one, or two, or very, very small number of components from a given library.

And I've got an asterisk here about reducing bundle sizes, which is kind of maybe not strictly true, which I touch on a little bit later, but as a component author or a library author, you have a lot of flexibility as to how you version and publish them. You can publish them, version them independently so each component has its own version, or you can version them together so that whenever you release, you bump the version for all of them and maybe only some of the changes, only changes are made to some of those components. And we'll talk a little bit about that latter option in a second, because I find that really annoying as a consumer. I've worked with independent packages that were versioned together.

And even though the Gatsby plugin system wasn't necessarily like a component library, what you would, if you've built with Gatsby in the past, you would probably use a dozen or so of these different first party plugins, and they were all versioned together against the same version. And so what would happen is if you went away from your computer for a couple of weeks, came back and tried to upgrade your dependencies, you'd see a whole list of Gatsby plugins that needed to be updated, and so when you go through each change log, because I don't like just upgrading everything and hoping for the best, you'd often see this, like version bump, version bump, version bump, version bump, oh, slight change to the readme, version bump, version bump. And you would have to do that across a dozen or so, if not more, packages. So that's a bit of a pain. But it's not so bad if you're using a small number of components and they're versioned independently.

Now, as a publisher, I have actually dealt with publishing scope packages. And I talked about my A2K component library a little earlier on. And to be totally honest, it was a mistake and I regret it massively. So the purpose of A2K was to let people build an entire interface using a suite of retro style components. So why would I make my developers or my consumers install each component individually? It just makes no sense. If they plan to use A2K to build an interface, they're probably likely to use all of the components. So making someone install 12 components is absolutely kills the X and increases friction. And I'll probably say adoption would have been a bit higher if I published everything as a single component. On top of that, managing independent versions is a bit more complex. So you need to set up your repo like a model repo. They need to have a specific workflow so that you can publish components as they change and make sure that the versions are incremented based on the change.

So you need to set up your repo like a model repo. They need to have a specific workflow so that you can publish components as they change and make sure that the versions are incremented based on the change. And I do like, I use change sets for this. And I like it as a tool, but it makes, or like having all of these tools into your repo just makes it way harder to deal with. So try and opt for the most simplest option if you can. And I did talk about one-way door problems earlier. And I think this is a good example. If I wanted to change A2K now to be a single library or a single package with all of the components, I would have to ask everyone that uses it to then completely change the way that they're using the component library. And not too many people use it now, but if you're building a component library that's used by thousands of different developers, you're kind of asking a lot of them. And so it's best to make sure that you've nailed this problem or at least take what you feel is the best approach at the time. So it's definitely worth considering.

So what would I do now? So for starters, I would offer a single package for the reasons I mentioned, I would also write the package in ESM only. One thing I didn't mention, cause it's kind of part of a different dilemma is that I published A2K as ESM, CommonJS and UMD. And this is, again, cause I wanted to make it as available as possible so anyone could use it. But like in retrospect, it's a web component. They're probably gonna be used on the web. ESM is web friendly. So it just makes sense that I only publish as ESM unless I really, really need to use CommonJS for whatever reason. For this, on top of that, because ESM, like ES modules are statically analyzable, if a consumer just wants to use a single component, then their bundler should be able to tree shake any of the unused components away. So you don't need to worry too much about bundle sizes. And what I talked about a little bit, why I would use a single package, because A2K does have a consistent design language. So it didn't make sense for it to be all separate. So whenever I start a new component library, I do ask myself these four questions. And I've already touched on them to some degree already. But if you say yes to all of them, again, opinionated design language, avoiding complexity, expecting users to use multiple components and happy to version everything together, then it's probably best to just throw everything in a single package. But if you say no to one or more of these, then it might be better to try and publish them independently.

Cool. So this is the last element that we're going to run through in this talk. Should I use tooling to build and or bundle my component library? So we're kind of two sides of this. There's building and there's bundling. And when I say bundle, I mean, running things like, you know, combining everything into like a single bundle in that maybe you're concatenating, minifying, transpiling. Whereas building is just turning some, like running some steps to make your code browser friendly code browser friendly.

So let's look at bundling first. Should I bundle my library? And I'm going to say no because it's super annoying. I have been on the receiving end of dealing with a bundled library. And the reason why it was a pain for me is because the optimizations that that library made weren't in line with what I needed to give to my end users. So this library that I've used in the past, and I really liked it. And I think the world of the team for this. They, well, we use it pretty heavily. We found a few bugs here and there, which is to be expected. But what we would do is we would debug the node modules and then we would maybe run patch package if we needed to make a few small changes while we waited for our pull request bug fixes to go in. And that was all well and good because the code was basically just standard ES modules as the developers had written it. But then we updated it one day and they had decided to bundle their code. So instead of being like lots and lots of different files, there was just like this one common JS file that had all of the code bundled together. And it made it an absolute pain to debug. And I kind of asked them to not do that, to revert their changes. And after a few weeks they did. And it was a much more pleasant developer experience as a consumer.

So just to kind of reiterate, don't assume the optimization needs of your consumers. Just publish as browser-friendly codes that if they want to run like a build list setup, then they won't need to make any changes to your code. Build steps are a little bit different. For this... You might want to use different tools to make your development experience a little bit better as a library author. You might use TypeScript because you like the static analysis that it gives you. You might like to add types to your code as well. SAS gives you things like maybe functions that aren't available in CSS.

And Stencil allows you to write components in their given syntax, which then compiles down to vanilla web components. But the challenge with these are that these aren't browser-friendly technologies. And I'm gonna say something quite shocking here, is that code that isn't supported in the browser won't work in the browser. And so what that means is that if you want to use TypeScript, you're going to have to add a compiler to your repo to ensure that the code that you write actually gets converted to browser-friendly code. And so if you're writing a TypeScript component, before that code is rendered in the browser, it needs to go through that compilation step. And so there's this level of friction between writing the code and actually seeing it work. And that may be fine for you. Maybe that tradeoff is not a problem. If you're working alone and you really like TypeScript, that might be a good option. But if you're working in a team or you're working on an open-source project, then you might realize that anyone that wants to contribute has to understand how everything works. And it could just make things a bit more complex. The same goes for having a compiler, even if it's TypeScript, Stencil, whatever, is that there's now this black box, which could be a single point of failure. And so you might end up wrestling with this tool if it's not working in the way that you expect it to. And I remember reading an article by the developers of Shoelace. And he said that he used Stencil initially to build the Shoelace web components. But then after a while, he just kept hitting his head against the compiler and ended up just moving over to Lit because it was a much simpler tool that allowed him to write his web components. And another example is the team at Svelte. They initially wrote the library in TypeScript, but they opted to instead remove TypeScript, go back to vanilla JavaScript, and write their types in JSDoc. And this was useful because it made it a lot easier for people to contribute.

And now, the thing that you might want to be, you might want to consider is to not overcorrect. It's easy to go from having heaps and heaps of different, build tools in there to then remove everything and just ensure that you write your code as a browser will read it and avoid anything else like tests and types or whatever. But the good thing is that you don't need to avoid all of those cool things. Instead of writing TypeScript and running the bundler before you run your code in the browser, you can instead of write your JSDoc types and have a TypeScript step literally just before you publish to generate types from your JSDoc, and that way you can publish your types for your consumers to use. So you don't need to completely remove all of or forego all of these useful tools. You can just make it so that it's as easy as possible for others to contribute to.

So my approach, you probably guessed that I like to keep things quite simple now. I have gone from one end of making things as complex as possible, and I've now kind of like swinging in the other direction. I like to lean on the browser's capabilities, but I'm not completely in the camp of like nothing else whatsoever. A good example is that you become a lot more familiar with the tools in the browser. Like I think CSS is great, and it's super capable, particularly in the last few years. So I haven't even needed to use SAS or CSS modules. And maybe in the past, sort of just defaulted to SAS because it's what I was used to. But leaning, becoming more familiar with the fundamental tools might open your eyes that they're better than maybe you give them credit for. The same goes to TypeScript. I like using it in my applications, but I prefer to use JS Dock when writing my libraries.

Cool. So I have covered about three different dilemmas, but in the GitHub article I mentioned earlier, I do cover a lot more. So if you'd love to learn a little bit more, then please check it out and maybe even contribute your own stories. That's everything from me, and I appreciate you watching, and have a good day. Bye.