Story Hierarchy in Storybook 3.2

My first open source contribution =)

I recently contributed Story Hierarchy to Storybook, which was a major feature of the 3.2 release. It is my first OSS contribution. This is the story of how I came to Storybook and how I developed the feature.

Love Story

I first discovered Storybook when I was looking for a living styleguide solution for the main project at work. Storybook didn’t match my needs at the time (the project wasn’t React, was 97% server rendering and 3% knockout — don’t judge and you won’t be judged 👮). So I put Storybook aside until later.

And the time has come a few months ago when we started to transition to the React ecosystem. The more I learned about React and all the tooling around it, I realized that React Storybook is the best match for us. It’s more than just a living style guide. It’s an IDE for the React components. The Holy Grail of the dev — design communication ! It’s a beam of light in the darkness of UI ignorance.

Story Hierarchy

So in our project we decided to use a single instance of Storybook for all our components. We used a namespace prefixing for each story to categorize them:

components.Button
components.Link
components.TextInput
...
...
auth.ActivateAccount.ActivateAccountPage
auth.ResetPassword.ResetPasswordPage
auth.Welcome.WelcomePage
...
...

But, nevertheless, it very quickly became a long list of stories, that is hard to navigate through. We desperately wanted to organize this list into something more structured, and as it turned out, we weren’t alone 🙏

Substories/Hierarchy · Issue #151 · storybooks/storybook

A few thoughts then came to mind: “They will probably add it soon”, “This is very useful, someone will just take care of it”. And afterwards: “Why not me !” It was a fast transition from this realization to my first pull request!

My implementation concerns were:

1. No breaking changes
2. Simple to use
3. Preserve previous functionality

The first implementation looked like this:

First implementation

After a few more conversations, bunch of PRs and several bug fixes the new UI was approved for the upcoming Storybook release. Currently it’s using a very nice open source tree library called react-treebeard, and not my clumsy implementation:

Final UI

It’s very easy to use. If you are already using a '/'symbol as the separator in the story namespace, you will get story hierarchy by default:

storiesOf('my/very/cool/MyComponent')
  .add('storyName', () => <MyComponent />);

For others, to support backward compatibility, we introduced an option to configure the separator with an options-addon:

storiesOf('my.very.cool.MyComponent')
  .add('storyName', () => <MyComponent />);
/// somewhere in expanses of config.js
setOptions({
  hierarchySeparator: '\\.'
});

The funny thing that this configuration feature was controversial, and even could’ve been extinct, but was saved by a twitter poll 🏆

Thoughts on Open Source

All this open-source sub-cultural movement in general and the github community especially was very attractive to me. We all use open source in our day to day work. A whole front end ecosystem is based on open source ! And I am not talking about frameworks like React or Angular that are created or backed by big companies. I am talking about those people that in their free time just do “something”. And this “something” is further becoming widely used by thousand of other developers. And in many cases we even don’t know to whom we have to say “Merci”… We can learn from their work, see “other” perspectives, we can explore new directions, unfamiliar technological aspects and to be inspired to achieve our new horizons.

Epilogue

How can I summarize my experience ? It was cool !! I’ve ‘met’ people from all around the world, cooperating together and doing great work. I’ve became a contributor in a very popular open source project and I am not going to stop.

For you that are hesitating, just take the first step, and don’t be afraid to be reviewed and examined. It’s good for your personal and professional growth. And of course come to contribute to the next releases of Storybook and to participate in Storybook slack channel 😉

P.S.

Special thanks to Michael Shilman, Oleg Proskurin and the rest of the storybook community for supporting me in my first moves, reviewing all of my PRs and chatting with me on slack 👍.