Vue: Replace vue-docgen-api with Volar vue-component-meta #22285

chakAs3 · 2023-04-27T11:30:09Z

Closes #22090 #21606 #23313 #25582 #25305 #24621 #22209 #21684 #19233 #16301

and other issues

Current PR status / open points

Status from: 18 February 2024

waiting for vue-component-meta: checker not working with tsconfig that uses references vuejs/language-tools#3896. Alternatively we have to implement a temporary workaround because currently projects that use references in their tsconfig will miss all component docs in Storybook
Performance issues need testing if they still exists. If they exist, we might need to only include .vue files by default and add a framework option to also include ts,js,jsx and tsx files

Volar can be enabled with:

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/vue3-vite';

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: "vue-component-meta"
    },
  },
};

export default config;

What I did

replace vue-docgen-api with official vue language tools by Volar ( vue-meta-component ) with a better type definition, more features, and regular updates by @johnsoncodehk.

What benefits are we getting? :

Added Props type definition extraction

String (e.g. 'Foo')
Array of strings (e.g. ['Baz', 'Bar', 'Foo'])
Number (e.g. 1)
Union types with optional values (e.g. 'Foo' | undefined)
Union types (e.g. 'Foo' | 'Baz')
Object with inline properties (e.g. { foo: 'Foo' })
Object with nested properties (e.g. { nestedProp: 'Nested Prop' })
Object with intersection types (e.g. { nestedProp: 'Nested Prop', additionalProp: 'Additional Prop' })
Array of objects with properties (e.g. [{ foo: 'Foo' }])
Literal types (e.g. ['Uncategorized', 'Display', 'Addons'])
Enum types (e.g. MyEnum.Small)
Recursive object types (e.g. { recursive: { recursive: { recursive: 'recursive' } } })

Added props description and tag annotation support :

This PR adds the ability to include descriptions and tag annotations for props in Vue components. The following examples demonstrate how to use this new feature:

Props Description

To provide a description for a prop, add a description property to the prop object. Here is an example:

interface MyComponentProps {
  /**
   * The name of the user
   */
  name: string;
  /**
   * The category of the component
   * @required
   * @default 'Uncategorized'
   */
  category: string;
}

export default {
  name: "MyComponent",
  props: {
    name: {
      type: String,
      required: true,
      description: "The name of the user",
    },
    category: {
      type: String,
      default: "Uncategorized",
      tags: ["required", "default: Uncategorized"],
    },
  },
  // rest of the component's logic
};

Props Tag Annotation

To add a tag annotation to a prop, add a tags property to the prop object. This can be useful for documenting things like default values or required props. Here is an example:

props: {
  // @required
  // @default 'Uncategorized'
  category: {
    type: String,
    tags: ['required', 'default: Uncategorized']
  }
}

These new features can make documentation more organized and useful for other developers, so be sure to take advantage of them in your Vue components.

Added support control generation

Ability to generate Storybook controls based on Vue component's props type definitions

This new feature enables developers to generate Storybook controls for their Vue components, using simple props type definitions as a guide. Here's an example of how it might look like:

<script>
enum MyEnum {
	Small,
	Medium,
	Large,
}

const categories = [
	'Uncategorized',
	'Content',
	'Interaction',
	'Display',
	'Forms',
	'Addons',
] as const;

type MyCategories = typeof categories[number];

type MyProps = {
  /**
	 * description enum value
	 */
	enumValue: MyEnum,
	/**
	 * description literal type alias that require context
	 */
	literalFromContext: MyCategories,
}

withDefaults(defineProps<MyProps>(), {
	bar: 1,
	baz: () => ['foo', 'bar'],
});
</script>

Events types extraction

Note:
Due to technical limitations of Volar / vue language features, JSDoc / descriptions for emits can not be extracted.

<script setup lang="ts">
type MyFooEvent = "foo";

interface MyEvents {
  (event: MyFooEvent, data?: { foo: string }): void;
  (event: "bar", value: { year: number; title?: any }): void;
  (e: "baz"): void;
}

const emit = defineEmits<MyEvents>();
</script>

Added slots types definition extraction

we can get slots type definition from Vue component and display them on the component docs table

<template>
  <slot name="no-bind"></slot>
  <br />
  <slot :num="123"></slot>
  <br />
  <slot name="named" str="str"></slot>
  <br />
  <slot name="vbind" v-bind="{ num: 123, str: 'str' }"></slot>
</template>

<script setup lang="ts"></script>

Added "Exposed" methods and properties types definition extraction

With the release of Vue 3.2 a new composition tool was made available for us, called expose.
to make methods and properties available to the parent. and made the type available #3399

