Vuetify3 (Alpha) + Storybook

DISCLAIMER (2021-04-14): Vuetify v3 is still in an early alpha release phase. I was able to get Storybook working in the way I’ve described below but YMMV. The steps needed to make this work are likely to change a few times before the latest release. At the time of writing, I used vuetify@v3.0.0-alpha.2 and storybook@6.2.8

Just a quick post to document how I was able to get Storybook working with the Vuetify 3. Here are some quick links:

• A repo with a working Vuetify 3 + Vue 3 + Storybook configuration
• The Storybook site that was generated by that project
• Vuetify 3 (alpha) documentation
• Storybook v6 for Vue documentation

Background

On 2021-03-03 the VuetifyJS project released it’s first alpha of version 3 which is designed to be compatible with and take advantage of the new features in VueJS v3. I’m a big fan of using Storybook to develop components for my projects, so I thought I’d use it to kick the tires of the updated framework. Storybook only very recently announced support for Vue 3, and while there are probably still a few kinks to be worked out, so far the process has been relatively pleasant.

The steps below are the ones that I followed. There are probably other (better) ways to accomplish this. Please leave a comment if you have any ideas for ways to improve this strategy. A huge caveat is that Vuetify 3 is still very much in development–a bunch of features have not been implemented, yet, and as with any alpha project, changes are quite likely.

Step 1: Create a New Vue 3 Project

I used the @vue/cli to generate a new project. Here are the options I selected in the menus:

1. “Manually select all features”
2. Selected all EXCEPT TypeScript (and haven’t tested this process with TS)
3. Choose “3.x (Preview)”
4. Use history mode: Yes
5. Sass/SCSS (with dart-sass)
6. ESLint + Standard config (my personal preference)
7. Lint on save (only)
8. Jest
9. Cypress
10. In dedicated config files

Step 2: Add Vuetify 3

I used the @vue/cli to add Vuetify to the project and chose the “V3 (alpha)” preset. At this point I also recommend committing any changes you’ve made to the project git repo in case you want to roll back to this point. I also recommend starting up the app once at this point (npm run serve) just to confirm that Vue 3 and Vuetify 3 are playing nicely together.

Step 3: Initialize Storybook

Although the Storybook Vue 3 support announcement touted their “zero-config setup”, I didn’t find that this worked out-of-the-box just yet. Upon digging deeper, I discovered that the Storybook init command checks for the presence of Vuetify in a project, and if it finds it, defaulted to a Vue 2 configuration, which won’t work for Vue3/Vuetify3. As such, you needed to specify the project type at setup like this:

I submitted a PR to update the Storybook CLI to auto-detect projects with Vuetify 3 installed. As of 2021-04-13 and storybook@v6.2.8, the auto-detect feature now works out of the box with Vue3 and Vuetify3:

At this point, you can actually run storybook (npm run storybook) and it should start without incident, but it won’t actually parse Vuetify components just yet.

Step 4: Update Storybook Config Files

In the .storybook/ directory, update the following two files:

This updates the main config to register the standard @ alias to the src/ directory used in Vue projects, and also instructs the Storybook webpack builder to parse Sass/Scss files correctly.

This file pulls in the same src/plugins/vuetify.js config file that’s used by your app and adds it to the Vue 3 instance used by Storybook. It also adds a decorator that wraps all of your stories in a <v-app></v-app> element, which is required for many/most of the Vuetify 3 styling/JS to be applied correctly.

Step 5: Start Writing Stories!

You can see a sample component and story in the sample repo I set up for this project. You can see the built Storybook site, as well. In addition to the standard setup, I added the @storybook/addon-a11y (accessibility) and storybook-dark-mode plugins. You can also see how Storybook detects the component and property documentation (in the comments in src/components/Button.vue and automatically generates docs and controls for the different properties that can be submitted to the VBtn component.

Bonus: i18n

The sample repo also demonstrates how to use i18n (internationalization) for Vue 3 in both the actual app being developed as well as the Storybook stories. To set this up:

1. Install the Vue-I18n package: npm i vue-i18n@next
2. For the app itself:
   1. Instantiate i18n in the ./src/i18n/index.js file and place appropriate language/translation files in ./src/i18n/locales/, e.g. ./src/i18n/locales/en.json
   2. Import and use the i18n instance in ./src/main.js
3. For Storybook, following the recommended setup from the storybook-addon-i18n package (NOTE: do NOT actually install this package as it is deprecated):
   1. Update .storybook/preview.js to import the useI18n() function from the vue-i18n package and the i18n instance we created in step 2.1 above
   2. Add a global locale variable and assign it a toolbar button/menu with your defined locales
   3. Update the setup() method of the decorator used to wrap all of your stories so that it can update your components’ locale to match that selected in the toolbar
   4. Update your actual components and/or their stories to use the string interpolation functions as directed by the vue-i18n documentation

NOTE: vue-i18n has several different methods for translating strings depending on whether or not you are injecting the component globally or locally, and whether you’re using their “Legacy API” or the newer composition API. My example uses the composition API instructions.

Conclusion

Although there are still aspects of this setup that I have yet to explore, and I haven’t used it in a “real” project, yet, I found this MUCH easier and cleaner to use than my previous example with Vue 2 + Vuetify 2. Please share a comment below if you found any ways to improve upon what I’ve started.