Vue Component Documentation API

Common errors

• Error: This file exports multiple components. Use `parseMulti` instead.

  cause 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

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

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

Warnings

• gotcha When 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.
• gotcha 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.
  Fix: Carefully order your `alias` configurations, placing more specific aliases before general ones. Test your alias resolutions thoroughly to ensure they match expectations.
• breaking Older 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.
• gotcha 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.
  Fix: Ensure `vue-docgen-api` is at version `4.72.4` or higher for full compatibility with Vue 3.3.2 and later.
• 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.

Install

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

Imports

• parse
  wrong:

  const parse = require('vue-docgen-api').parse;

  correct:

  import { parse } from 'vue-docgen-api';

  The `parse` function is used for single-component files. It will throw an error if multiple components are detected.
• parseMulti
  wrong:

  const parseMulti = require('vue-docgen-api').parseMulti;

  correct:

  import { parseMulti } from 'vue-docgen-api';

  Use `parseMulti` when a file might export more than one Vue component, returning an array of documentation objects.
• parseSource
  wrong:

  import { parse } from 'vue-docgen-api'; // then try to pass source string instead of path

  correct:

  import { parseSource } from 'vue-docgen-api';

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

Quickstart

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();