Now we can extract these exposed and display them on docs table in section called exposed

<script setup lang="ts">
import { ref } from "vue";

const label = ref("Button");
const count = ref(100);

defineExpose({
  /**
   * a label string
   */
  label,
  /**
   * a count number
   */
  count,
});
</script>

In addition to generating Storybook controls for Vue components based on their props, events, slots and exposed type definitions, the new feature also allows this meta extraction from all types of Vue components, including functional, composition / options API components, and from both .vue or .ts files. This makes it easier for developers to test their components and ensure that they are working as intended.

Here's an example of a TypeScript Vue component:

//  .ts-component.ts
export default defineComponent({
  props: {
    /**
     * string foo
     */
    foo: {
      type: String,
      required: true,
    },
    /**
     * optional number bar
     */
    bar: {
      type: Number,
    },
  },
  setup(props) {
    return () => h("pre", JSON.stringify(props, null, 2));
  },
});

Support for Named Export Component

The PR introduces support for named export components in Vue. With this enhancement, you can now have multiple components exported from a single file using named exports. This provides greater flexibility and organization in structuring your Vue components.

You can do something like this

// ./component.ts
export const ComponentA = defineComponent({
  name: "MyCompo1",
  props: {
    /**
     * This is a description of the prop
     * @values 'small', 'medium', 'large'
     * @defaultValue 'medium'
     * @control select
     * @group Size
     * */
    size: {
      type: String as PropType<"small" | "medium" | "large">,
      default: "medium",
    },
    /**
     * This is a description of the prop
     * @defaultValue false
     * @control color
     * @group Style
     * */
    backgroundColor: {
      type: String,
      default: "red",
    },
  },
  setup(props: any) {
    return () => h("pre", JSON.stringify(props, null, 2));
  },
});

export const ComponentB = defineComponent(
  (props: MyProps) => () => h("Pre", `${JSON.stringify(props)}`),
  { props: ["foo", "bar"] }
);

Component Meta Extraction from Various File Types

The PR extends the component meta extraction functionality to support multiple file types, including .vue, .js, .ts, .tsx, and .jsx. Regardless of the file extension, you can now extract component metadata seamlessly. This improvement enables a unified approach to extracting component meta across different file formats, ensuring consistent and efficient development workflows.

so you can have something like :

// ./components.tsx
export const JSXComponent = defineComponent({
  props: {
    /**
     * label for the JSXComponent
     */
    label: String,
    /**
     * counter for the JSXComponent
     * @default 0
     * @type Number
     * @example 1
     */
    counter: Number,
  },
  name: "JSXComponent",
  setup(props, { emit }) {
    return () => (
      <>
        <h4>JSX Component</h4>
      </>
    );
  },
});

By incorporating these new features, we aim to enhance the flexibility and extensibility of Vue components, making it easier to manage and extract metadata across various file types and export configurations.

Please review this PR and provide your feedback. Your contributions and suggestions are highly appreciated.

Thank you!

How to test

Run a sandbox for template, e.g. yarn task --task sandbox --start-from auto --template vue3-vite/default-ts
Open Storybook in your browser

-->

Checklist

Make sure your changes are tested (stories and/or unit, integration, or end-to-end tests)
Make sure to add/update documentation regarding your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Maintainers

If this PR should be tested against many or all sandboxes,
make sure to add the ci:merged or ci:daily GH label to it.
Make sure this PR contains one of the labels below.

["cleanup", "BREAKING CHANGE", "feature request", "bug", "documentation", "maintenance", "dependencies", "other"]

This pull request has been released as version 0.0.0-pr-22285-sha-f910dccb. Try it out in a new sandbox by running npx [email protected] sandbox or in an existing project with npx [email protected] upgrade.

More information


Published version	`0.0.0-pr-22285-sha-f910dccb`
Triggered by	@kasperpeulen
Repository	storybookjs/storybook
Branch	`chaks/vue-component-meta`
Commit	`f910dccb`
Datetime	Fri Feb 23 15:33:14 UTC 2024 (`1708702394`)
Workflow run	8021473651

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=22285

socket-security · 2023-05-08T12:47:02Z

👍 Dependency issues cleared. Learn more about Socket for GitHub ↗︎

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

View full report↗︎

Next steps

Take a deeper look at the dependency

Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support [AT] socket [DOT] dev.

Remove the package

If you happen to install a dependency that Socket reports as Known Malware you should immediately remove it and select a different dependency. For other alert types, you may may wish to investigate alternative packages or consider if there are other ways to mitigate the specific risk posed by the dependency.

