Vitepress instead of Storybook

Vitepress is a documentation application for projects based on Vite and Vue. It works like a normal Vue application, so displaying a Vue component in the documentation will be seamless. The question is worth asking: can Vitepress replace Storybook?

About Storybook

Storybook is a frontend workshop for building UI components and pages in isolation. Every front-end developer should have experience with this tool. In order to present a component, you need to create a story. It is created according to the Component Story Format (CSF) standard. Based on the stories, an application presenting the described components is generated.

Important advantages of Storybook:

• supports the most important frontend frameworks;
• is very actively developed and the most popular tool of its kind on the market;
• has many plugins and integrations;

We need it?

If Storybook is so good why think about something else? Why Vitepress? What we should really be asking ourselves is how the team working on the system design will produce and use the documentation, and for whom we are ultimately creating the documentation.

In practice, the source of truth for the team will be Figma or another design tool. The front-end developer should transfer the component from Figma to Storybook - provide its code. At this point in the process there should be a check that the developer has reflected the design from Figma correctly. And here the question arises - who should accept or not the work of the frontend-developer when in practice the business will test the operation already in the application? And if so, what is the value to the UX developer of giving approval in Storybook if the business will come back to him with comments already from production?

Here it is worth looking at another conclusion from observing how front-end developers work with Storybook. It is accepted that we do Storybook because when a new developer joins the team it will allow him to get acquainted with the project and conventions. Unfortunately, this is complete nonsense. The developer will look in the code anyway, and his source of truth is - again, Figma.

Sometimes certain things are automatic in projects, they affect the delivery time of working software, but no one asks themselves what proper role the tool plays in the delivery process, who uses it and whether it makes sense at all.

To be fair - it's a great tool and should be used, but as with many decisions in projects implementing a design system, it's worth asking ourselves questions about how we want to use Storybook and what real value it brings to the project.

Why Vitepress?

Almost every team has a documentation problem. The business will use Confluence, the UX will design in Figma, the backend will use markdown and yaml (example: for OpenApi), and the front-end will comment in components and just want Storybook.

A new developer joining the team will be lost, as he/she will lack connections between different sources of knowledge. It is also important to realize that the work of individual team members will be of interest to more than just other team members. The project will have many stakeholders. Developers and stakeholders should not receive only a fragment of the work. Context is important, showing the bigger picture. Documentation has to explain why we do something, why something should work in a defined way.

What if we devoted one page in markdown to one component, which would be edited by those involved in its construction? Would everyone have a similar understanding of what component they are building, what they expect and whether what has been delivered meets the requirements?

Vitepress is nothing more than a directory of markdown files from which a project documentation page is generated. In each document, you can embed components of the produced system design or components that improve the presentation of documentation. You can create a detailed description, show the code, the result of the code and, most importantly, adopt one consistent standard for documenting the project.

It is simple, quick to implement, streamlining the process and saving time (read: money).

Limitations

There are three things to be aware of:

• Vitepress is only suitable for Vue-based projects;
• in the presented components, be careful about the inheritance of styles from Vitepress;
• does not use stories so there is no generation of controls to set props.

Is it worth using?

I'm currently experimenting with using Vitepress instead of Storybook. I see great potential in this tool and in my opinion, in fact, in some projects it will be a completely sufficient tool for documenting components, and it is certainly great for descriptive documentation of projects.

Deciding whether it's worth using should certainly depend on what we need and what I described earlier, which is the team's awareness of how we will use it.

Project website: Vitepress.