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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocgenCLIConfig
✓ import type { DocgenCLIConfig } from 'vue-docgen-cli';
✗ import { DocgenCLIConfig } from 'vue-docgen-cli';
Primarily a CLI tool; direct programmatic imports for library usage are less common. This import is for TypeScript users type-checking their `docgen.config.js` / `.ts` file.
generate
✓ import { generate } from 'vue-docgen-cli';
✗ const generate = require('vue-docgen-cli').generate;
While primarily a CLI, advanced users might programmatically invoke its generation function. The `docgen.config.js` itself is typically CommonJS.
componentTemplate
✓ import { componentTemplate } from 'vue-docgen-cli/dist/templates';
✗ import componentTemplate from 'vue-docgen-cli/dist/templates/component';
For customizing output, users can extend default templates. This path is illustrative as specific internal template module exports may vary and are not explicitly documented for direct import.
This quickstart demonstrates how to install vue-docgen-cli, define a basic Vue component with JSDoc comments, and then use the CLI via npm scripts to generate Markdown documentation for it.
```javascript
// package.json
{
"name": "my-vue-project-docs",
"version": "1.0.0",
"description": "Generate docs for Vue components",
"scripts": {
"docs:generate": "vue-docgen src/components/**/*.vue docs/components",
"docs:watch": "vue-docgen -w src/components/**/*.vue docs/components"
},
"devDependencies": {
"vue-docgen-cli": "^4.79.0"
}
}
// src/components/MyButton.vue
<template>
<button @click="handleClick">{{ label }}</button>
</template>
<script setup lang="ts">
/**
* A universal button component.
* @displayName MyButton
*/
import { ref } from 'vue';
/**
* Props for MyButton.
*/
interface MyButtonProps {
/**
* The text label for the button.
* @type {string}
* @example 'Click Me'
*/
label: string;
/**
* Determines if the button is disabled.
*/
disabled?: boolean;
}
const props = withDefaults(defineProps<MyButtonProps>(), {
disabled: false,
});
const emit = defineEmits<{ (e: 'click', event: MouseEvent): void }>();
const count = ref(0);
/**
* Handles the click event on the button.
* @param {MouseEvent} event - The native mouse event.
* @event click
*/
const handleClick = (event: MouseEvent) => {
if (!props.disabled) {
count.value++;
emit('click', event);
}
};
</script>
// Terminal commands
$ npm install
$ npm run docs:generate
```
vue-docgen --version
Debug
Known issues
breakingvue-docgen-cli requires Node.js version 16.3 or higher. Running on older Node.js environments will result in errors.fixUpgrade your Node.js environment to version 16.3 or newer. Use a Node Version Manager (e.g., nvm) for easy switching.
affects: <4.0.0 (check specific previous versions)
gotchaOlder versions of vue-docgen-cli (and its core dependency vue-docgen-api) may fail to correctly parse newer Vue 3.3+ syntax, specifically `defineEmits` syntax introduced in Vue 3.3. This was addressed in vue-docgen-api@4.75.0 and vue-docgen-cli@4.75.0.fixEnsure you are using vue-docgen-cli version 4.75.0 or newer to guarantee compatibility with Vue 3.3+ features. Update your package dependencies.
affects: <4.75.0
gotchaThe `docgen.config.js` file is processed as a CommonJS module. Using ES Module syntax (`import`/`export`) directly within this configuration file will cause errors unless your project is explicitly configured to handle `.js` files as ES Modules or you rename the config file to `docgen.config.mjs`.fixUse CommonJS `require()` and `module.exports` syntax within your `docgen.config.js`. If you prefer ESM, consider configuring your build process or renaming the file to `.mjs` if the CLI supports it.
affects: >=1.0.0
gotchaAlias resolution (e.g., `@components`) defined in bundlers like Webpack or Vite is not automatically picked up by vue-docgen-cli. This can lead to issues where component imports within your Vue files cannot be resolved during documentation generation, affecting type inference or linking.fixExplicitly inform `vue-docgen-cli` of your aliases through the `apiOptions.alias` property in `docgen.config.js`, typically by importing your bundler's resolve configuration (e.g., `apiOptions: { ...require('./webpack.config').resolve }`). affects: >=1.0.0
Errors
Common errors & fixes
Error: Minimum Node.js version 16.3 is required. You are using Node.js X.Y.Z.
Running vue-docgen-cli on a Node.js version older than 16.3.
fixUpgrade your Node.js environment to version 16.3 or newer. Use 'nvm install 16 && nvm use 16' or similar for your nvm setup.
Failed to parse the Props passed to Macro function as Type alias reference
A bug in vue-docgen-api prevented correct parsing of Type alias references within macro functions.
fixUpdate vue-docgen-cli to version 4.79.1 or newer, which includes a fix for this parsing issue.
TypeError: Cannot read properties of undefined (reading 'extension')
A bug related to parsing interface extensions in Vue components.
fixUpdate vue-docgen-api to version 4.79.2 or newer, which contains a fix for interface extension parsing.
Error: No component files found for glob: src/components/**/*.vue
The glob pattern provided to vue-docgen-cli did not match any existing component files, or the `componentsRoot` was misconfigured.
fixVerify that your `componentsRoot` and `components` glob pattern in `docgen.config.js` (or command-line arguments) accurately reflect the location and naming convention of your Vue components. Ensure the paths are correct relative to your project root.
Audit
Dependencies
vue-docgen-apirequiredCore API for parsing Vue components and extracting documentation.
vueoptionalRequired for compatibility and correct parsing of Vue component syntax.