【vue】Vue Styleguidistの使い方を説明① 〜Laravel + vue環境でVue Styleguidistを動かす〜

※元々ブログに書いていたのですが、qiitaに転載しました
https://www.moyashidaisuke.com/entry/vue-styleguidist-install

概要

vueのstyleguild「Vue Styleguidist」をLaravel + vue環境で使い始めてみました。
思ったより手間取ってしまったので、設定ファイルや、私の環境で発生したエラーの対応等を残しておきます。

↑のカメレオンはVue Styleguidistのロゴ。きもかわいい。

※Laravel環境じゃなくても多分参考になると思います。

Vue Styleguidistとは

とりあえず動作サンプル見た方がわかりやすいのでいきなりですがリンクを。

こういうコンポーネントの仕様と、サンプルのドキュメントを生成してくれるツールです。 こういうの。

GitHubのStar数はこの記事を書いてる時点で1419なので、デファクトになってる感はまだ無いですが、競合のvueseよりはstar数多いのでこちらを採用しました。
https://github.com/vue-contrib/vuese

導入手順（理想形

特にはまらないですんなりいくパターン。

前提

• Laravel + vue環境導入済み
• npmじゃなくてyarn
• Vue CLIは使ってない

公式手順だとnpmですが、私の環境ではyarnを使っているのでyarnの手順を紹介します。

インストール

$ yarn add -D vue-styleguidist

〜色々インストールされる。省略〜

Done in 296.61s.

style guildの設定

公式手順だとリンクが2つ貼ってあります。

https://vue-styleguidist.github.io/docs/Components.html#finding-components
https://vue-styleguidist.github.io/docs/Webpack.html

いきなりぶん投げられてわかんないですが、プロジェクトルートに

styleguide.config.jsというファイルを作成してください。

中身は

const VueLoaderPlugin = require('vue-loader/lib/plugin')
module.exports = {
  webpackConfig: {
    module: {
      rules: [
        // Vue loader
        {
          test: /\.vue$/,
          exclude: /node_modules/,
          loader: 'vue-loader'
        },
      ]
    },
    plugins: [
      new VueLoaderPlugin()
    ]
  },
  // vueファイルへのpathを指定
  components: 'resources/js/components/**/[A-Z]*.vue',

}

で私の環境だといけました。

ポイントとしては、webpackConfigはlaravel mixの設定を流用しても全く動かないです。（あれはmixで動的にconfigを生成したりしてるので）

また、vue-loaderの設定もちゃんと書いてあげないと動かないです。デフォルトで呼んでくれたりはしないようです。

あと、vueのファイルはLaravelだと普通resources/js以下で作成してる事が多いと思いますが、適時調整してください。

package.jsonにコマンド追加

これは公式そのままで大丈夫です。

{
  "scripts": {
+    "styleguide": "vue-styleguidist server",
+    "styleguide:build": "vue-styleguidist build"
  }
}

実行

hot reload版

yarn run styleguide

サーバが立ち上がってlocalhost:6060でつなげるようになります。vagrantやDocker等の仮想環境を使っている方はポートの設定をしてください。

私はdocker-composeを使っていたので

      ports:
        - 6060:6060 # styleguide

を追加しました。

htmlとjs吐き出す版

yarn run styleguide:build

styleguideというディレクトリにhtmlとjsが吐き出されますので、htmlを開けばOKです。

エラー色々

styleguide.config.jsの設定系

componentsへのpathがおかしい

画面を開くとこれが表示されるパターン。

Welcome to Vue Styleguidist!
We couldn’t find any components using these patterns:

src/{components,Components}/**/*.vue
Create styleguide.config.js file in your project root directory like this:

module.exports = {
  components: 'src/components/**/*.vue'
};
Read more in the locating components guide.

componentsの設定を自分の環境に合わせればOK。

Failed to compile

Failed to compile
./resources/js/components/XXXXX.vue 1:0
Module parse failed: Unexpected token (1:0)
You may need an appropriate loader to handle this file type.

vue-loaderの設定をいれてあげればOK。

vueとvue-template-compilerのバージョン違い

Failed to compile
./resources/js/components/XXXXXX.vue (./node_modules/vue-styleguidist/loaders/vuedoc-loader.js!./resources/js/components/XXXXXX.vue)
Error: 