Mark a package as acceptable risk

To ignore an alert, reply with a comment starting with @SocketSecurity ignore followed by a space separated list of ecosystem/package-name@version specifiers. e.g. @SocketSecurity ignore npm/[email protected] or ignore all packages with @SocketSecurity ignore-all

…level

larsrickert · 2024-02-22T10:43:27Z

Just to add a personal anecdote, I'm using component-meta in our product to help generate docs for our design system, the forceTs option was prohibitively slow for us. For 125 components that went from ~15s to just under ~4s

Unfortunately this didn't improve performance in my tests :/

larsrickert · 2024-02-22T10:45:23Z

@kasperpeulen As discussed:

framework option is added and defaults to "vue-docgen-api"
only thing left to do is to document the change so people are aware of the new feature :) Is the MIGRATION.md the right place for this? Seems like only breaking changes are added there, not new features.

kasperpeulen · 2024-02-22T12:19:58Z

Right, as it is not breaking anymore it doesn't have to be added to MIGRATION.md.
We will update the documentation cc @kylegach and probably do 8.0 feature post about it cc @joevaugh4n

chakAs3 · 2024-02-22T18:51:05Z

Right, as it is not breaking anymore it doesn't have to be added to MIGRATION.md. We will update the documentation cc @kylegach and probably do 8.0 feature post about it cc @joevaugh4n

It's fantastic to see this PR evolving nicely! Huge thanks to everyone involved for their contributions. While the documentation may need some refinement with @kylegach to fit into the official docs, I'm eager to assist with that. Additionally, I'm keen to collaborate on the blog post with @joevaugh4n. Big kudos to @kasperpeulen & @larsrickert for their efforts! 👍 🚀

chakAs3 · 2024-02-22T19:06:51Z

i rather suggest to call it vue-component-meta (the package namee) to be more specific as Volar is the larger it includes all vue language tools

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: 'vue-component-meta', // defaults to vue-docgen-api
    },
  },
};

chakAs3 · 2024-02-22T19:20:59Z

In this way, we are also able to improve the performance in the meantime without blocking this PR.
Maybe @IanVS @ndelangen or @joshwooding have some tips how they did this with react-docgen-typescript.
I guess we might somehow be able to scan lazy load one component at a time? Instead of all at startup.

i think the actual problem with performance is due to files transform, Volar is so fast because it does extract meta via static code analysis.
Maybe generating virtual component meta files in build time will eliminate completely this issue.

kasperpeulen · 2024-02-23T08:43:55Z

i think the actual problem with performance is due to files transform, Volar is so fast because it does extract meta via static code analysis.
Maybe generating virtual component meta files in build time will eliminate completely this issue.

Interesting, let's experiment with that in 8.x.

…okjs/storybook into chaks/vue-component-meta

kasperpeulen

Thanks so much @chakAs3 and @larsrickert

thomasaull · 2024-02-23T15:20:11Z

Thanks guys for all your work on it!

larsrickert · 2024-02-23T15:24:21Z

Great that we got this PR ready 🚀 Special thanks to @kasperpeulen and @chakAs3 and everyone testing out the changes!

tl;dr: To use the new improved docgen plugin, just set the following and enjoy (once its released^^):

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/vue3-vite';

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: "vue-component-meta"
    },
  },
};

export default config;

chakAs3 added 2 commits April 27, 2023 13:25

add component meta 1.5.4 + tests

fecc165

upgrade vue-component-meta

1744729

chakAs3 added maintenance User-facing maintenance tasks vue vue3 labels Apr 27, 2023

chakAs3 added 2 commits April 27, 2023 15:49

remoe "vue-docgen-loader"

ee87fb7

run yarn to update deps

2d155af

chakAs3 added the ci:daily Run the CI jobs that normally run in the daily job. label Apr 27, 2023

JReinhold marked this pull request as draft May 1, 2023 14:17

JReinhold assigned kasperpeulen May 1, 2023

Merge branch 'chaks/fix-sandbox-nx-deps' into chaks/vue-component-meta

50f37e4

chakAs3 added 14 commits May 10, 2023 01:34

add some logs

c15f27a

add all type of components + tests

8f47cb1

remove the undefined string from event descriptions

23e0ab7

Merge branch 'next' into chaks/vue-component-meta

c730333

refactory extractArgTypes vue3

dd02f17

refactory stories for vue-component meta

d4c34ef

add unity tests for extractArgTypes

5f2f547

refactory component meta plugin

291ec4c

Merge branch 'next' into chaks/vue-component-meta

bfb8bd9

refactory export function

7c18b7b

refactory for better types

