vue-styleguidist / vue-styleguidist

Created from react styleguidist for Vue Components with a living style guide

Isolated Vue component development environment with a living style guide

Start documenting now on codesandbox.io

Sponsors

A big thank you to our sponsors.

Marcello Bachechi, Walter Tommasi, Luca Ban and Ben Hong

Packages

vue-styleguidist takes the results of vue-docgen-api and creates a website to showcase and develop components.

---

vue-docgen-api parses vue components and load their documentation in a JavaScript object.

---

vue-inbrowser-compiler takes vue components code written in es6 and uses buble to make it compatible with all browser.

---

vue-cli-plugin-styleguidist configures vue-styleguidist to work with vue-cli 3.

---

vue-docgen-cli is a command line interface generating documentation files automatically from vue-docgen-api. Generate markdown by default but can be configured to generate whatever text format you desire.

Documentation

Docs are available at https://vue-styleguidist.github.io/ - we are still working on refining it and contributions are welcome!

Contributing

Please see contributing guide.

Note that the current monorepo relies on yarn workspaces. Don't forget to install yarn, npm i --global yarn, before cloning.

Authors and license

Artem Sapegin, Rafael Escala, Bart Ledoux, react-styleguidist contributors and vue-styleguidist contributors. Thanks to the team of react-styleguidist for the amazing tool.

We work on this project because we love the open-source community and learn new things.

Logo by Benjamin Cognard.

License

MIT License

vue-styleguidist's Issues

Error when trying to run styleguide server

Error when parsing src/global-components/icon/index.vue: Error: The component has no name, add 'el' property on the Vue component.

I have default vue app from vue-cli.
My config:

module.exports = {
  components: 'src/global-components/**/*.vue',
  webpackConfig: require('./build/webpack.dev.conf.js')
}

External mixins must have hot reloading

For now, you have to restart the server to view the last changes of the external mixins in the documentation.

@event tag just support one param

Now, the @event tag just support @type tag, and I just set one param.

/**
 * @event click
 * @type {Object}
 */

But, if I want to export two or more params, the vue-styleguidist can't support it.

I suggest to update the @event tag, like:

/**
 * @event click
 * @property {Event} event - DOM Event
 * @property {String} name - some name
 * @property {String} value - some value
 */
this.emit('click', event, 'name', 'value')

Vue.use is undefined

I need to run install() from a plugin in order to generate documentation examples but available vue class into .md files doesn't have .use() function. How can I achieve this?

Doc generation of mixin props

I have a mixin that adds props to the component. Is it possible for those props to also be documented with the component they are added to?

Markdown require() not importing

Hi!

I've got an issue with a more complex markdown example, where the required data is either not imported or just not seen by Vue (backticks "escaped" just for the example):

### Bullet type radio inputs
\```js
const mockedOptions = require('./mocks.js').options;

new Vue({
  template: `
      <bb-radio radioType="bullet"
        :options="opts" 
        name="bullet"></bb-radio>`,
  data() {
    return { opts: mockedOptions }
  },
});
\```

And it works fine when I inline the options:

### Bullet type radio inputs
\```js
new Vue({
  template: `
    <div>
      <bb-radio radioType="bullet"
        :options="opts"
        name="bullet"></bb-radio>
    </div>`,
  data() {
    return { opts: [
      {
        value: 1,
        text: 'Foo',
      },
      {
        value: 2,
        text: 'Bar',
      },
      {
        value: 30,
        text: 'Foobar',
      },
      {
        value: 45,
        text: 'Foobaz',
      },
    ]}
  },
});
\```

Windows line ending in styleguidist.js causing build error in version 1.3.2

This error seems to have crept back in.

$ npm run styleguide

> @ styleguide 
> vue-styleguidist server

env: node\r: No such file or directory

It might be worth configuring git to automatically fix this for you so that it doesn't happen again. https://help.github.com/articles/dealing-with-line-endings/

Thank you.

Component example is not working if vuex property in config is undefined

Hi!
Thanks for the great tool.
In config documentation I found that vuex property is optional. I don`t use vuex and in my styleguide.config.js vuex property is not set, so all my examples from markdown files is not working.
But if I set it as path pointing to module that exports empty object, everything is working, like this:

