A djangster story on Storybook

23 February 2022

The sages say change is inevitable but growth is optional. We here, at djangsters, like growing. So when we started work on a new home page for one of our clients, we opted to grow our toolset by introducing Storybook among other things. Here are our thoughts on it.

But first we need to talk a bit about Storybook. On the Storybook page they define it as an open source tool for building UI components and pages in isolation. They say it streamlines UI development, testing, and documentation.

What this means is that you build your components and can view them or test them without the need for a full blown system to be running. This is a far cry from trying to build a new component where you’d need to run the whole system, it’s dependencies, etc just to see the changes you are making.

How this works is as you create your component, you write a story for it. A story is basically just a bunch of exports that define the rendered states of your component. Stories are separate from components and do not impact your running application. You can, and maybe should, write stories for all possible states of your components. Writing stories is beyond the scope of this article but you can read more here.

Here is a simple example of what a story looks like in code:

import React from "react";

import Popover from "./Popover";

export default {
  title: "Popover",
  component: Popover,
};
const Template = (args) => <Popover {...args}>Popover</Popover>;
export const Default = Template.bind({});
export const Focused = Template.bind({});
Focused.args = {
  autoFocus: true,
};

Using Storybook, we were able to improve our productivity and developer experience once we got over the initial process shock. It was also well received by our clients who were initially understandably sceptical that adding more stuff would improve anything. So let’s break it down.

Increased Productivity

At first blush it seems counter intuitive that adding an extra step to the development process would increase productivity but that’s pretty much what we saw. Most of the components we built have an accompanying story or two. This allowed us to get the client involved early and as a result the iteration period was remarkably fast. Writing stories was relatively painless and we actually made it way faster by using IDE templates to create boilerplate stories that only needed small tweaks and updates to the arguments.

Storybook also allowed us to globally define common settings, viewpoints etc to all stories and allowed us to test how the components behave under different breakpoints. Storybook was pretty awesome and combining it with css modules virtually eliminated stylesheet clashes.

Improved testing

Storybook also allowed us to introduce loki for visual regression testing. Visual tests are a mixed bag, and while they can catch a lot of unintended changes they also have a couple of downsides, such as increased maintenance cost. But we’ll probably talk more in another post down the road.

In our case we added loki tests for each component at each breakpoint which allowed us to easily and rapidly see if some components clashed or some piece of code introduced unexpected visual changes. This also impacted how we designed our components which ended up making traditional unit tests easier to write.

That's how the story is displayed in the browser, including interactive component elements such as popovers.

Responsiveness

When building an app that will be seen by millions of people on various devices responsiveness is super important. Storybook allowed us to define our target breakpoints and switch between them quickly which sped up development considerably. Loki also allowed us to define these breakpoints and have our visual tests check on mobile, tablet and desktop all with a single command.

Compatibility

While the setup was trivial, there were some issues we ran into that I feel I should mention.

First you have to make sure that any global changes made to the app are also made in Storybook. This also indicates that you should avoid global styles in favour of component styles whenever possible.
Make sure that the app and Storybook use the same version of webpack because bad things will happen if they do not.
MSW, which stands for Mock Service Worker, but could be Magic Sea Weed (jury is still out), is your friend and will make testing components that call APIs a breeze

Client perspective

As mentioned before, our client was initially sceptical about our choice to use Storybook but that changed when we were able to demo different components for them in record time. They could see how the new homepage was shaping up and our QA team had a pretty easy time testing without needing to know anything about how to set up the whole system.

So from the client perspective Storybook in itself did not change the development process that much. However It allowed the client to see the changes early and put a focus on the visual design.

Conclusion

All things considered, we had a better time with Storybook than without it. It increased our productivity and forced us to be more deliberate with our component designs and testing. It also made the client more involved, put a spotlight on the visual aspects of the project early and inadvertently improved the way our visual specifications are handled.

It’s an amazing piece of software which you should take a look at and maybe even add to your development process.