A Storybook for BBC iPlayer Web
See it at https://www.bbc.co.uk/iplayer/storybook
Once upon a time…
iPlayer Web was in the midst of a migration to Node and React, and as you might expect, we were creating lots of React components!
We had custom-built a “living styleguide” which showed-off all our different components in various states, and for a while this worked.
…but then!
As the number of components and variants grew, we realised our custom-build solution was lacking.
- It was built by Developers without much consideration of other disciplines. Developers, UX and Product didn’t have a shared understanding of our components — what they were and how, when and where they should be used
- It was hard to navigate and had no search capability
- We had created our own domain-specific-language for writing examples of components, which was brittle and hard to work with
- We were spending too much time maintaining it
To address all these things, we evaluated several solutions:
- Improving our custom-built solution
- Storybook
- Styleguidist
- Catalog
Please note we did this evaluation in August 2018 — the above options may have matured and changed since then
We chose Storybook for the following reasons:
- The ease of migration
- An active open-source community with useful plugins and addons
- A good balance between functionality for Developers and UX
A plan emerges!
After deciding on a solution, we created a migration plan that would involve Developers, UX and Product all working together. A component audit was carried out across the whole site, and documentation for every component was written. This built the shared understanding that we had been lacking before.
This audit also allowed us to see which components or variants were no longer in use, and only migrate the things that were actually useful.
Writing the book on iPlayer
We then went about creating Storybook “stories” for all of the entries in our component audit.
The documentation we had created during the audit became Markdown files, displayed in Storybook using the Notes addon. Developers worked with UX and Product to get them up-and-running with Github PRs so they could contribute to these files in future.
We also created a “styleguide” section specifically to show off our brand colours, typography, grid and motion guidelines.
And they lived happily ever after…
…almost!
As with all things, Storybook isn’t perfect. Some of the problems we have encountered are:
Server vs. client-side rendering
In production, we render our pages server-side and hydrate on the client. Out-of-the-box, Storybook only renders client-side. This meant there were cases where our components looked great in Storybook, but behaved differently in the iPlayer React app.
Our workaround for this problem was to create a Storybook Decorator which rendered child components to a string, and then manually hydrated them after a short delay. This is something we’d like to open-source in future.
Limited browser support
iPlayer Web and the BBC in general needs to support many legacy browsers. Unfortunately Storybook does not support all of these, meaning we can’t use Storybook to test components in older browsers during development. This is something we hope will improve over time.
Plugin woes
We have seen performance issues with some of the plugins we use (most often Knobs). This is something we are monitoring, but having as few plugins as possible will means your Storybook runs faster.
Another stumbling block is plugins don’t always work well together (e.g. Knobs and JSX), but through the power of open-source, this should improve in future.
The End
The iPlayer Web Storybook is a huge improvement over what we had before. It allows Developers, UX and Product to all have a shared understanding of our components, and encourages re-use rather than re-invention.
My key takeaways would be:
- Conduct a component audit before writing your stories so you know the right things (and only the right things) are being covered
- Any component library, regardless of the framework used, is only useful if it is maintained. Make it part of your development process to create and update stories as you go — not as an afterthought
- Similarly, it’s only useful if it’s shared between disciplines. All disciplines should be involved in the initial creation but also encouraged to make additions and corrections in future
Join us
If you’re excited by the things we’re doing and you value dedicated time to learn and improve your craft in software engineering, then do get in touch as we’re always hiring. You can see all our job listings for BBC iPlayer here.
