Vue Component Documentation Webpack Loader

2.0.1 · active · verified Tue Apr 21

vue-docgen-loader is a Webpack loader designed to parse Vue component files, including single-file components (.vue) and standard JavaScript/TypeScript files exporting Vue components. It leverages vue-docgen-api to extract detailed documentation metadata (props, events, methods, slots, etc.) and injects this information directly into the compiled component's module export. This enables various development tools, such as automatically generated style guides (e.g., Vue Styleguidist), component explorers, or dynamic property editors, to access component specifications at runtime. The current stable version is 2.0.1. While there isn't a strict release cadence, updates appear to be made as needed, often for dependency bumps or feature enhancements. Its primary differentiation lies in seamlessly integrating documentation generation into the Webpack build pipeline, making component documentation an intrinsic part of the application bundle.

Common errors

```
Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/configuration/module/#module-rules
```
cause `vue-loader` is either missing or configured incorrectly, preventing `.vue` files from being transformed into valid JavaScript before `vue-docgen-loader` attempts to process them.

fix Ensure `vue-loader` is correctly configured in your `webpack.config.js` rules array for `.vue` files and that `VueLoaderPlugin` is added to your plugins. The `vue-docgen-loader` rule should typically follow it with `enforce: 'post'`.
```
Error: Cannot find module 'vue-docgen-loader' from '...' (or similar loader resolution error like 'Module not found: Error: Can't resolve 'vue-docgen-loader'')'
```
cause `vue-docgen-loader` is not installed as a dependency in your project or Webpack cannot resolve its path.

fix Run `npm install --save-dev vue-docgen-loader vue-docgen-api` (or `yarn add -D vue-docgen-loader vue-docgen-api`) to ensure both the loader and its core parsing dependency are installed and available to Webpack.
```
TypeError: this.__docgenInfo is undefined (or similar runtime error accessing injected property)
```
cause `vue-docgen-loader` either failed to execute, or its configuration (e.g., `injectAt` option) differs from where you are attempting to access the documentation object within your Vue component.

fix Verify that `vue-docgen-loader` is correctly applied in your `webpack.config.js` with `enforce: 'post'`, that `vue-docgen-api` is installed, and that the `injectAt` option matches the property name you are trying to access on the component instance (e.g., `this.__docgenInfo`).

Warnings

breaking Loader ordering is critical: `vue-docgen-loader` *must* run after `vue-loader` for Single File Components. Incorrect order will lead to parsing failures or missing documentation.
Fix: Ensure your webpack rule for `vue-docgen-loader` includes `enforce: 'post'` to guarantee correct execution order after other loaders like `vue-loader`.
gotcha When applying `vue-docgen-loader` to non-SFC JavaScript files (e.g., `my-button.js` exporting a Vue component), do not use the `?vue` resource query. This query is silently injected by `vue-loader` and will break the module's processing by `vue-docgen-loader`.
Fix: For non-SFC files, use a distinct `resourceQuery` like `?component` (e.g., `import MyButton from './my-button.js?component'`) and configure the loader rule to match only that specific query (e.g., `resourceQuery: /component/`).
gotcha Support for parsing non-SFC JavaScript files (e.g., `.js` or `.ts` files exporting Vue components) through `vue-docgen-loader` requires `vue-docgen-api` version 4.0.0 or higher.
Fix: Upgrade your `vue-docgen-api` peer dependency to `^4.0.0` or higher to enable comprehensive non-SFC file parsing capabilities.
gotcha Missing peer dependencies `vue-docgen-api` or `webpack` will cause Webpack compilation errors or runtime failures for the loader.
Fix: Install `vue-docgen-api` (e.g., `npm install vue-docgen-api`) and ensure `webpack` is installed in your project (e.g., `npm install webpack`). Consult your `package.json` and the loader's requirements for specific version ranges.

Install

npm install vue-docgen-loader npm
yarn add vue-docgen-loader yarn
pnpm add vue-docgen-loader pnpm

Imports

vue-docgen-loader (in webpack config)
wrong:
```
import { loader } from 'vue-docgen-loader'
```
correct:
```
loader: 'vue-docgen-loader'
```
Webpack loaders are referenced by their package name string within the webpack configuration rules, not as an importable module itself.
Component with injected docgen info
wrong:
```
import { __docgenInfo } from './MyComponent.vue'
```
correct:
```
import MyComponent from './MyComponent.vue'; console.log(MyComponent.__docgenInfo);
```
The documentation object is injected as a property onto the component's default export (typically `__docgenInfo` by default), not as a named export. It is accessible on the component's options object or `this` inside the component instance.
VueLoaderPlugin (for .vue files)
wrong:
```
import VueLoaderPlugin from 'vue-loader/lib/plugin';
```
correct:
```
const { VueLoaderPlugin } = require('vue-loader');
```
The `VueLoaderPlugin` is essential for processing Vue Single File Components. Modern webpack configurations often use CommonJS `require` for plugins, though ESM `import` is also supported if your webpack config is set up for it. Avoid deprecated paths.

Quickstart

Configures Webpack to use `vue-docgen-loader` for Vue Single File Components, ensuring documentation metadata is injected into component exports at `__docgenInfo` for runtime access. It demonstrates `enforce: 'post'` for correct loader ordering and basic setup with `vue-loader` and `HtmlWebpackPlugin` for a runnable development server.

const path = require('path');
const { VueLoaderPlugin } = require('vue-loader');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'development',
  entry: './src/main.js', // Assuming a main entry point for a Vue app
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      },
      {
        // Apply vue-docgen-loader to Vue Single File Components.
        // 'enforce: "post"' ensures it runs after vue-loader, which is
        // crucial for correctly parsing the Vue component's script.
        test: /\.vue$/,
        loader: 'vue-docgen-loader',
        options: {
          // Customize the property name where documentation will be injected.
          // Default is '__docgenInfo'.
          injectAt: '__docgenInfo'
        },
        enforce: 'post'
      }
    ]
  },
  plugins: [
    new VueLoaderPlugin(),
    new HtmlWebpackPlugin({
      template: './public/index.html',
      filename: 'index.html'
    })
  ],
  resolve: {
    alias: {
      'vue$': 'vue/dist/vue.esm.js'
    }
  },
  devServer: {
    static: {
      directory: path.join(__dirname, 'dist')
    },
    compress: true,
    port: 8080,
    open: true
  }
};

view raw JSON →