A Practical Overview of Things Your Team Should Consider Before Adopting Storybook

In slightly less than 2.5 years of working, I have been involved in three potential adoptions of Storybook in a frontend engineering team.

The first time was a proposal by myself, which unfortunately utterly failed. It was a proposal that did not hold any business value. The second time was a year later at the same company by myself once again. This time the proposal was way better, which resulted in it being accepted. Shortly after we already started reaping benefits from it, but there were also hardships.

The third and most recent involvement was at another company and in a different role. The manager requested my advice regarding adopting Storybook due to my previous involvement with it. This adoption would have affected several frontend teams, so careful consideration was a must.

All of this has taught me quite a bit about adopting Storybook in an engineering team. While failing and succeeding in my first two proposals, I realised the importance of business value, that a company does not necessarily care about technical reasons, how to translate technical reasons into practical reasons that a company does care about, and the difficulties of adopting Storybook. The end result of the third involvement is not important (spoiler: I gave negative advice), rather it made apparent to me that I have a pretty solid understanding and overview of this topic.

In this article, I will share an overview of aspects that your engineering team should consider when deciding whether to adopt Storybook. Besides just mentioning the technical reasons, the focus is also on how those can practically translate into business value for a company. Lastly, I will also share the difficulties that can arise when adopting Storybook, so that you can either avoid or expect them early.

Disclaimer: Although I have been a Storybook maintainer in the past, this article isn’t meant as an advertisement for or against Storybook. The views and opinions in this article are mine alone, fully based on my personal experience and knowledge of Storybook, and do not reflect, represent, or relate to any organisation, employer, or company.

Local Development Speed Frontend Code

By far the most significant reason to consider Storybook is local development speed for frontend code. This is also the aspect in which I think Storybook can provide the most value for both technical and business reasons.

Under the hood, Storybook is basically a webpack server that runs locally on your machine with Hot Module Replacement (HMR). As a tool, Storybook is solely focused on frontend development. It takes your frontend code outside of the context of your application and places them in its own isolated environment.

Because of this isolation, the local development speed of frontend code within Storybook is extremely fast. It does not have to care about any backend, microservices, or any other code that is unrelated to the frontend. This way it avoids any overhead that would otherwise be introduced by that code and keeps the local frontend development speed in the order of seconds.

Improving local development speed for frontend code is by far the aspect where the most efficient and effective value can be gained for engineering teams. It is also very easy to determine whether it is an upgrade compared to your existing setup — if in your current stack the time that developers have to wait between making a small change in frontend code and being able to visually observe the change in their local development is even close to a minute, then I would strongly recommend adopting Storybook.

Especially with the current state-of-the-art developer tools, it is unacceptable for Developer Experience (DX) for local frontend development speed to be anywhere close to an order of a minute. Even if it does not sound as much per occurrence, it will add up in the long run over entire teams and all the developers with their own consequences. All of it is time that is unnecessarily wasted given the current state of the art in the world of frontend development.

Enforcing Quality Frontend Components

Storybook divides everything into so-called “stories”. The main concept is that every frontend component is individually rendered in its own isolated environment per story.

This puts a focus on making frontend components fully work in a standalone and isolated manner without being tightly coupled to other components or other code. Long-term, this will improve the reusability, maintainability, and quality of the frontend components.

Ensuring high-quality React code is not an easy task. Especially if it wasn’t part of the process and the knowledge of the team since the start, it is not uncommon to have built up technical debt in regards to this aspect. Unfortunately, this is not something that can be fixed overnight, not even with a tool like Storybook.

However, this does not mean Storybook can not provide value to codebases that already have technical debt. By introducing Storybook to a codebase, it can become that part of the process that helps developers create higher quality frontend components going forward and backwards.

Going forward, it means that new components will have to be created in this new structure that improves the quality of the code. Going backwards, old components will now also be handled more properly during refactorings due to Storybook being part of the process.

Code reusability, maintainability, and quality of fronted components are all long-term investments. A team will not immediately receive a large return of value by addressing them, but rather it will pay off in the future incrementally.

These long-term benefits are often a difficult topic when deciding whether to e.g. adopt tools like Storybook. The main problem is that there is no immediate payoff, but it does require quite some time and effort. Both of these could’ve been spent on different projects that have a higher short-term gain.

If this is the only reason you’re considering Storybook though, I would recommend you to first try out different tools with similar purposes that have a bigger degree of enforcement. While Storybook does result in a development environment that sets you up for success, it happens in a more passive way. Unfortunately, that also means that in practice it’s easy to circumvent the process which is not what you want.

Instead, having more specialised and stricter tools like ESLint, prettier, or a type checker can help you achieve this goal in a more active manner. These tools enforce rules and quality in a stricter manner, which also makes it harder to exclude them from the process. Although these static tools are not able to get you all the way, they are able to solve roughly 90% of the issues using about 30% of the effort.

If your team already has these tools in place, has already tried them out before, or is considering Storybook for other reasons as well, then adopting Storybook could be a logical follow-up step. But, to get the most out of Storybook in regards to this topic of code reusability, maintainability, and quality, it is wise to make sure everyone is on the same page. Making sure that the purpose of the tool is clear, where in the development process it fits, and how to use it is very important.

