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
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
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:
- “Manually select all features”
- Selected all EXCEPT TypeScript (and haven’t tested this process with TS)
- Choose “3.x (Preview)”
- Use history mode: Yes
- Sass/SCSS (with dart-sass)
- ESLint + Standard config (my personal preference)
- Lint on save (only)
- 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
email@example.com, 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
.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
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:
- Install the Vue-I18n package:
npm i vue-i18n@next
- For the app itself:
- Instantiate i18n in the
./src/i18n/index.jsfile and place appropriate language/translation files in
- Import and use the i18n instance in
- Instantiate i18n in the
- For Storybook, following the recommended setup from the
storybook-addon-i18npackage (NOTE: do NOT actually install this package as it is deprecated):
.storybook/preview.jsto import the
useI18n()function from the
vue-i18npackage and the
i18ninstance we created in step 2.1 above
- Add a global
localevariable and assign it a toolbar button/menu with your defined locales
- 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
- Update your actual components and/or their stories to use the string interpolation functions as directed by the vue-i18n documentation
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.
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.