Back to blog

Storybook for Vue 3

Supporting the next-gen progressive JS framework

loading
Michael Shilman
โ€” @mshilman
Last updated:

Vue 3 is the latest major installment of Vue.js that features better ergonomics, better performance, and new APIs for managing large apps.

Storybook is an open source tool for building UI components. It speeds up UI development, generates documentation, and automates testing. This versatility makes it the tool of choice at Netflix, Twitter, GitHub, Slack, and Microsoft.

Thousands of Vue 2 projects already use Storybook to build UIs faster. We're excited to ship official Vue 3 support for the next-gen framework. All of Storybookโ€™s core features are included.

๐ŸŽ Zero-config setup w/ built-in TypeScript support
๐ŸŽ› Auto-generated controls and documentation
๐Ÿ“ธ Automated snapshot and visual testing
๐Ÿงฉ Hundreds of addons: A11y, Perf, GraphQL, Theming, etc.

Betting early on Vue

Vue holds a special place in the Storybook ecosystem. It was one of the earliest communities we integrated with back in 2017.

Since then, usage of @storybook/vue has skyrocketed to over 500,000 npm downloads a month. The Vue ecosystem has adopted us too. Storybook now has first-class integrations with NuxtJS and Vuetify.

Today, Vue is one of Storybookโ€™s โ€œcoreโ€ frameworks. That means every new feature and core addon ships with first-class support and documentation for Vue out of the gate. Weโ€™re excited to continue our commitment with Vue 3 support.

Update, 2024: Storybookโ€™s Vue support and Vue testing workflows are now stronger than ever. Learn about Storybook 8โ€™s integration with Vueโ€™s official language tools (powered by Volar), or discover Storybook 8โ€™s built-in visual testing.

Zero-config setup

To get started, run the following in the root of an existing Vue 3 project:

npx sb init

This detects the project type, installs @storybook/vue3, and adds some sample files to demonstrate the basics of Storybook. Running `yarn storybook` gives you the following zero-config setup:

When you navigate to Storybook locally, youโ€™ll see examples of how to write Vue 3 stories, links to common configurations, as well as the โ€œessentialโ€ addons that ship with Storybook. TypeScript (TS) support is built-in. Learn more in the official documentation.

Auto-generated controls and documentation

First class support means that Storybookโ€™s key features work seamlessly with Vue 3. Two of the most-requested features include auto-generated controls and documentation.

When you annotate your Vue components with JSDoc comments, Storybook converts that into living documentation alongside your stories.

Consider the Vue 3 example:

import MyButton from './Button.vue';

const Template = (args) => ({
  components: { MyButton },
  setup() { return { args }; },
  template: '<my-button v-bind="args" />',
});

export const Primary = Template.bind({});
Primary.args = { primary: true };

export const Secondary = Template.bind({});
Secondary.args = { primary: false };

This example is written in Component Story Format, a standard way to document components that was developed by Storybook and supported by the broader frontend ecosystem. The Template defines a Vue 3 component using setup hooks to show how to map dynamic inputs (โ€œargsโ€) to component props. Each named export configures the template to show a key state of the component.

Finally, a default export defines metadata about the component.

export default {
  title: 'Example/Button',
  component: MyButton,
  args: { label: 'Button' },
  argTypes: {
    backgroundColor: { control: 'color' },
    size: {
      options: ['small', 'medium', 'large'],
      control: 'select'
    },
  },
};

Together, these result in auto-generated controls for interactively exploring component states:

It also results in component documentation with no extra work, which includes all of the key states laid out with props extracted from the component source:

Your component's controls and docs are always up to date because they're generated automatically from the source code. You don't need to keep track of your UI documentation whenever a component's API changes, Storybook does that for you.

Perfect for UI testing

When you build UIs in Storybook you get testing for free. Storybook revolves around the concept of stories, these capture the supported state of your UI components.

In development, you can manually confirm your stories โ€œlook rightโ€ and use a suite of addons to test your story in other dimensions like accessibility and mobile-friendliness.

In continuous integration, you can automatically detect both structural and visual changes in your stories using snapshot and visual testing respectively.

Testing your stories is so useful that multiple commercial services integrate with Storybook to run tests in the cloud and across browsers. Notably, Chromatic, created by Storybook maintainers, integrates tightly with Storybook and provides free automated publishing and visual diffing.

Whatโ€™s more, your stories are portable across tools. Storybook pioneered the Component Story Format, an open standard for component examples based on JavaScript ES6 modules. That allows you to reuse stories for your unit and end-to-end tests โ€“ no lock-in.

200+ addons to choose from

In addition to Storybookโ€™s core features, you can customize Storybook to fit your workflow with an ecosystem of hundreds of addons.

Addons unlock superpowers like accessibility testing, design handoff integrations, styling utilities, and mocking for network requests.

Thanks to Storybookโ€™s cross-framework architecture, most addons already support Vue 3 without any extra modification from you. We also display framework compatibility (when available) in the catalog.

Next steps

Storybook for Vue 3 is available now in 6.2. Add Storybook by running the following command in the root of your project. Check out the updated docs.

npx sb init

Issues are tracked with the โ€œapp: vue3โ€ label on GitHub. If youโ€™re experiencing an existing issue, upvote the issue by clicking ๐Ÿ‘ on the issue description. If you find a problem that doesnโ€™t have an existing issue, file a new issue using the โ€œbugโ€ issue template.

We've got big improvements planned for Vue including:

  • Native Vue ergonomics like Single File Component stories
  • Tighter integration with Vue build tools such as Vite
  • Native Vue MDX support once MDX v2 is released

Get involved

Storybook is maintained by 1,200+ open source contributors and guided by a steering committee of top maintainers. Vue 3 integration was developed by Blaine Bublitz, based on work by Sasan Farrokh, andoshin11, and Rafael Milewski with guidance from Lee Chase and the rest of the community.

If you are interested in contributing, check out Storybook on GitHub, create an issue, or submit a pull request. Donate on Open Collective. Chat with us in Discordโ€Šโ€”โ€Ša maintainer is usually online. Stay up to date with Storybook news on Twitter and by signing up for our mailing list below.

Join the Storybook mailing list

Get the latest news, updates and releases

6,616 developers and counting

Weโ€™re hiring!

Join the team behind Storybook and Chromatic. Build tools that are used in production by 100s of thousands of developers. Remote-first.

View jobs

Popular posts

Create Storybook Addon

Launching an Addon Kit and in-depth guide
loading
Varun Vachhar

Storybook for Webpack 5

Next-gen tooling with pluggable builders
loading
Michael Shilman

How we built a profile card generator for Storybook

Combining React and Netlify functions to build a social image generator
loading
Varun Vachhar
Join the community
6,616 developers and counting
WhyWhy StorybookComponent-driven UI
DocsGuidesTutorialsChangelogTelemetry
CommunityAddonsGet involvedBlog
ShowcaseExploreProjectsComponent glossary
Open source software
Storybook

Maintained by
Chromatic
Special thanks to Netlify and CircleCI