a37d65d

remove vue-component-meta from main project, keep it only in package …

4e87c9c

…level

revert back nx version update for darwin

975ddd7

add vue3 meta-component support

815f0e9

chakAs3 changed the title ~~WIP: replacing vue-docgen-api with Volar vue-component-meta~~ Vue: replacing vue-docgen-api with Volar vue-component-meta May 22, 2023

chakAs3 marked this pull request as ready for review May 22, 2023 11:07

chakAs3 unassigned kasperpeulen May 22, 2023

Merge branch 'next' into chaks/vue-component-meta

9a7cf88

larsrickert and others added 5 commits February 22, 2024 11:35

support both "vue-docgen-api" and "volar"

07702dd

rename "docgen-api" to "vue-docgen-api"

e3a1d4a

rename "docgen-api" to "vue-docgen-api"

e047e7b

use real framework options

e6c0cc3

Merge branch 'next' into chaks/vue-component-meta

cd4fd8c

Merge branch 'next' into chaks/vue-component-meta

4b6f889

larsrickert and others added 5 commits February 23, 2024 12:29

fix: update arg types extractor

3ab790c

Merge branch 'next' into chaks/vue-component-meta

b47da2b

fix tests

ae87a4a

Merge branch 'chaks/vue-component-meta' of https://github.com/storybo…

388e29c

…okjs/storybook into chaks/vue-component-meta

rename docgen option "volar" to "vue-component-meta"

f910dcc

kasperpeulen approved these changes Feb 23, 2024

View reviewed changes

larsrickert approved these changes Feb 23, 2024

View reviewed changes

kasperpeulen added this pull request to the merge queue Feb 23, 2024

kasperpeulen removed this pull request from the merge queue due to the queue being cleared Feb 23, 2024

kasperpeulen merged commit 2a8d0b9 into next Feb 23, 2024
107 of 108 checks passed

kasperpeulen deleted the chaks/vue-component-meta branch February 23, 2024 16:16

github-actions bot mentioned this pull request Feb 23, 2024

Release: Prerelease 8.0.0-beta.5 #26143

Merged

16 tasks

larsrickert mentioned this pull request Feb 23, 2024

Vue3: Replace vue-docgen-api with vue-component-meta #22010

Closed

5 tasks

AlexPaven mentioned this pull request Feb 26, 2024

Storybook V8 support storybookjs/storybook-nuxt#1

Open

kylegach mentioned this pull request Mar 5, 2024

Docs: Add docs for vue3-vite framework #26221

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Vue: Replace vue-docgen-api with Volar vue-component-meta #22285

Vue: Replace vue-docgen-api with Volar vue-component-meta #22285

chakAs3 commented Apr 27, 2023 •

edited by storybook-bot

Loading

socket-security bot commented May 8, 2023 •

edited

Loading

larsrickert commented Feb 22, 2024

larsrickert commented Feb 22, 2024

kasperpeulen commented Feb 22, 2024

chakAs3 commented Feb 22, 2024

chakAs3 commented Feb 22, 2024

chakAs3 commented Feb 22, 2024

kasperpeulen commented Feb 23, 2024

kasperpeulen left a comment

thomasaull commented Feb 23, 2024

larsrickert commented Feb 23, 2024 •

edited

Loading

Vue: Replace vue-docgen-api with Volar vue-component-meta #22285

Vue: Replace vue-docgen-api with Volar vue-component-meta #22285

Conversation

chakAs3 commented Apr 27, 2023 • edited by storybook-bot Loading

Current PR status / open points

What I did

What benefits are we getting? :

Added Props type definition extraction

Added props description and tag annotation support :

Added support control generation

Events types extraction

Added slots types definition extraction

Added "Exposed" methods and properties types definition extraction

Support for Named Export Component

Component Meta Extraction from Various File Types

How to test

Checklist

Maintainers

socket-security bot commented May 8, 2023 • edited Loading

Next steps

larsrickert commented Feb 22, 2024

larsrickert commented Feb 22, 2024

kasperpeulen commented Feb 22, 2024

chakAs3 commented Feb 22, 2024

chakAs3 commented Feb 22, 2024

chakAs3 commented Feb 22, 2024

kasperpeulen commented Feb 23, 2024

kasperpeulen left a comment

Choose a reason for hiding this comment

thomasaull commented Feb 23, 2024

larsrickert commented Feb 23, 2024 • edited Loading

chakAs3 commented Apr 27, 2023 •

edited by storybook-bot

Loading

socket-security bot commented May 8, 2023 •

edited

Loading

larsrickert commented Feb 23, 2024 •

edited

Loading