Tutorial

What's New in vue-styleguidist 3.0

Published on March 14, 2019
Default avatar

By Bart Ledoux

What's New in vue-styleguidist 3.0

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors
Default avatar
Bart Ledoux

author

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
Leave a comment


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel