Vue Docgen CLI

Common errors

• Error: Minimum Node.js version 16.3 is required. You are using Node.js X.Y.Z.

  cause Running vue-docgen-cli on a Node.js version older than 16.3.
  fix Upgrade 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

  cause A bug in vue-docgen-api prevented correct parsing of Type alias references within macro functions.
  fix Update 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')

  cause A bug related to parsing interface extensions in Vue components.
  fix Update 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

  cause The glob pattern provided to vue-docgen-cli did not match any existing component files, or the `componentsRoot` was misconfigured.
  fix Verify 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.

Warnings

• breaking vue-docgen-cli requires Node.js version 16.3 or higher. Running on older Node.js environments will result in errors.
  Fix: Upgrade your Node.js environment to version 16.3 or newer. Use a Node Version Manager (e.g., nvm) for easy switching.
• gotcha Older 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.
  Fix: Ensure you are using vue-docgen-cli version 4.75.0 or newer to guarantee compatibility with Vue 3.3+ features. Update your package dependencies.
• gotcha The `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`.
  Fix: Use 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.
• gotcha Alias 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.
  Fix: Explicitly 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 }`).

Install

• npm install vue-docgen-cli npm
• yarn add vue-docgen-cli yarn
• pnpm add vue-docgen-cli pnpm

Imports

• DocgenCLIConfig
  wrong:

  import { DocgenCLIConfig } from 'vue-docgen-cli';

  correct:

  import type { 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
  wrong:

  const generate = require('vue-docgen-cli').generate;

  correct:

  import { generate } from 'vue-docgen-cli';

  While primarily a CLI, advanced users might programmatically invoke its generation function. The `docgen.config.js` itself is typically CommonJS.
• componentTemplate
  wrong:

  import componentTemplate from 'vue-docgen-cli/dist/templates/component';

  correct:

  import { componentTemplate } from 'vue-docgen-cli/dist/templates';

  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.

Quickstart

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