module.exports = {
  vuex: 'empty.js'
};

and in empty.js:

export default {};

Can you fix this issue?

Missing module: `pretty-format`

I just tried to run vue-styleguidist build and got the following error:

module.js:529
    throw err;
    ^

Error: Cannot find module 'pretty-format'
    at Function.Module._resolveFilename (module.js:527:15)
    at Function.Module._load (module.js:476:23)
    at Module.require (module.js:568:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (/Users/dan.rumney/IdeaProjects/diagnostics-portal/client/node_modules/vue-styleguidist/bin/styleguidist.js:9:22)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)
    at Module.load (module.js:545:32)
    at tryModuleLoad (module.js:508:12)
    at Function.Module._load (module.js:500:3)
error Command failed with exit code 1.

I'm on Mac OSX, running node v8.6.0 and vue-styleguidist v1.2.8

The offending line appears to be

const prettyFormat = require('pretty-format');

Change how are props render in methods using custom *Renderer component

Hello guys,
I'm struggling with custom React *Renderer overwriting default components. I want render each argument prop from method on separate line and description in description column.

I was trying to start from this hint in cookbook section that define different layout How to change the layout of a style guide? but stuck on the compiler error. This error seems like there is no support of jsx compilation of React component, I try copy all dependencies from React-styleguidist but with no luck, always get this same error

