adjoe Engineers’ Blog
 /  Frontend  /  Storybook 7.0
decorative image in green with blue elements
Frontend

Documenting & Testing React Dashboard Components with Storybook 7.0

In my last article, I explained how to write stories for both simple components – like buttons – and more complex state-based components – like filters and dropdowns – with the help of Storybook.

In this article, I’ll show you how to document your own components with Storybook’s Autodocs feature and MDX. I will also give you a small introduction to Chromatic’s visual testing capability. 

But first, let’s talk about Storybook 7.0.

What Is Storybook 7.0?

The Storybook team released a new version at the beginning of April – Storybook 7.0. This version introduces a lot of changes regarding how you write and document stories. If you want to upgrade, the Storybook team provides you with a clear step-by-step tutorial on how to do so. It also gives you the option of migrating your components to the new story format CSF3.

If you don’t migrate your components after upgrading, they will still function in the old CSF2 format. However, you will see deprecated warnings.

In order to make sure this article is up to date with the Storybook 7.0 changes, I’ll work with the new documentation changes introduced in the update. This means you’ll need this version of Storybook to fully utilize these features.

How Do I Document My Components?

There are two ways to document your components in Storybook. You can use the Autodocs feature to utilize prop commenting and automatically generate documentation for your components. Or you can use MDX to customize the documentation page of your stories.

Let’s use our Button component from my last article:

interface IButtonProps {
 variant: 'text' | 'outlined';
 onClick: () => void;
 children: React.ReactNode;
}
export const MyButton: FC<IButtonProps> = ({ variant, onClick, children }) => (
 <Button variant={variant} onClick={onClick}>
   {children}
 </Button>
);

This is the corresponding story file that utilizes the new CSF3 format:

const meta: Meta<typeof MyButton> = {
 title: 'MyButton',
 component: MyButton,
 render: args => <MyButton {...args}>My Button</MyButton>,
};


export default meta;
type Story = StoryObj<typeof MyButton>;


export const Outlined: Story = {
 args: {
   variant: 'outlined',
 },
};


export const Text: Story = {
 args: { variant: 'text' },
};

When migrating to Storybook 7.0, during the automatic migration steps, the Autodocs feature will automatically be enabled by adding the following code to the main.js Storybook file.

ocs: {
   autodocs: true
 }

This will create the new docs substory for every component’s story.

Screenshot of the Docs Substory for the MyButtons Story
Screenshot of the Documentation of the MyButton Component

The Autodocs feature will generate the documentation story and show you all the stories created and the component’s properties on one page.

With the help of prop commenting, you can enhance the props’ descriptions.

interface IButtonProps {
 /** The variant of the button. Outlined Buttons do have a border around the child. */
 variant: 'text' | 'outlined';
 /** The onClick function that will be executed when clicking on the button */
 onClick: () => void;
 children: React.ReactNode;
}
 /** Default Button Component for interaction. */
export const MyButton: FC<IButtonProps> = ({ variant, onClick, children }) => (
 <Button variant={variant} onClick={onClick}>
   {children}
 </Button>
);

As you can see, I’ve added comments above the properties in the TypeScript interface, as well as above the component itself. These comments will automatically be added to the documentation.

Screenshot of the added comments in the storybook documentation.

You can also add comments above the substories in the story file to give them a subheading.

You can use MDX to fully customize your stories or documentation. MDX utilizes a mix of Markdown and JSX so that you can generate your own stories and documentation layouts. One common use for MDX is to create overviews of icons, typography, or color options in your project. 

To create new MDX pages, create a new .stories.mdx file first. When using VSCode, I recommend installing the MDX plugin, which supports highlighting for the file. Every MDX file needs the meta tag for Storybook to render it correctly. The Storybook framework comes with some tags that you can import via @storybook/blocks.

{/* MuiIcons.stories.mdx */}


import {Meta} from '@storybook/blocks'


<Meta title="MuiIcons" />

As an example, we can create a small list of icons from MUI.

{/* MuiIcons.stories.mdx */}


import { Meta, IconGallery, IconItem } from '@storybook/blocks'
import { ArrowBack, ArrowForward, ArrowUpward, ArrowDownward } from '@mui/icons-material';


<Meta title="MuiIcons" />


# Mui Icons


<IconGallery>
 <IconItem name="ArrowBackIcon">
   <ArrowBack />
 </IconItem>
 <IconItem name="ArrowForwardIcon">
   <ArrowForward />
 </IconItem>
 <IconItem name="ArrowUpIcon">
   <ArrowUpward />
 </IconItem>
 <IconItem name="ArrowDownIcon">
   <ArrowDownward />
 </IconItem>
</IconGallery>
Screenshot of custom story for mui icons.

How Do I Test My Components with Storybook?

When it comes to our Storybook setup for the dashboard project we’re working on at adjoe, we publish our stories on successful deployment to our production servers.

We have enabled UI tests (which you can do in the Manage section of the Chromatic project options) that will be run automatically on the Chromatic project when a new Storybook build is pushed. These UI tests will create snapshots of each story created and compare it to the latest accepted baseline version of the component. 

