{"id":12459,"library":"vue-docgen-api","title":"Vue Component Documentation API","description":"vue-docgen-api is a robust toolbox designed to programmatically extract detailed structural and behavioral information from Vue component files, whether they are Single File Components (SFCs), JavaScript, or TypeScript. It leverages `@babel/parser` to analyze component code, providing insights into props, events, slots, and methods, which is crucial for automated documentation generation. The current stable version is `4.79.2`, with a consistent release cadence of patch and minor updates, indicating active development and responsiveness to bug fixes and new Vue features (like `defineEmits` syntax in Vue 3.3). Its key differentiators include a highly configurable API with options for custom handlers to extend parsing logic, support for aliased paths, and the ability to handle both single and multiple component exports within a single file. This makes it an essential utility for projects building design systems, component libraries, or custom documentation platforms, often used as the core parser for tools like `vue-styleguidist`.","status":"active","version":"4.79.2","language":"javascript","source_language":"en","source_url":"https://github.com/vue-styleguidist/vue-styleguidist","tags":["javascript","vue","documentation-generation","jsdoc","parse","typescript"],"install":[{"cmd":"npm install vue-docgen-api","lang":"bash","label":"npm"},{"cmd":"yarn add vue-docgen-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-docgen-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for parsing Vue component syntax.","package":"vue","optional":false}],"imports":[{"note":"The `parse` function is used for single-component files. It will throw an error if multiple components are detected.","wrong":"const parse = require('vue-docgen-api').parse;","symbol":"parse","correct":"import { parse } from 'vue-docgen-api';"},{"note":"Use `parseMulti` when a file might export more than one Vue component, returning an array of documentation objects.","wrong":"const parseMulti = require('vue-docgen-api').parseMulti;","symbol":"parseMulti","correct":"import { parseMulti } from 'vue-docgen-api';"},{"note":"This function parses a component from a string source directly, instead of a file path, useful for in-memory or dynamically generated components.","wrong":"import { parse } from 'vue-docgen-api'; // then try to pass source string instead of path","symbol":"parseSource","correct":"import { parseSource } from 'vue-docgen-api';"},{"note":"TypeScript type for configuration options passed to `parse` or `parseMulti`.","symbol":"DocGenOptions","correct":"import type { DocGenOptions } from 'vue-docgen-api';"}],"quickstart":{"code":"import { parseSource } from 'vue-docgen-api';\nimport { resolve } from 'path';\n\nasync function generateComponentDoc() {\n  const componentSource = `\n    <template>\n      <div>{{ message }} <button @click=\"increment\">Click me</button></div>\n    </template>\n    <script lang=\"ts\">\n    import { defineComponent, ref } from 'vue';\n\n    /**\n     * A simple counter component demonstrating props, emits, and methods.\n     * @displayName MyCounterComponent\n     */\n    export default defineComponent({\n      props: {\n        /**\n         * Initial count value for the component.\n         */\n        initialCount: {\n          type: Number,\n          default: 0\n        },\n        /**\n         * Message to display alongside the count.\n         */\n        message: {\n          type: String,\n          required: true\n        }\n      },\n      emits: {\n        /**\n         * Emitted when the count value changes.\n         * @property {number} newCount - The updated count value.\n         */\n        'update:count': (newCount: number) => newCount >= 0\n      },\n      setup(props, { emit }) {\n        const count = ref(props.initialCount);\n\n        /**\n         * Increments the internal count and emits the updated value.\n         */\n        function increment() {\n          count.value++;\n          emit('update:count', count.value);\n        }\n\n        return {\n          count,\n          increment\n        };\n      }\n    });\n    </script>\n    `;\n\n  try {\n    // The second argument 'MyCounter.vue' is a dummy path used for resolution contexts.\n    const componentInfo = await parseSource(componentSource, 'MyCounter.vue', {\n      jsx: true, // Enable JSX parsing if your components use it\n      alias: {\n        '@': resolve(__dirname, './src') // Configure path aliases similar to webpack or tsconfig\n      }\n    });\n    console.log('Component Display Name:', componentInfo.displayName);\n    console.log('Props:', componentInfo.props?.map(p => `${p.name} (${p.type?.name || 'any'})`));\n    console.log('Events:', componentInfo.events?.map(e => e.name));\n    // console.log(JSON.stringify(componentInfo, null, 2)); // Uncomment for full output\n  } catch (error) {\n    console.error('Error parsing component:', error);\n  }\n}\n\ngenerateComponentDoc();\n","lang":"typescript","description":"This quickstart demonstrates how to use `parseSource` to extract documentation information from a Vue 3 component defined as a string, including props, emits, and methods. It also shows how to configure `jsx` and `alias` options."},"warnings":[{"fix":"Replace `parse(filePath)` with `parseMulti(filePath)` and handle the returned array of ComponentDoc objects.","message":"When a file contains multiple Vue components, the `parse()` function will throw an error. You must use `parseMulti()` instead.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully order your `alias` configurations, placing more specific aliases before general ones. Test your alias resolutions thoroughly to ensure they match expectations.","message":"Alias resolution in `vue-docgen-api` (via the `alias` option) is a simple path replacement and does not fully emulate Webpack's complex resolution logic. The order of aliases matters, as the first matching alias will be applied.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `vue-docgen-api@4.79.2` or higher to resolve issues with interface extension parsing.","message":"Older versions of `vue-docgen-api` had a bug where parsing Vue 3 components with interface extensions (`extends SomeInterface`) would break the tool.","severity":"breaking","affected_versions":"<4.79.2"},{"fix":"Ensure `vue-docgen-api` is at version `4.72.4` or higher for full compatibility with Vue 3.3.2 and later.","message":"Compatibility issues were identified with Vue version 3.3.2, potentially affecting parsing accuracy for components using specific new features or syntax introduced in that Vue patch.","severity":"gotcha","affected_versions":"<4.72.4"},{"fix":"Upgrade to `vue-docgen-api@4.75.0` or newer to ensure correct parsing of components utilizing Vue 3.3's `defineEmits` syntax.","message":"`vue-docgen-api` added specific support for the new `defineEmits` syntax introduced in Vue 3.3. Older versions might not correctly parse emit declarations using this syntax.","severity":"gotcha","affected_versions":"<4.75.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import and function call from `parse(filePath)` to `parseMulti(filePath)`. The `parseMulti` function returns an array of component documentation objects, one for each component found in the file.","cause":"Attempting to parse a `.vue` file or `.ts`/`.js` file that defines and exports more than one Vue component using the `parse()` function.","error":"Error: This file exports multiple components. Use `parseMulti` instead."},{"fix":"Update `vue-docgen-api` to version `4.79.1` or higher. This specific issue was addressed in that patch version.","cause":"A bug in `vue-docgen-api` prevented correct parsing of prop definitions that referenced type aliases within a macro function, leading to silent failures or incorrect documentation.","error":"Failed to parse the Props passed to Macro function as Type alias reference"},{"fix":"Pass a `DocGenOptions` object to `parse` or `parseMulti` with the `alias` property configured to mirror your project's alias settings. For example: `{ alias: { '@assets': path.resolve(__dirname, 'src/assets') } }`. Ensure the order of aliases is correct if you have overlapping patterns.","cause":"The `alias` option is not correctly configured or does not match the webpack/TypeScript path aliases used in your project's build setup.","error":"Cannot resolve module '@assets/image.png' in src/components/MyComponent.vue"}],"ecosystem":"npm"}