diff --git a/docs/get-started/nextjs.md b/docs/get-started/nextjs.md index 64e207a683b8..dc0bb08b8477 100644 --- a/docs/get-started/nextjs.md +++ b/docs/get-started/nextjs.md @@ -13,8 +13,8 @@ Storybook for Next.js is a [framework](../contribute/framework.md) that makes it ## Requirements -- Next.js >= 13.5 -- Storybook >= 7.0 +- Next.js ≥ 13.5 +- Storybook ≥ 7.0 ## Getting started diff --git a/docs/get-started/vue-component-meta-event-types-controls.png b/docs/get-started/vue-component-meta-event-types-controls.png index a25c91c37c03..093b2da0911a 100644 Binary files a/docs/get-started/vue-component-meta-event-types-controls.png and b/docs/get-started/vue-component-meta-event-types-controls.png differ diff --git a/docs/get-started/vue-component-meta-exposed-types-controls.png b/docs/get-started/vue-component-meta-exposed-types-controls.png index 16d19c2308d3..d725615e58b6 100644 Binary files a/docs/get-started/vue-component-meta-exposed-types-controls.png and b/docs/get-started/vue-component-meta-exposed-types-controls.png differ diff --git a/docs/get-started/vue-component-meta-prop-types-controls.png b/docs/get-started/vue-component-meta-prop-types-controls.png new file mode 100644 index 000000000000..049bc595c2e9 Binary files /dev/null and b/docs/get-started/vue-component-meta-prop-types-controls.png differ diff --git a/docs/get-started/vue-component-meta-slot-types-controls.png b/docs/get-started/vue-component-meta-slot-types-controls.png index 9a451963ce6e..72b41db2dff8 100644 Binary files a/docs/get-started/vue-component-meta-slot-types-controls.png and b/docs/get-started/vue-component-meta-slot-types-controls.png differ diff --git a/docs/get-started/vue-vite.md b/docs/get-started/vue-vite.md index 6a52f84a47d0..edf881db500c 100644 --- a/docs/get-started/vue-vite.md +++ b/docs/get-started/vue-vite.md @@ -9,9 +9,9 @@ Storybook for Vue & Vite is a [framework](../contribute/framework.md) that makes ## Requirements -- Vue >= 3 -- Vite >= 3.0 (4.X recommended) -- Storybook >= 7.0 +- Vue ≥ 3 +- Vite ≥ 3.0 (4.X recommended) +- Storybook ≥ 7.0 ## Getting started @@ -106,9 +106,13 @@ setup((app) => { ## Using `vue-component-meta` -[`vue-component-meta`](https://github.com/vuejs/language-tools/tree/master/packages/component-meta) is a tool that extracts metadata from Vue components which is maintained by the official Vue team. Storybook can use it to generate the [controls](../essentials/controls.md) for your stories and documentation. It's a more full-featured alternative to `vue-docgen-api` and is recommended for most projects. + + +`vue-component-meta` is only available in Storybook ≥ 8. It is currently opt-in, but will become the default in a future version of Storybook. -It requires Storybook >= 8. `vue-component-meta` is currently opt-in but will become the default in future versions of Storybook. + + +[`vue-component-meta`](https://github.com/vuejs/language-tools/tree/master/packages/component-meta) is a tool maintained by the Vue team that extracts metadata from Vue components. Storybook can use it to generate the [controls](../essentials/controls.md) for your stories and documentation. It's a more full-featured alternative to `vue-docgen-api` and is recommended for most projects. If you want to use `vue-component-meta`, you can configure it in your `.storybook/main.js|ts` file: @@ -143,44 +147,43 @@ To provide a description for a prop, including tags, you can use JSDoc comments ```html ``` -### Events types extraction - - +The props definition above will generate the following controls: -Due to technical limitations of Volar / vue language features, JSDoc descriptions for emitted events can not be extracted. +![Controls generated from props](./vue-component-meta-prop-types-controls.png) - +### Events types extraction -To provide a type for an emitted event, you can use TypeScript types in your component's `defineEmits` call: +To provide a type for an emitted event, you can use TypeScript types (including JSDoc comments) in your component's `defineEmits` call: ```html ``` -The definition above will generate the following controls: +If you use `defineSlots`, you can provide a description for each slot using JSDoc comments in your component's slots definition: -![Controls generated from slots](./vue-component-meta-slot-types-controls.png) - -If using `defineSlots`, the controls will even include the description: ```ts defineSlots<{ - /** Example description no-bind. */ - noBind(props: {}): any; - /** Example description default. */ + /** Example description for default */ default(props: { num: number }): any; - /** Example description named. */ + /** Example description for named */ named(props: { str: string }): any; - /** Example description vbind. */ + /** Example description for no-bind */ + noBind(props: {}): any; + /** Example description for vbind */ vbind(props: { num: number; str: string }): any; }>(); +``` + +The definition above will generate the following controls: + +![Controls generated from slots](./vue-component-meta-slot-types-controls.png) ### Exposed properties and methods @@ -240,13 +245,9 @@ The properties and methods exposed by your component are automatically extracted const count = ref(100); defineExpose({ - /** - * a label string - */ + /** A label string */ label, - /** - * a count number - */ + /** A count number */ count, }); @@ -256,6 +257,16 @@ The definition above will generate the following controls: ![Controls generated from exposed properties and methods](./vue-component-meta-exposed-types-controls.png) +### Limitations + +`vue-component-meta` cannot currently reference types from an import alias. You will need to replace any aliased imports with relative ones, as in the example below. See [this issue](https://github.com/vuejs/language-tools/issues/3896) for more information. + +```ts +// YourComponent.ts +import type { MyProps } from '@/types'; // ❌ Cannot be resolved +import type { MyProps } from '../types'; // ✅ Can be resolved +``` + ## API ### Options @@ -284,4 +295,6 @@ Type: `'vue-docgen-api' | 'vue-component-meta'` Default: `'vue-docgen-api'` +Since: `8.0` + Choose which docgen tool to use when generating controls for your components. See [Using `vue-component-meta`](#using-vue-component-meta) for more information. diff --git a/docs/toc.js b/docs/toc.js index a08a9a4a767e..a0d247bd9b8f 100644 --- a/docs/toc.js +++ b/docs/toc.js @@ -29,8 +29,8 @@ module.exports = { type: 'link', }, { - pathSegment: 'vue-vite', - title: 'vue-vite', + pathSegment: 'vue3-vite', + title: 'Vue & Vite', type: 'link', }, ],