Failed to compile.
./styleguide/StyleGuideRenderer.js
Syntax error: Unexpected token (9:2)

   7 |   hasSidebar,
   8 | }) => (
>  9 |   <div className="root">
     |   ^
  10 |     <h1>{title}</h1>
  11 |     <main className="wrapper">
  12 |       <div className="content">

What I am doing wrong?

Error while npm run build

I get this error while trying to build vue-styleguidist itself, while trying to contribute to it. Both on yarn and npm v5. As this issue is not client/consumer side, it's not that high priority. If everything works for you, feel free to close the issue 😃

Error in build/bundle.29e4e95d.js from UglifyJs
Unexpected token: operator (>) [build/bundle.29e4e95d.js:30719,19]

Cannot document separate .js files

I am using Vue mixins, plugins etc. which are .js files. I need to document them as well, but it does not work. Trying to add section Mixins to styleguide.config.js
sections: [ { name: "Introduction", content: "README.md", }, { name: "UI Components", components: "src/components/**/[A-Z]*.vue", }, { name: "Mixins", components: "src/mixins/*.js", },

This ends up with an error:
Failed to compile.
./node_modules/vue-styleguidist/lib/index.js
Module build failed: ReferenceError: message is not defined
at Array.map ()
at Array.map ()

Works fine if it is "src/mixins/*.vue". Any suggestions?

Path to component instead of name

Both the left sidebar and the header that should show the component name display the absolute path to the component.

I've tried changing the webpack config and even used the 'vue-webpack-loader' as in the example and still can't get it to display properly.

I also noticed the default glob pattern of src/components/**/*.vue doesn't work (even though that's where my components are). If I define it as an option in the config with that same string it does work.

Props, JSDoc comments, and Readme (with the exception of #3) all seem to be working otherwise.

Breaks backstopjs/casper

Just updated to 1.2 and with the inclusion of webpage in the dependencies, backstopjs/casper fails to run for visual regression tests. Backstop runs phantom (for now) and I think it requires a different version of it or something so this addition in my node_modules breaks it.

Was webpage meant to be added to devDependencies since it looks like it's only used for testing with phantom and not actually a dependency?

If not, I just want to at least make it known that if you use backstopjs for testing, updating to v1.2 will break it.

How do I document events?

According the docs http://usejsdoc.org/tags-event.html we can use @fires and @event tags to refer to event documents, but It seems that the compiler ignores these entries.

typescript support?

Cannot parse src/view/2d/KonvaExp2.vue: Error: SyntaxError: unknown: Unexpected token (29:0)

where KonvaExp2.vue

29:  @Component
30:  export default class KonvaExp2 extends Vue{

Windows line ending in styleguidist.js causing build error in version 1.2.10

In vue-styleguidist/bin/styleguidist.js, the first line has a Windows line ending. Need to change format of file to have Unix line endings. (error found in MacOS Sierra)

Bootstrap-vue issue

Hello there,

First of all, really great work there on vue-styleguidist, it is awesome and simplifies the teamwork.

I was trying to implement bootstrap-vue with our custom styles to replicate the bootstrap-vue doc our way.

Here's my component :

<template>
  <b-alert show variant="primary">Primary Alert</b-alert>
</template>
<script>
  import Vue from 'vue';
  import bAlert from 'bootstrap-vue/es/components/alert/alert';

  export default {
    name: 'Alert',
    components: {
       'b-alert': bAlert
    }
  }
</script>

<docs>
  ```js
    <b-alert show variant="primary">Primary Alert</b-alert>
  ```
</docs>

I'm not sure if it's intended or not, but I'm getting an error with this :

main.bundle.js:31795 [Vue warn]: Unknown custom element: - did you register the component correctly? For recursive components, make sure to provide the "name" option.

(found in )

In my styleguide.config.js, i'm requiring :
require: [
'./node_modules/bootstrap/dist/css/bootstrap.css',
'./node_modules/bootstrap-vue/dist/bootstrap-vue.css',
'./styleguide/styles.css'
]

Could you please explain what is the proper way to achieve this kind of documentation ?

Support render function

Hi,
I personally use render functions with JSX to develop my Vue components.
Is there a plan to support these types of components?

Making each component an individual page

Just a suggestion :-)

Having many and rather larger components grouped together in a single project/repo, the one-page documentation can get rather long and confusing.

It would help a lot to be able to split up each component into individual pages, or add some sort of split line after each component, in the default theme/styling.

Also adding a setting for a different font-family for the headers, might make the sections separate a bit better.

spread operator is causing parsing to skip documentation for block/section

Using the example below and knowing that this is part of a larger vue.js file... when trying to document the private methods, we find that if any of the methods begin with the spread operator (...), the whole entire block is ignored. Placement does not matter as the method could be in the beginning, the middle or the end.

Example:

    // == Methods
    methods: {
      /**
       * Description of method below
       *
       * @public 
       */
      ...mapActions('app', {
        doSomething: true
      }),

      /**
       * Description of method below
       *
       * @public 
       */
      onInputHandle () {
        // this is a method and has code in it
      },
   }

Adding example code gives error in console

When I try to add a component example, these errors appear in the console:

I've tried naming the file the same as the component.vue and as Readme.md. The 'show code' shows the code snippet correctly, but the component is not rendered. (possibly related to #2)

How to mock vuex getters/setters in styleguidist? label:"help wanted"

I wrote a component (vue+vuex) in which I need to mock Vuex methods. The forms are added dynamically and inside styleguidist the getters tries to read from object that doesn't exists yet (undefined). Is there any way to mock/stub Vuex store?

e.g.
`
computed: {

...mapGetters( 'BaseModule', [
  'getCurrentFieldValue'
]),

textFieldValue: {

  get () {
    return this.getCurrentFieldValue( this.fieldName )
  },
  set ( value ) {
    this.setCurrentFieldValue({
      name : this.fieldName,
      value: value,
    })
  }
}

},
`

No such file or directory

I keep on running into this error:

> vue-styleguidist server

env: node\r: No such file or directory

Whenever I run that command.

I'm running node -v v6.10.0
and npm -v 4.1.2

The path it hits is /examples/basic/node_modules/.bin/vue-styleguidist/

Allow config option for auto open props and methods

Currently you can auto open the code examples but not the props and methods.

Could we have this as a config option to have everything auto expanded.

In certain cases, ignoring props doesn't work

Following the docs.

I tried listing ignored props first, as seen in the example, and at the end of the props object but they are not ignored in the docs either way.

v1.2.9 not working due to 'UglifyJs Plugin Invalid Options'

After switching to v1.2.9 the build breaks with the following error:

{ [Error: Validation Error

UglifyJs Plugin Invalid Options

options.parallel should be boolean
options.parallel should be integer
options.parallel should match exactly one schema in oneOf
]
err:
[ { keyword: 'type',
dataPath: '.parallel',
schemaPath: '#/properties/parallel/oneOf/0/type',
params: [Object],
message: 'should be boolean' },
{ keyword: 'type',
dataPath: '.parallel',
schemaPath: '#/properties/parallel/oneOf/1/type',
params: [Object],
message: 'should be integer' },
{ keyword: 'oneOf',
dataPath: '.parallel',
schemaPath: '#/properties/parallel/oneOf',
params: {},
message: 'should match exactly one schema in oneOf' } ] }
/path/node_modules/vue-styleguidist/bin/styleguidist.js:33
throw err;
^

It seems that the reason for this is a newer version of "uglifyjs-webpack-plugin".
There is a new build out since a few hours: "1.0.0-beta.3" and your package load this as a dependency due to the semver '^1.0.0-beta.2'

migrate to react-codemirror2

react-codemirror has major outstanding issues and many users including myself suspect this package has been abandoned. I authored react-codemirror2 and plan to actively maintain this as a successor moving forward. I encourage you try the new package in your project. Likewise, feel free to open up any issue should you encounter trouble and I'll be on it. Same with general suggestions/improvements - I'm aiming to build it up collaboratively so if you had any shortcomings with the original package please let me know.

Slots are not documented unless component has doc-comments in script part

If a component does not have any props or public methods/events, the slots are not being evaluated.

<template>
  <div>
    <!-- This slot will not be documented -->
    <slot></slot>
  </div>
</template>

<script>
  export default {
    name: 'i-only-have-a-template'
  }
</script>

A workaround is to add empty props, but then an empty table is rendered with just the head

<template>
  <div>
    <!-- This slot WILL be documented -->
    <slot name="foo"></slot>
  </div>
</template>

<script>
  export default {
    name: 'i-only-have-a-template',
    props: {}
  }
</script>

Results in something like this:

Prop name	Type	Default	Description

Slot	Description
foo	This slot WILL be documented

Extends support

It would be great to have documentation for props and methods of extended component.

Two problems about slot comment on docs

1. If a component don't have props, the slot comment will be ignore.
2. If template lang is pug, the slot comment won't show on style guide, both //- and //.

Normal

Without props

With `lang="pug"`

Example in master doesn't work

Hi,

from a fresh cloned repository, I try to run the basic example but I get some errors:

$ npm run styleguide

> [email protected] styleguide /home/projects/perso/vue-styleguidist/examples/basic
> vue-styleguidist server

You can now view style guide in the browser.

Local:            http://localhost:6062/

On your network:  http://172.18.0.1:6062/

Warning: Accessing PropTypes via the main React package is deprecated, and will be removed in  React v16.0. Use the latest available v15.* prop-types package from npm instead. For info on usage, compatibility, migration and more, see https://fb.me/prop-types-docs
Warning: Accessing createClass via the main React package is deprecated, and will be removed in React v16.0. Use a plain JavaScript class instead. If you're not yet ready to migrate, create-react-class v15.* is available on npm as a temporary, drop-in replacement. For more info see 
https://fb.me/react-create-class
Failed to compile.
./src/components/Input/Input.vue
(Emitted value instead of an instance of Error) 
  Error compiling template:
  
  <div>
        <input :value="value" @input="updateValue($event.target.value)" @change="emitChange" v-model="val" ref="input">
        <button @click="fireEvent()">Fire example event!</button>
  </div>
  
  - :value="value" conflicts with v-model on the same element because the latter already expands to a value binding internally
./src/components/Button/Button.vue
Module build failed: ReferenceError: [BABEL] /home/projects/perso/vue-styleguidist/examples/basic/src/components/Button/Button.vue: Unknown option: /home/projects/perso/vue-styleguidist/examples/basic/node_modules/react/react.js.Children. Check out http://babeljs.io/d$
cs/usage/options/ for more information about options.

A common cause of this error is the presence of a configuration options object without the corresponding preset name. Example:

Invalid:
  `{ presets: [{option: value}] }`
Valid:
  `{ presets: [['presetName', {option: value}]] }`

For more detailed information on preset configuration, please see http://babeljs.io/docs/plugins/#pluginpresets-options. (While processing preset: "/home/projects/perso/vue-styleguidist/examples/basic/node_modules/react/react.js")
    at Array.map (<anonymous>)

...

Document slots

It's possible to add slots to props, methods & events table?

Example in .vue file

As I see main advantage of additional .md file is the possibility to show an example. In .vue component above "export default" we can use JSDoc syntax with some markdown. So we can describe anything inside .vue file except example(I try it). I think the possibility to write an example in .vue file will be cool.

Array/Object props type shown is 'func'

Hi, i found some problem.
please see my example code

1. Array type, default return is function

props: {
...
  /**
    * images
    */
   images: {
      type: Array,
      default: function () {
        return [
          {
            url: 'https://instagram.com',
            image: 'https://placehold.it/300x300',
            text: '텍스트'
          }
        ]
      }
    }
...
}

This code is shown usage

Prop name	Type	Default	Description
images	func	Function	images

2. Array type, default value is array

   images: {
      type: Array,
      default: [
        {
          url: 'https://instagram.com',
          image: 'https://placehold.it/300x300',
          text: '텍스트'
        }
      ]
    },

This code is shown usage

Prop name	Type	Default	Description
images	array	[{"url":"https://instagram.com","image":"https://placehold.it/300x300","text":"텍스트"}]	images

but if i wrote (2) code, has error

[Vue warn]: Invalid default value for prop "images": Props with type Object/Array must use a factory function to return the default value.

as you known that Props type is Object/Array default value necessary factory function

please check issue
thanks.

svg loader

I use a vue-svg-loader to connect icon, but it is intercepted by the built-in file-loader and at the output of the base64

{
        test: /\.icon\.svg$/,
        loader: 'vue-svg-loader'
}

Can you make working example of using vuex state variable in component in examples/basic ?

Hello,
I fork this repo and run it in dev mode, because I want to get working example of how to use vuex state variables used in vue components in styleguide, but the example of vuex store that is in the repo is never used in any component.
So I try to add it to one component (here you can find the fork https://github.com/struers-mfr/vue-styleguidist) and I struggle with it, the value that is shown in vuex bindings in vue inspector is "(error during evaluation)" and in console i get the message "Uncaught TypeError: Cannot read property 'getters' of undefined"
Can you point what is wrong in my attempt, or can you add working example of usage in vue-styleguidist examples?

Component documentation example not working on Function

Using [email protected] and [email protected]

I copied your example for the component documentation (https://github.com/vue-styleguidist/vue-styleguidist/blob/master/docs/Documenting.md). But the converter seems to break, when it comes up to the default for the function prop (onClick). It looks like unquote(string) is expecting a string but gets a Function.

function unquote(string) {
  return string.replace(/^['"]|['"]$/g, ''); // => Cannot read property 'replace' of undefined
}

Failed to mount component with vue-loader 13.0.0

vue-loader 13.0.0

Examples no longer load with the new vue-loader update. Get this error in console:

[Vue warn]: Failed to mount component: template or render function not defined.

found in

---> <CdrButton>
       <Root>

Unable to document slots

Using [email protected] and [email protected] (webpack)

I'm unable to document the slots. As described in documentation I added the following line to my component, but the slots are not documented in the styleguide:

<template>
  <div class="foo">
    <!-- Use this slot footer -->
    <slot name="footer"></slot>
  </div>
</template>

Props, methods and events are working though

I keep getting: Cannot read property '1' of null

Hi,

After installing and configuring package.json, I get this error:

Cannot read property '1' of null

npm ERR! Linux 4.4.0-93-generic
npm ERR! argv "/usr/bin/nodejs" "/usr/bin/npm" "run" "styleguide"
npm ERR! node v8.4.0
npm ERR! npm v3.10.10
npm ERR! code ELIFECYCLE
npm ERR! [email protected] styleguide: vue-styleguidist server
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] styleguide script 'vue-styleguidist server'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the saftims-ui package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! vue-styleguidist server
npm ERR! You can get information on how to open an issue for this project with:
npm ERR! npm bugs saftims-ui
npm ERR! Or if that isn't available, you can get their info via:
npm ERR! npm owner ls saftims-ui
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR! /home/timtech4u/flexiProjectz/saftims-ui/npm-debug.log

Also, my *.vue files are in varieties of folders. Thanks

Update docs for styles/themes

The configuration docs mention styles and theme as options to customize the styleguide.

The cookbook link is a 404 -- are there docs for how to customize those located somewhere else? I can see a little bit of it in the buefy example, but would love to know what other options are available.

Add support for Yup

Yup offers schema validation for Vue components.
Would be great to have it integrated with vue-styleguidist as maybe an extension?

I would be glad to submit a PR adding support for this, but need to check how to make this optional

Example vue-styleguidist with Nuxt

TypeError: require.context is not a function

Got the error TypeError: require.context is not a function when attempt to parse component containing webpack's require.context

<template>
  <p>Some component</p>
</template>

<script>
  const ctx = require.context('some/path', true, /.jpg$/);

  export default {
    name: 'example',
  };
</script>

Console output:

Error when parsing someComponent.vue: TypeError: require.context is not a function

webpack configs are taken from official vui-cli/webpack template (https://git.io/v7UkZ)

// styleguide.config.js

const webpack = require('./build/webpack.base.conf');

module.exports = {
  webpackConfig: webpack,
};

vue-styleguidist v1.2.0
webpack 2.6.1

Examples are not working

The /examples folder in this repository is not working out of the box.

I've run the instructions detailed in the Readme.md and there were errors in all components when serving vue-styleguidist:

JSDOC_ERROR: There are no input files to process.


Cannot parse src/components/RandomButton/RandomButton.vue: Error: JSDOC_ERROR: There are no input files to process.

Vue example gives a syntax error

The following example from the documentation

const names = require('dog-names').all;

new Vue({
  data(){
    return {
      list: names
    }
  },
  template: `
    <div>
      <RandomButton :variants="list" />
    </div>
  `
})

is giving a syntaxt error in chrome

Custom style: scss

Hi !
I'm discovering the Styleguidist, but I don't know how to load a scss file for the components style, as mine are not in the component files...

The sass loader is configured in the webpack config, but i don't know how I can load the scss file itself. I tried

const path = require('path');
module.exports = {
  require: [
    'babel-polyfill',
    path.join(__dirname, 'path/to/styles.scss'),
  ]
};

with no success

Webpack 3 support

Just tried to setup the styleguide with webpack 3. Got the following message:

Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema.

Is this a issue because Webpack 3 is not supported?
All works fine with Webpack 2

Build task doesn´t exit

When I build my static assets the build task vue-styleguidist build doesn´t exit after the assets are built.