# Cookbook

# How to add third-party plugins to the style guide?

If you need to load vue plugins from a third party. You can add it, creating a .js file that installs the plugins and then adds it into the styleguide.config.js file

Use require option:

// styleguide/global.requires.js
import Vue from 'vue'
import VueI18n from 'vue-i18n'
import VeeValidate from 'vee-validate'
import Vuetify from 'vuetify'
import 'vuetify/dist/vuetify.min.css'

Vue.use(VueI18n)
Vue.use(VeeValidate)
Vue.use(Vuetify)
// styleguide.config.js
module.exports = {
  require: [path.join(__dirname, 'styleguide/global.requires.js')]
}

If you need to change the root component of each preview example, you can change the root component of the preview. Creating a .js file that exports the root component as jsx component and then adds it into the styleguide.config.js file

Use renderRootJsx option:

// config/styleguide.root.js
import VueI18n from 'vue-i18n'
import messages from './i18n'

const i18n = new VueI18n({
  locale: 'en',
  messages
})

export default previewComponent => {
  // https://vuejs.org/v2/guide/render-function.html
  return {
    i18n,
    render(createElement) {
      // v-app to support vuetify plugin
      return createElement(
        'v-app',
        {
          props: {
            id: 'v-app'
          }
        },
        [createElement(previewComponent)]
      )
    }
  }
}
// styleguide.config.js
module.exports = {
  renderRootJsx: path.join(__dirname, 'config/styleguide.root.js')
}

See an example of style guide with vuetify and vue-i18n.

# How to add vuex to the style guide?

You can add it, creating a .js file that installs the plugins and then adds it into the styleguide.config.js file

// config/styleguide.root.js
import Vue from 'vue'
import Vuex from 'vuex'
import { state, mutations, getters } from './mutations'

Vue.use(Vuex)

const store = new Vuex.Store({
  state,
  getters,
  mutations
})

export default previewComponent => {
  // https://vuejs.org/v2/guide/render-function.html
  return {
    store,
    render(createElement) {
      return createElement(previewComponent)
    }
  }
}

Use require option:

// styleguide.config.js
module.exports = {
  renderRootJsx: path.join(__dirname, 'config/styleguide.root.js')
}

See an example of style guide with vuex.

# How to add dummy data to the style guide?

You can use global mixins to add dummy data:

Use require option:

// styleguide/global.requires.js
import Vue from 'vue'

Vue.mixin({
  data() {
    return {
      colorDemo: 'blue',
      sizeDemo: 'large'
    }
  }
})
// styleguide.config.js
module.exports = {
  require: [path.join(__dirname, 'styleguide/global.requires.js')]
}
// example component

<Button size="colorDemo" color="sizeDemo">
  Click Me
</Button>

# How to exclude some components from the style guide?

Vue Styleguidist will ignore tests (__tests__ folder) by default.

Use ignore option to customize this behavior:

module.exports = {
  ignore: ['**/*.spec.vue', '**/components/Button.vue']
}

Note: You should pass glob patterns, for example, use **/components/Button.vue instead of components/Button.vue.

# How to hide some components in a style guide but make them available in examples?

Enable skipComponentsWithoutExample option and do not add example file (Readme.md by default) to components you want to ignore.

Require these components in your examples:

const Vue = require('vue').default
const Button = require('./Button.vue').default
Vue.component('Button', Button)

<Button>Push Me</Button>

# How to add custom JavaScript and CSS or polyfills?

In your style guide config:

const path = require('path')
module.exports = {
  require: [
    'babel-polyfill',
    path.join(__dirname, 'path/to/script.js'),
    path.join(__dirname, 'path/to/styles.css')
  ]
}

# How to change styles of a style guide?

There are two config options to change your style guide UI: theme and styles.

Use theme to change fonts, colors, etc.

Use styles to tweak the style of any particular Styleguidist component.

As an example:

module.exports = {
  theme: {
    color: {
      link: 'firebrick',
      linkHover: 'salmon'
    },
    fontFamily: {
      base: '"Comic Sans MS", "Comic Sans", cursive'
    }
  },
  styles: {
    Logo: {
      // We're changing the LogoRenderer component
      logo: {
        // We're changing the rsg--logo-XX class name inside the component
        animation: 'blink ease-in-out 300ms infinite'
      },
      '@keyframes blink': {
        to: { opacity: 0 }
      }
    }
  }
}

Note: See available theme variables.

Note: Styles use JSS with these plugins: jss-isolate, jss-nested, jss-camel-case, jss-default-unit, jss-compose and jss-global.

Note: Use React Developer Tools to find component and style names. For example a component <LogoRenderer><h1 className="rsg--logo-53"> corresponds to an example above.

Note: Use a function instead of an object for styles to access all theme variables in your custom styles.

module.exports = {
  styles: function(theme) {
    return {
      Logo: {
        logo: {
          // we can now change the color used in the logo item to use the theme's `link` color
          color: theme.color.link
        }
      }
    }
  }
}

NOTA: If you need to reference the original component, you can do so by importing the rsg-components-default version. Check out the customized example, it uses the following:

// SectionsRenderer.js
import React from 'react'
import PropTypes from 'prop-types'
import Styled from 'rsg-components/Styled'
import Heading from 'rsg-components/Heading'

// Avoid circular ref
// Import default implementation using `rsg-components-default`
import DefaultSectionsRenderer from 'rsg-components-default/Sections/SectionsRenderer'

const styles = ({ fontFamily, color, space }) => ({
  headingSpacer: {
    marginBottom: space[2]
  },
  descriptionText: {
    marginTop: space[0],
    fontFamily: fontFamily.base
  }
})

export function SectionsRenderer({ classes, children }) {
  return (
    <div>
      {!!children.length && (
        <div className={classes.headingSpacer}>
          <Heading level={1}>Example Components</Heading>
          <p className={classes.descriptionText}>
            These are the greatest components
          </p>
        </div>
      )}
      <DefaultSectionsRenderer>{children}</DefaultSectionsRenderer>
    </div>
  )
}

SectionsRenderer.propTypes = {
  classes: PropTypes.object.isRequired,
  children: PropTypes.node
}

export default Styled(styles)(SectionsRenderer)

# How to change style guide dev server logs output?

You can modify webpack dev server logs format changing stats option of webpack config:

module.exports = {
  webpackConfig(env) {
    if (env === 'development') {
      return {
        stats: {
          chunks: false,
          chunkModules: false,
          chunkOrigins: false
        }
      }
    }
    return {}
  }
}

# How to debug my components and examples?

  1. Open your browser’s developer tools
  2. Write debugger; statement wherever you want: in a component source, a Markdown example or even in an editor in a browser.

# How to debug the exceptions thrown from my components?

  1. Put debugger; statement at the beginning of your code.
  2. Press the Debugger button in your browser’s developer tools.
  3. Press the Continue button and the debugger will stop the browser from running JavaScript at the next exception.

# How to use Vagrant with Styleguidist?

First read Vagrant guide from the webpack documentation. Then enable polling in your webpack config:

devServer: {
  watchOptions: {
    poll: true
  }
}

# How to document styled-components?

To document styled-components you need to get them recognized by vue-docgen-api. The simplest way is to use extends:

import styled from 'vue-styled-components'

const _StyledTitle = styled.h1`
  font-size: 1.5em;
  text-align: center;
  color: palevioletred;
`

export default {
  extends: _StyledTitle
}

or if you are using with the class component syntax

import styled from 'vue-styled-components'

const _StyledTitle = styled.h1`
  font-size: 1.5em;
  text-align: center;
  color: palevioletred;
`

@Components({ extends: _StyledTitle })
export default class StyledTitle extends Vue {}

# Use vue-styleguideist with components that contain routing

If your components contain <router-link> the best way is, in your styleguide to mock it. In the styelguide.config,js file add styleguide.global.required.js (see below) to the require parameter. Styleguidist will render router-link as an anchor or tag of your choosing. Don't use vue-router inside vue-styleguidist. It will conflict with its internal router.

// styleguide.global.requires.js
import Vue from 'vue'
Vue.component('RouterLink', {
  props: {
    tag: { type: String, default: 'a' }
  },
  render(createElement) {
    return createElement(this.tag, {}, this.$slots.default)
  }
})

See this example for a concrete implementation.

PRO TIP: If your styleguide has .resolve issues in the browser console, it still seems to be using vue-router. Check if you are requiring the router.js file in any of the showcased components and remove the dependency. If you still can't find the culprit, follow these steps and you will find it.

  1. Find all mentions of Vue.use(Router) in your codebase
  2. Add console.trace() on the line before it to get the stack trace of the way they are called
  3. open styleguidist and look at the console of your browser

Somewhere in your stack should be one of the displayed components. Find a way to avoid this require. If you can't find a way around this require, use a context variable to only load the router when not in styleguidist.

  1. Install cross-env package
  2. Set a context variable before you launch styleguidist: cross-env MYSTYLE=true styleguide serve
  3. Use the variable in your code as follows
if (!process.env.MYSTYLE) {
  Vue.use(Router)
}

# How to include FontAwesome (or other icon sets) in your style guide

If your components rely on an icon set such as FontAwesome, you can edit styleguide.config.js to import it:

module.exports = {
  title: 'My Style Guide',
  template: {
    head: {
      links: [
        {
          rel: 'stylesheet',
          href:
            'https://pro.fontawesome.com/releases/v5.8.2/css/all.css',
          integrity: 'your hash here',
          crossorigin: 'anonymous'
        }
      ]
    }
  }
}

See template for more details.

# How to use vue-styleguidist with multiple packages for components

If your base components are in one package and the derived components are in another, you will want the documenattion to reflect extended components props in the exposed ones.

Say you have a BaseButton.vue in a @scoped/core package that you extend into IconButton.vue in the @scoped/extended package, the BaseButton.vue props are not going to be documented with IconButton.vue. This can be what you want, or you could be missing a lot of props.

Use the validExtends option to allow parsing of extended components in other packages.

module.exports = {
  // Add the following function to your styleguide.config.js
  validExtends(fullFilePath) {
    return (
      /[\\/]@scoped[\\/]core[\\/]/.test(fullFilePath) ||
      !/[\\/]node_modules[\\/]/.test(fullFilePath)
    )
  }
}