{"id":12587,"library":"vue-styleguidist","title":"Vue Styleguidist","description":"Vue Styleguidist is a living style guide generator and isolated development environment for Vue components. It enables developers to document components with live, editable usage examples based on Markdown files, fostering a component-driven development workflow. Currently at version 4.72.4, it generally maintains a frequent patch and minor release cadence, often addressing compatibility with newer Vue versions or fixing parsing issues in its underlying `vue-docgen-api` dependency. Its key differentiators include its heritage from React Styleguidist, providing a similar interactive documentation experience, and its specific tooling for parsing and compiling `.vue` single-file components. It supports both Vue 2 and Vue 3 environments (requiring appropriate `vue-loader` and `@vue/compiler-sfc` peer dependencies respectively) and integrates with webpack for asset loading.","status":"active","version":"4.72.4","language":"javascript","source_language":"en","source_url":"https://github.com/vue-styleguidist/vue-styleguidist","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-styleguidist","lang":"bash","label":"npm"},{"cmd":"yarn add vue-styleguidist","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-styleguidist","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Vue 3 component compilation and parsing.","package":"@vue/compiler-sfc","optional":false},{"reason":"Needed if you use Pug (Jade) templates within your Vue components.","package":"pug","optional":true},{"reason":"The core Vue.js library for component rendering and reactivity.","package":"vue","optional":false},{"reason":"Webpack loader for Vue Single File Components (.vue files). Essential for compilation.","package":"vue-loader","optional":false},{"reason":"Required for Vue 2 component compilation and parsing. Not needed for Vue 3.","package":"vue-template-compiler","optional":true},{"reason":"The underlying module bundler used by Styleguidist to process components.","package":"webpack","optional":false}],"imports":[{"note":"The Node API for `vue-styleguidist` is primarily exposed via CommonJS `require` for its main factory function, which takes a configuration object. While ESM imports might work with bundlers, the official documentation uses CJS.","wrong":"import styleguidist from 'vue-styleguidist';","symbol":"styleguidist","correct":"const styleguidist = require('vue-styleguidist')(config);"},{"note":"When using TypeScript, import `Configuration` as a type for your `styleguide.config.js` file to get type-checking for the configuration object. It's a type, not a runtime value.","wrong":"import { Configuration } from 'vue-styleguidist';","symbol":"Configuration","correct":"import type { Configuration } from 'vue-styleguidist';"},{"note":"The primary configuration file `styleguide.config.js` expects a CommonJS export. Using `export default` might cause issues unless your environment is configured for ESM in config files (which is less common for tools like this).","wrong":"export default { /* ...config */ };","symbol":"styleguide.config.js export","correct":"module.exports = { /* ...config */ };"}],"quickstart":{"code":"npm install --save-dev vue-styleguidist vue@^3 @vue/compiler-sfc webpack@^5 vue-loader@^17 style-loader css-loader babel-loader @babel/core @babel/preset-env\n\n# Create styleguide.config.js\n// styleguide.config.js\nconst path = require('path');\n\nmodule.exports = {\n  title: 'My Vue Component Style Guide',\n  // Adjust components glob to match your project structure\n  components: 'src/components/**/*.vue',\n  defaultExample: true,\n  // Required for Vue 3 setup, or if you have specific compilation needs\n  compiler: 'vue-styleguidist/lib/loaders/vue-standalone-compiler',\n  webpackConfig: {\n    module: {\n      rules: [\n        {\n          test: /\\.vue$/,\n          loader: 'vue-loader',\n        },\n        {\n          test: /\\.(js|ts)$/,\n          exclude: /node_modules/,\n          use: {\n            loader: 'babel-loader',\n            options: {\n              presets: ['@babel/preset-env']\n            }\n          }\n        },\n        {\n          test: /\\.css$/,\n          use: ['style-loader', 'css-loader'],\n        },\n      ],\n    },\n    resolve: {\n      alias: {\n        // Essential for Vue 3 to resolve the correct Vue instance\n        'vue': path.resolve(__dirname, 'node_modules/vue'),\n      },\n      extensions: ['.vue', '.js', '.ts', '.json'],\n    },\n  },\n  styleguideDir: 'dist-styleguide',\n};\n\n\n# Create src/components/MyButton.vue\n// src/components/MyButton.vue\n<template>\n  <button :style=\"{ backgroundColor: color }\" @click=\"onClick\">\n    {{ label }}\n  </button>\n</template>\n\n<script lang=\"ts\">\nimport { defineComponent } from 'vue';\n\nexport default defineComponent({\n  name: 'MyButton',\n  props: {\n    label: {\n      type: String,\n      required: true,\n    },\n    color: {\n      type: String,\n      default: 'blue',\n    },\n  },\n  emits: ['click'],\n  setup(props, { emit }) {\n    const onClick = () => {\n      console.log(`Button '${props.label}' clicked!`);\n      emit('click');\n    };\n    return {\n      onClick,\n    };\n  },\n});\n</script>\n\n<style scoped>\nbutton {\n  padding: 10px 20px;\n  border: none;\n  border-radius: 4px;\n  color: white;\n  cursor: pointer;\n}\n</style>\n\n<docs>\nThis is a simple button component with customizable label and color.\n\n```vue\n<MyButton label=\"Click Me!\" />\n<MyButton label=\"Submit\" color=\"#4CAF50\" />\n<MyButton label=\"Danger\" color=\"#f44336\" @click=\"alert('Danger button clicked!')\" />\n```\n</docs>\n\n# Run Styleguidist\nnpx styleguidist server\n# or to build a static style guide\nnpx styleguidist build","lang":"typescript","description":"This quickstart demonstrates how to set up Vue Styleguidist for Vue 3 with a basic component, including a `styleguide.config.js` for webpack configuration and a `.vue` component with embedded documentation using TypeScript."},"warnings":[{"fix":"Carefully review the required peer dependencies for your specific Vue version. For Vue 3, ensure `@vue/compiler-sfc` and `vue-loader@^17` are installed. For Vue 2, use `vue-template-compiler` and `vue-loader@^15` (or older compatible versions).","message":"Vue Styleguidist requires specific peer dependencies (`vue`, `vue-loader`, `webpack`, `@vue/compiler-sfc` for Vue 3, or `vue-template-compiler` for Vue 2) to be installed and correctly configured. Incompatibility or missing packages are a common source of errors.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"For Vue 3 projects, explicitly set `compiler: 'vue-styleguidist/lib/loaders/vue-standalone-compiler'` in your `styleguide.config.js`. Ensure your `webpackConfig.resolve.alias` includes `'vue': path.resolve(__dirname, 'node_modules/vue')` and use `vue-loader` version 17 or later with compatible webpack.","message":"Migrating from Vue 2 to Vue 3 often requires significant changes to the `styleguide.config.js` file, especially regarding the Vue compiler and `vue-loader` setup, and potentially `resolve.alias` for 'vue'.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use `module.exports = { ... }` in your `styleguide.config.js` and `require()` for any Node API interactions to ensure compatibility with Vue Styleguidist's internal tooling.","message":"The documentation examples and Node API predominantly use CommonJS (`require`). While modern projects favor ESM, sticking to CommonJS for configuration files (`styleguide.config.js`) is safer to avoid tooling conflicts.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Thoroughly check your `webpackConfig` within `styleguide.config.js`. Ensure you have rules for `.vue` files (with `vue-loader`), `.js`/`.ts` files (with `babel-loader` or `ts-loader`), and CSS files. Verify `resolve.extensions` includes all necessary file types.","message":"Webpack configuration within `styleguide.config.js` is crucial and can be complex. Incorrect `module.rules`, `resolve.alias`, or missing loaders can prevent components from being parsed or rendered correctly.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Vue 2: `npm install vue-template-compiler`. For Vue 3: `npm install @vue/compiler-sfc`. Also, ensure `styleguide.config.js` has `compiler: 'vue-styleguidist/lib/loaders/vue-standalone-compiler'` for Vue 3.","cause":"Missing the appropriate Vue compiler package for your Vue version.","error":"[Vue Styleguidist] Error: Cannot find module 'vue-template-compiler' or '@vue/compiler-sfc'"},{"fix":"Install `vue-loader`: `npm install vue-loader`. Then, ensure your `styleguide.config.js` `webpackConfig.module.rules` includes a rule like `{ test: /\\.vue$/, loader: 'vue-loader' }`.","cause":"The `vue-loader` package is not installed or the webpack rule for `.vue` files is incorrect or missing.","error":"Webpack config: 'vue-loader' is not found (or similar 'Module not found' for vue-loader)"},{"fix":"Add a `resolve.alias` entry in your `styleguide.config.js` `webpackConfig`: `alias: { 'vue': path.resolve(__dirname, 'node_modules/vue') }`.","cause":"Webpack is unable to correctly resolve the 'vue' package, often due to an incorrect or missing alias, especially in Vue 3 setups where 'vue' might point to a runtime-only build.","error":"Module not found: Error: Can't resolve 'vue' in '...'"},{"fix":"Verify the `components` array/string in `styleguide.config.js` (e.g., `components: 'src/components/**/*.vue'`) precisely matches the actual file paths of your Vue components.","cause":"The `components` glob pattern in `styleguide.config.js` does not match any existing `.vue` files in your project.","error":"[Vue Styleguidist] Error: No components found. Make sure you have specified the components option correctly."}],"ecosystem":"npm"}