Having a Showcase of Frontend Components

Another consideration for adopting Storybook would be having an overview of frontend components for internal and external use. Because Storybook splits everything up into separate stories, it can serve as a catalogue of all your frontend components. For external usage, it would serve the role of public showcase and documentation, while for internal usage it would more fit into the role of a design system.

Storybook has built-in features that will make all of this a rather easy process. Doing this through Storybook can avoid having multiple sources of truth. Using multiple tools to achieve these features separately can easily lead to them getting out of sync and increase the maintenance burdens and costs long term.

The larger a project gets, the more difficult it becomes to keep an overview of everything that exists in the application. The same goes for the different frontend components that are already implemented. The showcase itself can also provide value for the team in this aspect.

Developers will have one dedicated location where they can find all of the existing frontend components, assuming all of them are documented in Storybook. They won’t have to rely on the maximum capabilities of the human memory anymore but rather can refer to the showcase. This way a team avoids constantly reinventing the wheel in regards to frontend components, which would have wasted time and effort otherwise, and making design decisions ad hoc, which would lead to inconsistencies in the company’s branding.

If your team does not have a showcase or design system in place, whether internal or external and is considering it next to Storybook, then adopting Storybook is a nice two-in-one solution.

Even if this is not a consideration for your team or there is no need for such a (public) showcase, then I would argue that Storybook could still be worth it if the other considerations in this article still apply to you. Based on my experience and compared to the other considerations in this article, this is by far the least determining one.

However, if your team is only considering Storybook for its showcasing feature, I would strongly recommend reconsidering. Don’t get me wrong, it’s not that Storybook does a bad job in this aspect, but it is not their most significant feature. Compared to more specialised tools, Storybook introduces a non-trivial footprint and might be an overkill for just adding a showcase to your project if you also consider the drawbacks.

Drawbacks

Obviously, there ain’t no such thing as a free lunch in the development world and the same goes for adopting new tools like Storybook. Although there are a lot of great benefits to adopting Storybook as we have seen, there are unavoidably also drawbacks. These drawbacks are not necessarily about the tool itself, but rather about the process of adopting Storybook.

When considering adopting new tools, the adoption process itself is often overlooked and we only focus on the benefits. But getting to that point where the tool provides its maximum value is not always trivial, and can make or break the value it provides to a team.

Onboarding a Team

One straightforward drawback to adopting Storybook, or any other new tool for that matter, is that the entire team needs to learn how to work with it. Despite Storybook being relatively well-known in the frontend development field, it does not always equal similar amounts of experience with it. While in essence, it is JavaScript programming and not a completely new framework on its own, it does require developers to learn how to work with Storybook specifically.

The main hurdle is not necessarily learning what Storybook is, how to use it, or how to create stories for your components. There are a lot of great resources and documentation out there that will help developers to do so. But the main challenges of onboarding a team is getting everyone to concretely understand the value of using it, how to use it in a way that will yield this value, and how to integrate it properly in their own process of work.

There is no point in introducing a new tool if nobody understands how to use it properly. There are many ways to address this, like having one knowledgable person (whether internal or external) accountable for a certain period of time, preparing resources in advance, requiring the team to spend time on learning it, and more. The details will depend on the team and how they like to operate.

The main downside is that all of this requires time, effort, and adjustments by the engineering team. In certain scenarios, spending this time and effort on integrating a new tool like Storybook compared to the usual job activities like creating features might not be an affordable decision. Another reason could be that adjustments to the team are (currently) undesired.

The main considerations to make in regards to this are how does the team onboard a new tool, how much time, effort, and adjustments it requires to do so, how aligned is the team, and whether that is currently an affordable investment to make compared to the potential benefits.

Integrating Storybook

Obviously, there are also concrete drawbacks to adopting new technology like Storybook into your existing stack. A big one would be that every related developer in the team has to learn and work with it. It also adds an extra step in the entire development process, which can have a significant impact based on varying factors.

But the biggest one by far would be the time and effort it takes to set up the entirety of Storybook. At my previous employment, I was responsible for setting up Storybook. This involved several tasks like dealing with webpack configurations, making sure all the necessary code is injected, creating examples, and the list goes on.

This whole process consumed quite some time and effort. But it’s also not possible to avoid this step or do it partly, because it’s a necessary step to make sure that Storybook can serve its role properly. If everything is not set up properly so that it reflects exactly how your application would serve in the production environment, then the components and UI in your Storybook stories don’t reflect the reality and experience of your end-users. In that case, Storybook loses all of its value in the purpose it attempts to serve.

Final Thoughts

Storybook is one of the greatest development tools available in frontend development. The open-source tool is loved by many frontend developers and has become a staple choice in a lot of frontend stacks. However, actually making the decision to adopt Storybook into an existing team’s stack is not necessarily a trivial one to make. There are a lot of factors to consider for the team, the company, and more.

To help with this, this article provides an overview of things that your team should consider before adopting Storybook. While these are based on my personal experience, this article does not focus on all the theoretical benefits and perks. Rather, it dives into the practical benefits and drawbacks that come with adopting a tool like Storybook and the business or long-term impact attached to it.