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!

Business Intelligence Analyst (f/m/d)

  • adjoe
  • Playtime Supply
  • Full-time
adjoe is a leading mobile ad platform developing cutting-edge advertising and monetization solutions to meet the diverse needs of app publishers. Being part of the applike group ecosystem plus the significant financial backing from Bertelsmann empowers us to do this. At adjoe, we are proud of our advanced tech stack and dynamic and innovative workforce.

Meet Your Team: Playtime Supply

The Playtime Supply team focuses on creating great experiences for the 200+ million users who interact with Playtime. This includes everything from the gamified experiences within the mobile apps to the dashboards used to configure and customise these experiences. From the unique product features and ML algorithms to the analytical systems used to analyse their effects. Our cross-functional team has all the expertise needed to realise our product goals.
What you will do
  • You will use data-insights to find opportunities for our product to improve and grow.
  • You will be part of an international, English-speaking team that builds our disruptive Ad Tech platform
  • You create, analyze and communicate reports and statistics by using queries and dashboards that our BI team builds.
  • You will participate in building and maintaining models that will be used in order to provide business insights through our dashboard
  • You drill into data from various sources (Redshift, Spark, SQL, Athena, S3, Druid event streams, AWS data pipeline) and write scripts to improve the processes
  • You are a strong communicator,can explain complex things in simple words,and know how to deal with stakeholders
  • You are able to express technical issues comprehensively in business language
  • You have to understand all the different parts of our product to help our product to achieve better results and provide incredible experience to our publishers and end-users.
  • Who you are
  • You have excellent analytical & communication skills and like to use these on Python, Scala or Julia as well as on Spreadsheets
  • You are fluent in English
  • Strong knowledge in at least one programming language that can be used for BI
  • You’re interested in big data and have outstanding experience in SQL
  • Experienced in using Power BI/Tableau/Quicksight or other tools for creating a dashboard for quick analysis.
  • You are self-confident and competent in communicating with clients
  • Plus: You got in touch with java or you build already some basic android apps in your free time
  • Plus: Knowledge about Mobile App analytics (e.g. adjust, appsflyer etc.)
  • Plus: Knowledge about SDK and basic understanding of the SDK integration process.
  • Heard of Our Perks?
  • Work-Life Package: 2 remote days per week, 30 vacation days, 3 weeks per year of remote work, flexible working hours, dog-friendly kick-ass office in the center of the city.
  • Relocation Package: Visa & legal support, relocation bonus, reimbursement of German Classes costs, and more.
  • Happy Belly Package: Monthly company lunch, tons of free snacks and drinks, free breakfast & fresh delicious pastries every Monday
  • Physical & Mental Health Package: In-house gym with a personal trainer, various classes like Yoga with expert teachers & free of charge access to our EAP (Employee Assistance Program) to support your mental health and well-being
  • Activity Package: Regular team and company events, and hackathons.
  • Education Package: Opportunities to boost your professional development with courses and training directly connected to your career goals 
  • Wealth building: virtual stock options for all our regular employees
  • Skip writing cover letters. Tell us about your most passionate personal project, your desired salary and your earliest possible start date. We are looking forward to your application!

    We welcome applications from people who will contribute to the diversity of our company.

    Build our signature product

    See vacancies