Structuring our Storybook better

Storybook is a brilliant tool for documentation, and we'll make good use of it in several ways.

Storybook 6 uses the MDX format to allow for some rather extensive possibilities in how you can document and create stories. In this lesson, we are going to do a full house cleaning, setting up the essentials.

Our documentation will be short and more "indicative" than a perfect representation of full documentation. On the other hand, what we've built is also not too complicated, and our domain does not need a lot of elaboration. So, let's get going!

Organize all elements in an elements category#

Go through all elements and look at their <Meta title="{SOMETHING}"...>. Prefix their respective names with elements/. Save and go to Storybook, and you'll find all elements in their own category.

This is a bit neater and easier to scan and find what you are looking for.

Storybook categorized items

Prop types#

One very smart and easy way to document components is to add prop types to them. I'll guide you through setting up prop docs for the Image element. This is a good use-case, as it has some non-obvious prop names and functionality. Also, it has a mix of required and selective props.

Start Storybook and open up the Image element. You can see the props for the element in both Canvas and Docs views, but the full description is only in the Docs tab—go there. You'll find the onClickEvent prop at the bottom, in the ArgsTable. It might say, This story is not configured to handle controls., meaning, in our case, we are missing data, so it's not going to show anything.

Now, open up src/elements/Image/Image.js. Update the prop types object to:

Because an Image element without an actual image makes no sense, we require the url prop. For the other two props, which are only aesthetic in nature, we are setting them as selective and also being explicit with what their defaults are.

Save and switch back to Storybook. Notice how the prop description is now updated with what we just wrote.

Image props description

You can also see this reflected under the Docs tab.

Start a new discussion. All notification go to the author.