{"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,"search_vec":"'3.3':91 '4.79.2':63 'abil':115 'activ':75 'alias':111 'analyz':40 'api':4,8,99 'autom':55 'babel/parser':38 'behavior':20 'bug':80 'build':136 'cadenc':68 'code':42 'compon':2,24,31,41,122,139 'configur':98 'consist':66 'core':149 'crucial':53 'current':59 'custom':103,142 'defineemit':87 'design':13,137 'detail':17 'develop':76 'differenti':94 'docgen':7 'document':3,56,143,160 'documentation-gener':159 'essenti':132 'event':47 'export':123 'extend':106 'extract':16 'featur':85 'file':25,30,127 'fix':81 'generat':57,161 'handl':117 'handler':104 'high':97 'includ':95 'indic':74 'inform':21 'insight':44 'javascript':33,157 'jsdoc':162 'key':93 'leverag':37 'librari':140 'like':86,153 'logic':108 'make':129 'method':50 'minor':72 'multipl':121 'new':83 'often':145 'option':101 'pars':107,163 'parser':150 'patch':70 'path':112 'platform':144 'programmat':15 'project':135 'prop':46 'provid':43 'releas':67 'respons':78 'robust':11 'sfcs':32 'singl':29,119,126 'slot':48 'stabl':60 'structur':18 'styleguidist':156 'support':109 'syntax':88 'system':138 'tool':152 'toolbox':12 'typescript':35,164 'updat':73 'use':146 'util':133 'version':61 'vue':1,6,23,84,90,155,158 'vue-docgen-api':5 'vue-styleguidist':154 'whether':26 'within':124","created_at":"2026-04-19T13:43:16.540384+00:00","updated_at":"2026-04-19T13:43:16.540384+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://vue-styleguidist.github.io","github":"https://github.com/vue-styleguidist/vue-styleguidist","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vue-docgen-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}