Registry / testing / vue-docgen-api

vue-docgen-api

JSON →
library4.79.2jsnpmunverified

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`.

npm install vue-docgen-api
INSTALL
IMPORT
SIG · VUE-DOCGEN-API
V
vue-docgen-api
testingjavascriptv4.79.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse
✓ import { parse } from 'vue-docgen-api';
✗ const parse = require('vue-docgen-api').parse;
The `parse` function is used for single-component files. It will throw an error if multiple components are detected.
parseMulti
✓ import { parseMulti } from 'vue-docgen-api';
✗ const parseMulti = require('vue-docgen-api').parseMulti;
Use `parseMulti` when a file might export more than one Vue component, returning an array of documentation objects.
parseSource
✓ import { parseSource } from 'vue-docgen-api';
✗ import { parse } from 'vue-docgen-api'; // then try to pass source string instead of path
This function parses a component from a string source directly, instead of a file path, useful for in-memory or dynamically generated components.
DocGenOptions
✓ import type { DocGenOptions } from 'vue-docgen-api';
TypeScript type for configuration options passed to `parse` or `parseMulti`.

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.

import { parseSource } from 'vue-docgen-api'; import { resolve } from 'path'; async function generateComponentDoc() { const componentSource = ` <template> <div>{{ message }} <button @click="increment">Click me</button></div> </template> <script lang="ts"> import { defineComponent, ref } from 'vue'; /** * A simple counter component demonstrating props, emits, and methods. * @displayName MyCounterComponent */ export default defineComponent({ props: { /** * Initial count value for the component. */ initialCount: { type: Number, default: 0 }, /** * Message to display alongside the count. */ message: { type: String, required: true } }, emits: { /** * Emitted when the count value changes. * @property {number} newCount - The updated count value. */ 'update:count': (newCount: number) => newCount >= 0 }, setup(props, { emit }) { const count = ref(props.initialCount); /** * Increments the internal count and emits the updated value. */ function increment() { count.value++; emit('update:count', count.value); } return { count, increment }; } }); </script> `; try { // The second argument 'MyCounter.vue' is a dummy path used for resolution contexts. const componentInfo = await parseSource(componentSource, 'MyCounter.vue', { jsx: true, // Enable JSX parsing if your components use it alias: { '@': resolve(__dirname, './src') // Configure path aliases similar to webpack or tsconfig } }); console.log('Component Display Name:', componentInfo.displayName); console.log('Props:', componentInfo.props?.map(p => `${p.name} (${p.type?.name || 'any'})`)); console.log('Events:', componentInfo.events?.map(e => e.name)); // console.log(JSON.stringify(componentInfo, null, 2)); // Uncomment for full output } catch (error) { console.error('Error parsing component:', error); } } generateComponentDoc();
Debug
Known issues
gotchaWhen a file contains multiple Vue components, the `parse()` function will throw an error. You must use `parseMulti()` instead.
fix
Replace `parse(filePath)` with `parseMulti(filePath)` and handle the returned array of ComponentDoc objects.
affects: >=1.0.0
gotchaAlias 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.
fix
Carefully order your `alias` configurations, placing more specific aliases before general ones. Test your alias resolutions thoroughly to ensure they match expectations.
affects: >=1.0.0
breakingOlder versions of `vue-docgen-api` had a bug where parsing Vue 3 components with interface extensions (`extends SomeInterface`) would break the tool.
fix
Upgrade to `vue-docgen-api@4.79.2` or higher to resolve issues with interface extension parsing.
affects: <4.79.2
gotchaCompatibility 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.
fix
Ensure `vue-docgen-api` is at version `4.72.4` or higher for full compatibility with Vue 3.3.2 and later.
affects: <4.72.4
gotcha`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.
fix
Upgrade to `vue-docgen-api@4.75.0` or newer to ensure correct parsing of components utilizing Vue 3.3's `defineEmits` syntax.
affects: <4.75.0
Errors
Common errors & fixes
Error: This file exports multiple components. Use `parseMulti` instead.
Attempting to parse a `.vue` file or `.ts`/`.js` file that defines and exports more than one Vue component using the `parse()` function.
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.
Failed to parse the Props passed to Macro function as Type alias reference
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.
fix
Update `vue-docgen-api` to version `4.79.1` or higher. This specific issue was addressed in that patch version.
Cannot resolve module '@assets/image.png' in src/components/MyComponent.vue
The `alias` option is not correctly configured or does not match the webpack/TypeScript path aliases used in your project's build setup.
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.
Upgrade
Version history
4.79.2latest on npm
Audit
Dependencies
vuerequiredPeer dependency, required for parsing Vue component syntax.
Agent activity
12 hits · last 30 days
node
10
Resources