Vue packages version mismatch:

- vue@2.6.8 (/var/www/node_modules/vue/dist/vue.runtime.common.js)
- vue-template-compiler@2.6.10 (/var/www/node_modules/vue-docgen-api/node_modules/vue-template-compiler/package.json)

This may cause things to work incorrectly. Make sure to use the same version for both.
If you are using vue-loader@>=10.0, simply update vue-template-compiler.
If you are using vue-loader@<10.0 or vueify, re-installing vue-loader/vueify should bump vue-template-compiler to the latest.

バージョン合わせないとダメらしい。
yarn.lockを確認すると

vue-template-compiler@^2.0.0:
  version "2.6.10"
  resolved "https://registry.yarnpkg.com/vue-template-compiler/-/vue-template-compiler-2.6.10.tgz#323b4f3495f04faa3503337a82f5d6507799c9cc"
  integrity sha512-jVZkw4/I/HT5ZMvRnhv78okGusqe0+qH2A0Em0Cp8aq78+NK9TII263CDVz2QXZsIT+yyV/gZc/j/vlwa+Epyg==
  dependencies:
    de-indent "^1.0.2"
    he "^1.1.0"

となっており、^2.0.0 2以上を使ってね、の指定で2.6.10をinstallしちゃってる。

というわけで、無理やり2.6.8を入れてみる。

$ yarn add vue-template-compiler@2.6.8
yarn add v1.13.0

info Direct dependencies
└─ vue-template-compiler@2.6.8
info All dependencies
└─ vue-template-compiler@2.6.8
Done in 223.61s.

これで2.6.8入ったと思いきや、2.6.10も入ったままなのでダメ。

yarn.lockはこんな状態

vue-template-compiler@2.6.8:
  version "2.6.8"
  resolved "https://registry.yarnpkg.com/vue-template-compiler/-/vue-template-compiler-2.6.8.tgz#750802604595134775b9c53141b9850b35255e1c"
  integrity sha512-SwWKANE5ee+oJg+dEJmsdxsxWYICPsNwk68+1AFjOS8l0O/Yz2845afuJtFqf3UjS/vXG7ECsPeHHEAD65Cjng==
  dependencies:
    de-indent "^1.0.2"
    he "^1.1.0"

vue-template-compiler@^2.0.0:
  version "2.6.10"
  resolved "https://registry.yarnpkg.com/vue-template-compiler/-/vue-template-compiler-2.6.10.tgz#323b4f3495f04faa3503337a82f5d6507799c9cc"
  integrity sha512-jVZkw4/I/HT5ZMvRnhv78okGusqe0+qH2A0Em0Cp8aq78+NK9TII263CDVz2QXZsIT+yyV/gZc/j/vlwa+Epyg==
  dependencies:
    de-indent "^1.0.2"
    he "^1.1.0"

installしたりremoveしてもダメだったので、最終手段でyarn.lockを直接書き換える。

vue-template-compiler@2.6.8:
  version "2.6.8"
  resolved "https://registry.yarnpkg.com/vue-template-compiler/-/vue-template-compiler-2.6.8.tgz#750802604595134775b9c53141b9850b35255e1c"
  integrity sha512-SwWKANE5ee+oJg+dEJmsdxsxWYICPsNwk68+1AFjOS8l0O/Yz2845afuJtFqf3UjS/vXG7ECsPeHHEAD65Cjng==
  dependencies:
    de-indent "^1.0.2"
    he "^1.1.0"

vue-template-compiler@^2.0.0:
  version "2.6.8"
  resolved "https://registry.yarnpkg.com/vue-template-compiler/-/vue-template-compiler-2.6.8.tgz#750802604595134775b9c53141b9850b35255e1c"
  integrity sha512-SwWKANE5ee+oJg+dEJmsdxsxWYICPsNwk68+1AFjOS8l0O/Yz2845afuJtFqf3UjS/vXG7ECsPeHHEAD65Cjng==
  dependencies:
    de-indent "^1.0.2"
    he "^1.1.0"

$ yarn install

これで動きました。

issueはちょいちょい見かけるのだけど、ちゃんとした対応方法は不明。誰か知ってたら教えて下さい。

次

実際のドキュメントを生成したり、パラメータの解説したりの予定。

第2段