feat: Vue 3 Support

To compile vue3 template we have to use @vue/compiler-sfc (because vue-template-compiler is for vue2 only).

https://github.com/vuejs/vue-next/issues/670#issuecomment-579785869

I think this is an issue that should be fixed in vue-cli-plugin-vue-next by not including vue-template-compiler (which is for 2.x only)

---

So we have to replace parseComponent(...) from vue-template-compiler with parse(...).descriptor from @vue/compiler-sfc

Here:

1. https://github.com/vue-styleguidist/vue-styleguidist/blob/69c848bfcd9bcf5ee0e33053324d5ed206c85eb6/packages/vue-styleguidist/src/loaders/utils/parseVue.ts#L14
2. https://github.com/vue-styleguidist/vue-styleguidist/blob/daf043224af2a1b8bde19af5fe4426dab466596b/packages/vue-styleguidist/src/loaders/utils/getScript.ts#L7
3. https://github.com/vue-styleguidist/vue-styleguidist/blob/f5b70bf1bdca13495fd041a3eb6e844bf9f9e4c4/packages/vue-styleguidist/src/loaders/utils/processComponent.ts#L44

[elevatebart]

@dvh91 @PauloSSAragao Thank you for your interest in the tool, it means a lot.

I have not worked seriously on styleguidist for a while. My work at Cypress and the raising of my little human have taken the better part of my brain power this year.

@PauloSSAragao I would not expect any good news before spring unless you are willing to help.

To jump on version 3 of Vue we need to change the architecture of the tool. Here is a summary of why and how we will do that.

How it worked

The architecture of vue-styleguidist@4 works very well with the explicitness of Vue 2.

vue-docgen-api

There are only 3 places I can find a prop for a component.

• It is in its code, in the props member, or in the @props if it’s a class style component
• It’s in its parent components code (using extends)
• It’s in one of the mixins it uses

We would parse the current components code using @babel/parser and if by any chance the component had a mixin or a extend we would parse the imported components corresponding to these extends and mixins.

Since there is only 3 places to look in, it was rather easy find where the current prop has been documented. With this data found, composing the documentation object was a matter of merging them in the right order.

vue-styleguidist

Most of the rendering code was already made in react-styleguidist. It made the dev and maintenance of the front-end of the tool relatively simple.

Vue-styleguidist would leverage the vue-docgen-api to build the documentation website.

What failed with Vue 3

vue-docgen-api

Now that TypeScript is a first class citizen, we can define prop types in interfaces. Those interfaces can be defined inline like here. That makes parsing the same as with Vue 2.

<script lang="ts" setup>
    defineProps<{
	  /**
	   * typescript is easy to document
	   */
        typescript: string
        vue: string
        docgen: string
    }>()
</script>

Often, we will not want to be that explicit The case below becomes a bit more complicated:

• Resolving the interface by matching it’s name with it’s definition (a type, an interface)
• Creating Prop documentation that is not a flat array but a set of deep objects. We need a much more robust type than what we have today to return that

<script lang="ts" setup>
    interface Stack {
	  /**
	   * typescript is easy to document
	   */
        typescript: string
        vue: string
        docgen: string
    }

    interface Props {
	  /**
	   * stack? what is that
	   */
        stack: Stack
    }

    defineProps<Props>()
</script>

And this could become extensively more complex when one adds spreads and imports to the definition of interfaces.

<script lang="ts" setup>
    import type { ExternalProps } from "../common/types"
    interface Stack {
	  /**
	   * typescript is easy to document
	   */
        typescript: string
        vue: string
        ...ExternalProps
        docgen: string
    }

    interface Props {
	  /**
	   * stack? what is that
	   */
        stack: Stack
    }

    defineProps<Props>()
</script>

vue-styleguidist

The front end of react-styleguidist written in React TSX. React JSX is not compatible with Vue3 typings. Vue 3 imposes that you DO NOT already use TSX in any framework besides Vue’s. You’d ask me: “Why did you not try JSX instead of TSX to avoid conflicts” I did. And it worked partially. As soon as you import @testing-library/react the ambient React JSX types are imported again and we are back to square 1. I decided that working without TS and without test was too dangerous so I stopped that way.

The ambition

vue-docgen-api

A couple of new features are necessary

• Implement setup syntax parsing
• Resolution of interfaces, in the same file, resolution of variables
• Definition of a storage format for complex types
• Management of spread operator

I wonder if using the native typescript parser would be more efficient here. If we were to change it means rewriting the new library with the new AST vocable.

A better management of the @example tag would be likely too.

vue-styleguidist

First, I need to design and implement the visual aspect of complex interfaces as rendered above.

Second, Since we cannot use react anymore, why not use Vue all the way. And, while we are at it, why not ditch webpack altogether in favor of vite. I need to re-implement the entire front-end which is fun but takes time.

[elevatebart]

@Keyes thanks for the kind words.

I am a bit swamped right now but it’s moving. checkout the progress on the Pull Requests marked with the label next major

My plan is to support Vue3 in the next major version. I should be starting to work on it in March, for a release at the beginning of summer.

• No more support for Vue 2
• Use of typescript in examples
• Monaco as the editor with an option to get back to the prism editor if you need lighter sites.
• And hopefully sass compilation in SFC