What's New in vue-styleguidist 3.0

Vue Styleguidist is a Node package to automatically create documentation for your Vue Components. Alex Jover Morales presented it last year on Alligator.io. Since last February, vue-styleguidist has evolved.

It’s time for a refresher.

The new documentation website powered by VuePress will help you start documenting.

Vue-styleguidist 3 brings a significant performance boost. vue-docgen-api went through an entire rewrite. Vue-styleguidist now runs from 20 times to 2000 times faster.

Let’s see what features have changed.

Detection of types in Flow and TypeScript

Before 3.0, documenters had to specify in JSDoc the type returned and the types of arguments. If you are using TypeScript or Flow, it’s now all automated.

// vue-styleguidist 2.0
export default {
  methods: {
    /**
      * Get the item selected in the category found
      * @param {Number} category
      * @returns {Item}
      */
    getSelectedItem(category: number): Item {
        return this.items[category]
    }
  }
}

// vue-styleguidist 3.0
export default {
  methods: {
    /**
      * Get the item selected in the category found
      */
    getSelectedItem(category: number): Item {
        return this.items[category]
    }
  }
}

Slots in JSX Render Functions

In some cases, it’s easier to write templates in a JSX render function. Why sacrifice automated documentation then? In 3.0 you can document slots directly in the render function.

export default {
  render() {
    return (
      <div>
        {/** @slot describe the slot here */}
        <slot name="myMain" />
      </div>
    )
  }
}

This is valid with a non-JSX render function as well.

Class-Style Components

The future of Vue.js 3.0 is class-style components. See this Request for Comments. No way Vue Styleguidist was gonna fall behind. Vue-styleguidist 3.0 now supports Vue class components:

/**
 * Describe your components here
 */
export default class MyComponent extends Vue {
  /**
   * An example of a property typed through the annotation
   */
  @Prop() myProp: number = 0;
}

No More Flagging Mixins

In version 2, documenters had to flag each mixin with the tag @mixin. If not, vue-styleguidist was missing documentation for the props in the mixin. Starting from version 3.0, this tagging is not necessary anymore.

// vue-styleguidist 2.0
/**
 * @mixin
 */
export default {
  props:{
    size: Number
  },
  computed:{
    sizeClass(){
      return `size-${this.size}`;
    }
  }
}

// vue-styleguidist 3.0
export default {
  props:{
    size: Number
  },
  computed:{
    sizeClass(){
      return `size-${this.size}`;
    }
  }
}

Prop Extraction from Functional Templates

Vue 2.5 introduced functional templates, templates to render functional components. The props definition is a bit different from classical components. Styleguidist 3.0 now understands and documents this syntax too.

<template functional>
  <button :style="`width: ${props.size}px;`">
    {{props.name}}
  </button>
</template>

Automated Detection of Events

In v2.0 documenters had to point vue-styleguidist to every event emitted. Should they forget one, it would never show in the documentation. In 3.0, rest easy, events are detected and immediately documented by default. You can ignore them if you decide they are irrelevant.

// vue-styleguidist 2.0
export default {
  //...
  methods:{
    /**
     * When submission is sucessful
     * @event success
     */
    submit(){
      this.$emit('success')
    }
  }
}

// vue-styleguidist 3.0
export default {
  //...
  methods:{
    submit(){
      /**
        * When submission is sucessful
        */
      this.$emit('success')
    }
  }
}

Note that, in vue-styleguidist 3.0, event and description have to be on consecutive lines, like a JSDoc. This constraint was not in 2.0.

External Script and Template

Finally, vue-styleguidist 3.8 brought compatibility with imported template and script. Documenters can now have Single File Components (SFC) written like this:

<template src="./template.html"/>
<script src='./script.ts'/>

Document the script and template the same way as in the .vue file. Vue-styleguidist will parse and display the JSDoc.

Wrapping Up

We hope you like this new release. We put a lot of effort into making sure it meets as many needs as possible.

If you have any questions, suggestions, issues or comments, please post an issue on the Vue Styleguidist monorepo.

See you soon.