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 – APAC

  • 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). And that’s just the start: We’ve just launched our programmatic in-app platform in order to disrupt the status quo of mobile ad monetization. Again. 

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

Be the next tech-driven, ambitious talent to join our growing teams!

Meet Your Team: Supply Partnerships
Big ambitions lead to big impact – and big revenue numbers. The Supply Partnerships team is an indispensable unit in driving adjoe to reach every single app user on the globe. You don’t just focus on seamlessly integrating our ad solutions into publishers’ apps, you tell publishers what they need to do to create the most engaging ad experiences for their users. Today, our formats reach hundreds of millions of monthly active users through our extensive network of publisher apps. Join this highly charged team and reshape the way apps operate their business!
What You Will Do:
  • Drive results with a ‘get things done’ attitude, proactively solving challenges and ensuring smooth publisher onboarding.
  • Manage the technical onboarding of new app partners in APAC, ensuring a seamless SDK implementation process.
  • Act as a trusted client-facing technical consultant, delivering timely advice and support for technical and product-related inquiries.
  • Provide data-driven insights to the supply business team, helping them achieve KPIs through analysis, aggregation, and visualization of adjoe’s data.
  • Troubleshoot and resolve publisher integration issues, ranging from basic app code errors to advanced configuration fine-tuning.
  • Serve as the bridge between product and business teams, learning the product development roadmap and advocating for business-related product requests.
  • Collaborate with the product team to align feature requests and development timelines, ensuring product enhancements meet market needs.
  • Maintain clear, easy-to-understand documentation for the integration process.
  • Proactively identify potential integration challenges and work with the product team to create scalable solutions.
  • Who You Are
  • You have a skill for communicating complex technical information to business teams 
  • You are bilingual, English and, Mandarin or Korean or Japanese 
  • 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 have excellent analytical and communication skills and can use SQL to query databases.
  • Basic Knowledge of HTML and JavaScript
  • 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.
  • Plus: You know how to use testflight and reproduce the publisher’s test environments. Winner mindset: being a problem solver. 
  • Heard of our perks
  • Hybrid working model: 3 office day, and 2days work from home. 
  • Performance based competitive salary offer.
  • Strong feedback culture with twice a year performance feedback conversations
  • Strong career growth opportunities with biannual development talks to define a career plan
  • Build our signature product

    See vacancies