Registry / web-framework / vue-styleguidist

vue-styleguidist

library4.72.4jsnpmunverified

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.

web-framework

npm install vue-styleguidist

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-STYLEGUIDIST

vue-styleguidist

web-frameworkjavascriptv4.72.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

styleguidist

✓ const styleguidist = require('vue-styleguidist')(config);

✗ import styleguidist from 'vue-styleguidist';

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.

Configuration

✓ import type { Configuration } from 'vue-styleguidist';

✗ import { Configuration } from 'vue-styleguidist';

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.

styleguide.config.js export

✓ module.exports = { /* ...config */ };

✗ export default { /* ...config */ };

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

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.

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 # Create styleguide.config.js // styleguide.config.js const path = require('path'); module.exports = { title: 'My Vue Component Style Guide', // Adjust components glob to match your project structure components: 'src/components/**/*.vue', defaultExample: true, // Required for Vue 3 setup, or if you have specific compilation needs compiler: 'vue-styleguidist/lib/loaders/vue-standalone-compiler', webpackConfig: { module: { rules: [ { test: /\.vue$/, loader: 'vue-loader', }, { test: /\.(js|ts)$/, exclude: /node_modules/, use: { loader: 'babel-loader', options: { presets: ['@babel/preset-env'] } } }, { test: /\.css$/, use: ['style-loader', 'css-loader'], }, ], }, resolve: { alias: { // Essential for Vue 3 to resolve the correct Vue instance 'vue': path.resolve(__dirname, 'node_modules/vue'), }, extensions: ['.vue', '.js', '.ts', '.json'], }, }, styleguideDir: 'dist-styleguide', }; # Create src/components/MyButton.vue // src/components/MyButton.vue <template> <button :style="{ backgroundColor: color }" @click="onClick"> {{ label }} </button> </template> <script lang="ts"> import { defineComponent } from 'vue'; export default defineComponent({ name: 'MyButton', props: { label: { type: String, required: true, }, color: { type: String, default: 'blue', }, }, emits: ['click'], setup(props, { emit }) { const onClick = () => { console.log(`Button '${props.label}' clicked!`); emit('click'); }; return { onClick, }; }, }); </script> <style scoped> button { padding: 10px 20px; border: none; border-radius: 4px; color: white; cursor: pointer; } </style> <docs> This is a simple button component with customizable label and color. ```vue <MyButton label="Click Me!" /> <MyButton label="Submit" color="#4CAF50" /> <MyButton label="Danger" color="#f44336" @click="alert('Danger button clicked!')" /> ``` </docs> # Run Styleguidist npx styleguidist server # or to build a static style guide npx styleguidist build

vue-styleguidist --version

Debug

Known issues

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

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

affects: >=4.0.0

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

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.

affects: >=4.0.0

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

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.

affects: >=4.0.0

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

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.

affects: >=4.0.0

Errors

Common errors & fixes

[Vue Styleguidist] Error: Cannot find module 'vue-template-compiler' or '@vue/compiler-sfc'

Missing the appropriate Vue compiler package for your Vue version.

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.

Webpack config: 'vue-loader' is not found (or similar 'Module not found' for vue-loader)

The `vue-loader` package is not installed or the webpack rule for `.vue` files is incorrect or missing.

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

Module not found: Error: Can't resolve 'vue' in '...'

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.

fix

Add a `resolve.alias` entry in your `styleguide.config.js` `webpackConfig`: `alias: { 'vue': path.resolve(__dirname, 'node_modules/vue') }`.

[Vue Styleguidist] Error: No components found. Make sure you have specified the components option correctly.

The `components` glob pattern in `styleguide.config.js` does not match any existing `.vue` files in your project.

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.

Upgrade

Version history

4.72.4latest on npm

Audit

Dependencies

@vue/compiler-sfcrequiredRequired for Vue 3 component compilation and parsing.

pugoptionalNeeded if you use Pug (Jade) templates within your Vue components.

vuerequiredThe core Vue.js library for component rendering and reactivity.

vue-loaderrequiredWebpack loader for Vue Single File Components (.vue files). Essential for compilation.

vue-template-compileroptionalRequired for Vue 2 component compilation and parsing. Not needed for Vue 3.

webpackrequiredThe underlying module bundler used by Styleguidist to process components.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vue-styleguidist/vue-styleguidist ↗

packagehttps://www.npmjs.com/package/vue-styleguidist ↗

homepagehttps://vue-styleguidist.github.io ↗