Vue CLI Plugin for Styleguidist

Common errors

• Error: Cannot find module '@vue/cli-service'

  cause The `@vue/cli-service` package, a peer dependency, is not installed or incorrectly linked.
  fix Ensure `@vue/cli-service` is installed in your project: `npm install @vue/cli-service` or `yarn add @vue/cli-service`.

• TypeError: Cannot read properties of undefined (reading 'path') in webpack config

  cause Often indicates an issue with `webpack` version compatibility or incorrect configuration within `styleguide.config.js` that interferes with webpack's module resolution.
  fix Update `webpack` to a compatible version as specified by `vue-cli-plugin-styleguidist`'s peer dependencies. Review your `styleguide.config.js` for any custom webpack modifications that might be causing the issue.

• No component found in <path/to/components>

  cause Vue Styleguidist could not locate any Vue components at the specified glob path in `styleguide.config.js` or the components are not properly exported.
  fix Double-check the `components` glob pattern in your `styleguide.config.js` to ensure it correctly matches your component files. Verify that your components are valid Vue components and are discoverable.

Warnings

• breaking Versions of `vue-cli-plugin-styleguidist` and its underlying `vue-styleguidist` dependency prior to `4.72.4` may experience compatibility issues when used with Vue 3.3.2 due to internal changes in Vue's reactivity system or compiler. Updating to `4.72.4` or newer is crucial for stable operation with Vue 3.3.2.
  Fix: Upgrade to `vue-cli-plugin-styleguidist@4.72.4` or higher. Ensure your `package.json` allows for the update, then run `npm update vue-cli-plugin-styleguidist` or `yarn upgrade vue-cli-plugin-styleguidist`.
• gotcha The plugin is specifically designed for Vue CLI 3.0+ projects. While it might function with newer Vue CLI versions (e.g., 4.x or 5.x) or non-CLI setups (like Vite), full compatibility and all features are best guaranteed within the Vue CLI 3.x ecosystem. Using it outside this context may lead to unexpected behavior or require manual configuration adjustments.
  Fix: Ensure your project is managed by Vue CLI 3.x. For newer setups, consider directly integrating `vue-styleguidist` without the plugin or exploring alternative documentation solutions native to your build system.
• gotcha The documentation generation relies heavily on `vue-docgen-api`. Older versions of this dependency (e.g., prior to `4.79.2`) had known bugs, such as failing to parse interface extensions or type alias references correctly, leading to incomplete or incorrect component documentation. Users might need to explicitly update `vue-docgen-api` if their project's dependency resolution pulls an older version.
  Fix: Check your `package-lock.json` or `yarn.lock` for the `vue-docgen-api` version. If it's below `4.79.2`, try updating your root dependencies, or manually add `"vue-docgen-api": ">=4.79.2"` to your `package.json` to force an upgrade.
• gotcha The plugin relies on peer dependencies `@vue/cli-service` and `webpack`. Mismatched versions of these peer dependencies can cause build errors or runtime issues when generating the style guide. Always ensure these peer dependencies meet the requirements specified by `vue-cli-plugin-styleguidist`.
  Fix: Verify that your installed versions of `@vue/cli-service` and `webpack` satisfy the peer dependency ranges listed in `vue-cli-plugin-styleguidist`'s `package.json`. Use `npm ls <package>` or `yarn why <package>` to inspect installed versions and update if necessary.

Install

• npm install vue-cli-plugin-styleguidist npm
• yarn add vue-cli-plugin-styleguidist yarn
• pnpm add vue-cli-plugin-styleguidist pnpm

Imports

• StyleguidistConfig

  import type { StyleguidistConfig } from 'vue-styleguidist';

  While this plugin itself doesn't export this symbol, it's the primary configuration type for `styleguide.config.ts`, which the plugin sets up. It's imported from the underlying `vue-styleguidist` package.
• parse

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

  For advanced use cases, such as creating custom documentation generators or parsers, developers might directly use `vue-docgen-api`. This package is a core dependency of `vue-styleguidist` which this plugin integrates.
• setup

  /* No direct programmatic import for 'setup' from this plugin. */

  The primary interaction with `vue-cli-plugin-styleguidist` is via Vue CLI commands (`vue add styleguidist`) and not through direct programmatic imports of a 'setup' function. Its role is to configure and run `vue-styleguidist`.

Quickstart

Demonstrates how to install the plugin, add it to a Vue CLI project, and run the style guide command to generate documentation.

vue create my-project
cd my-project
vue add styleguidist

# The plugin will prompt you for configuration details.
# After installation, generate the styleguide:
yarn styleguide

# This will typically open the style guide in your browser.
# To customize, edit the generated `styleguide.config.js` or `styleguide.config.ts`.
// Example of a basic component in src/components/MyComponent.vue
// <template>
//   <button :class="{ primary }" @click="$emit('click')">{{ label }}</button>
// </template>
// <script setup lang="ts">
// import { defineProps, defineEmits } from 'vue';
//
// interface Props {
//   label: string;
//   primary?: boolean;
// }
//
// const props = defineProps<Props>();
// const emit = defineEmits<{ (e: 'click'): void }>();
// </script>
// <style scoped>
// .primary { background-color: blue; color: white; }
// </style>