Storybook Vue3 Router
A Storybook decorator that allows you to use your Vue 3 routing-aware components.
If you want to build stories for Vue 3 components using <router-view>
or <router-link>
then you need to wrap your stories with vue-router
this addon will allow for you to easily do this.
How to use
This decorator works with Storybook's Component Story Format (CSF) and hoisted CSF annotations, which is the recommended way to write stories since Storybook 6. It has not been tested with the storiesOf API.
Install the decorator
npm install --save-dev storybook-vue3-router
// or
yarn add --dev storybook-vue3-router
Use in your stories
The default setup will create a vue-router
instance, with 2 routes (/
and /about
) - these can be reviewed in the defaultRoutes.ts file.
import vueRouter from 'storybook-vue3-router'
export const Default = Template.bind({})
Default.decorators = [
vueRouter()
]
Demo
You can see the examples stories published on this demo.
Advanced usage
This decorator comes with optioal params for customising the implementation of your vue-router
within Storybook.
Custom Routes
const customRoutes = [
{
path: '/',
name: 'home',
component: HomeComponent
},
{
path: '/about',
name: 'about',
component: AboutComponent
}
]
Default.decorators = [
vueRouter(customRoutes)
]
Custom Routes (with guards)
const customRoutes = [
{
path: '/admin',
name: 'admin',
component: AdminComponent,
beforeEnter: (to, from, next) => {
}
}
]
Default.decorators = [
vueRouter(customRoutes)
]
Custom Routes (with inital route)
By default the decorator will default the starting route to /
, if you want to change this you can pass as a parametor to the decorator
const customRoutes = [
{
path: '/',
name: 'dashboard',
component: Dashboard
},
{
path: '/intro',
name: 'intro',
component: Intro
}
]
Default.decorators = [
vueRouter(customRoutes, {
initialRoute: '/intro'
})
]
See the examples folder for more advanced usage.
Decorator Parameters
function vueRouter(routes: RouteRecordRaw[], options?: { initialRoute?: string, beforeEach?: NavigationGuard })
v2.x Migration
The migration from v1 brings some breaking changes:
vueRouter(customRoutes, (to, from) => action('ROUTE CHANGED')({ to: to, from: from }))
vueRouter(customRoutes, {
beforeEach: (to, from) => action('ROUTE CHANGED')({ to: to, from: from })
})
If you were previously using v1 with router guards in the second parameter, these will need to be refactored to use the route specific router guards (recommended) or you can pass your global route guards using the beforeEach
option.
v2.0 DOES NOT HAVE THIS beforeEach
option, please upgrade to v2.1
⚠️ Warning:
When using the global beforeEach
option, if there is an existing story also using this decorator then we must force a page reload in order to setup the specific story router guard and this has a minor UX / performance impact. Checkout the demo for an example of this: README > With Router Guards > Global Guard - when clicking the 'Global Guard' link you will notice the page is refreshed to apply global guards (due to previously existing stories).
This will not be an issue if you are using this decorator for just one story.
After resolving this issue, to enable multiple stories to be created using different route setups, it was noticed that this caused the global beforeEach
function to be added on every route. For example every time you click a different story the new beforeEach
hook is added - but previous ones are not removed, this results in multiple guards firing on stories unrelated to the 'active' story.