When the test detects changes in the visual snapshot, or detects new components, it will set the status of the build to “Review.”

This means the build is not automatically accepted as the latest Storybook. A developer needs to manually review the change and either accept it or deny it.
If all changes are accepted, the build is marked as successful and is then the new baseline. All components of the latest accepted build will be used as the baseline for future UI tests. The permanent links to the library and Storybook will subsequently use this build.

If any change under review is denied (it does not matter if one or more are denied), the build is marked as failed. It will not be used as the new baseline, and new pushes of denied components will automatically be set to review, even if there are no changes to them.

Screenshot of chromatics review page with unreviewed changes.

At adjoe, we are currently thinking of utilizing Storybook’s UI test feature in addition to unit tests as an alternative to snapshots. You can set up merge requests in a way that they cannot be merged if the UI test is failing. This could either be due to the build being under review or a component being denied.

You can achieve this in various ways based on if you are using a linked or unlinked project in Chromatic. Unlinked projects are used by self-hosted GitLab repositories or enterprise providers. They cannot utilize direct merge request integrations with Chromatic, but have to use their CI settings to block merges.

Summarizing Storybook

Now you should have the tools to implement Storybook in your own React projects and utilize its visualization capabilities, documentation, and testing features to improve your daily development workflow.

If you want to learn more about Storybook, you can find a lot more information with examples on the official website. Especially, about the new Storybook 7.0 update.

I hope my articles about Storybook gave you a good introduction to the key features of Storybook’s framework. You now should have some useful examples to help you start working with it in your own projects. Thanks for reading!

Technical Account Manager (Boston) (f/m/d)

  • adjoe
  • Playtime Supply
  • Full-time
Every great app out there deserves to be connected with the right users and the right revenue streams. And adjoe will give this to them. adjoe is a leading mobile ad platform developing cutting-edge advertising and monetization solutions that take its app partners’ business to the next level. Our unique ad unit Playtime has made us one of the fastest-growing ad platforms and top-ranking user acquisition sources for app publishers worldwide (ranked #1 for growth in the AppsFlyer Index).

Home to an advanced tech stack, powerful financial backing from Bertelsmann, and a long-term growth mindset, adjoe is part of the AppLike Group ecosystem. A hub of disruption and thought leadership in the app economy, with a driven and dynamic workforce to be reckoned with. 

Our US HQ launched in the beginning of 2023. Since its inception the US office has played a critical role in adjoe’s massive year-over-year growth, and we’ve continued to grow our investment in the US as a key source of future growth. Be the next tech-driven, ambitious talent to join our growing US team!

Meet Your Team: Playtime Supply

Playtime Supply is building a unique software solution for app and game developers that puts users’ needs first. Instead of traditional monetization mechanisms, Playtime builds an engaging ad experience in which users can play and earn rewards for various new mobile games in Playtime. To predict which mobile game will best suit a user, the team has introduced ML algorithms.

To build this rewarded experience, adjoe’s backend reliably handles more than 200 million users – remaining stable despite impressive growth in the user base. And imagine this: adjoe’s Golang event consumer applications assign rewards equivalent to 700 months of time spent in Playtime every day to its users. 

The software depends on two main components.
1) adjoe’s Android mobile SDK – written in a combination of Java and Kotlin – which can be bundled by developers in their apps. 
2) The team’s highly scalable Golang backend, which is hosted on AWS and is otherwise responsible for developing a modern React (TypeScript) dashboard that provides adjoe’s clients and Business team colleagues with fast-loading insights.
What You Will Do:
  • Manage the technical onboarding of our newest app partners and ensure a smooth implementation process. 
  • Become the link between various stakeholders, teams, and clients to provide clients with solutions to maximize their business goals. 
  • Assist the supply business team by providing them with data-driven insights into how they can reach their KPIs based on the analysis, aggregation, and visualization of adjoe’s data. 
  • Put on your detective hat and support publishers with issues they may face when integrating adjoe, ranging all the way from basic issues in their mobile app code to fine-tuning configurations.
  • Proactively identify integration issues that publishers may face and work with the product team to create solutions for these issues.
  • Contribute to maintaining easy-to-understand documentation of the integration process.
  • Be part of an international English-speaking team dedicated to scaling our adtech platform beyond our hundreds of millions of monthly active users.
  • Who You Are:
  • You have a skill for communicating complex technical information to business teams and partners. 
  • You are able to turn data into clear and actionable insights and document these in understandable spreadsheets or wiki pages to drive business growth. 
  • You thrive in a team environment and are an excellent cross-team communicator.
  • You have excellent analytical and communication skills and can use SQL to query databases.
  • Basic Knowledge of HTML and JavaScript & you know you don’t eat cookies in IT.
  • You have a working knowledge of how different technical systems communicate with each other, such as being able to test HTTP REST endpoints and understand what could go wrong when they don’t work.
  • Plus: You are familiar with Java or have experience building your own apps.
  • Build our signature product

    See vacancies