sc5-styleguideとgulp-webserverを一緒に使う

14888 ワード
sc5-styleguide スタイルガイド gulp gulp テキストリンク

開発用WEBサーバー（gulp-webserver）とスタイルガイドのサーバー（sc5-styleguide）を一緒に使った時に共通の静的コンテンツをみる方法を試行錯誤したので紹介します。

スタイルガイドジェネレータsc5-styleguideについては、いくつか記事がすでに書かれているので、環境構築については本稿では割愛します。
次を参考にしました。

開発用WEBサーバーgulp-webserverも言わずと知れたgulp用のプラグインなので割愛します。

経緯

sc5-styleguideはKSSのコメント記法を受け継いだNode.js実装のスタイルガイドジェネレータです。
例えば、scssに次のような設定コメントを書いておけば

button.scss
// Button
// 
// ボタン
// 
// Markup:
// <div class="button">
//   <a href="#">Button</a>
// </div>
//
// Styleguide 1.0.0

.button {
  width: 240px;
  margin-left: auto;
  margin-right: auto;
  & > a {
    display: block;
    text-align: center;
    padding: 12px;
    color: #333;
    border: 1px solid #ddd;
    &:hover {
      color: #fff;
      background: #000;
    }
  }
}

次のようなスタイルガイドが作成されます。

このようにコメントのMarkUpの下部にマークアップを記述すると、スタイルガイドにはスタイルがあった状態でレンダレングされます。
さらに、下部にはレンダリングされていない状態のマークアップがあるので、理想的な使い方としては、このボタンを作りたいところにコピペすればよいことになります。

さて、このときjpgやpngなどのイメージファイルを呼び出したい場合、どうすればよいか困ったのがきっかけです。
例えば、先ほどのボタンを例に挙げるとアイコン画像を文字の前に置く場合です。

button.scss(コメント抜粋)
// Button
// 
// ボタン
// 
// Markup:
// <div class="button">
//   <img src="/images/icon.png">
//   <a href="#">Button</a>
// </div>
//
// Styleguide 1.0.0

上記のようにMarkupを記載したとき、スタイルガイドでもちゃんと画像が表示され、かつ、開発中のコンテンツでも同じパスで画像を表示するようにするにはどうすればよいのでしょうか。

実はsc5-styleguideのREADMEにはその場合のことが書かれていました。
https://github.com/SC5/sc5-styleguide#images-fonts-and-other-static-assets

ここに書かれている対処方法はそれぞれのサーバーにコピーして置けというものです。もし資材に変更があればoutput先を両方にしとけばよいと書かれています。

しかし、私のプロジェクトでは画像ファイルが大量にあるので、この方法には賛同できませんでした。
そのため、コンテキストルートを一緒にする方法を考えました。

方法

結論から言うと、スタイルガイドの設定だけでは無理だったので、gulp-webserverのリバースプロキシを使って実現します。

開発用WEBサーバーのポートを3000、
スタイルガイドのサーバーのポートを4000としたとき、
スタイルガイドのページへは次のURLでアクセスするようになります。
http://localhost:3000/styleguide/

ディレクトリ構成

単純に次のようになります。

ディレクトリ構成
├── dist <- 開発中のソースをビルドしたものの出力先
│   ├── img
│   ├── css
│   ├── ...
│   └── styleguide <- スタイルガイドのコンテンツ
│       ├── index.html <- スタイルガイドのTOPページ
│       ├── assets <- 自動で生成されるガイドで使う画像とか
│       ├── css <- 自動で生成されるガイドのスタイルを整えるcss群
│       ├── js <- 自動で生成されるガイドで使うjs群
│       └── ...

gulpfile.js

試行錯誤の結果、次のようになりした。

  • gulp-webserverで
    http://localhost:3000/styleguide/
    にアクセスされたら次にアクセスするようにする。
    http://localhost:4000/
  • スタイルガイドのTOPページへは次でアクセスできるようにする。
    http://localhost:4000/
  • スタイルガイドのTOPページで定義している静的コンテンツのパスは次となるようにする。
    例えばこんな感じ
    <link rel="icon" href="/styleguide/assets/img/favicon.ico">
gulpfile.js
const gulp = require('gulp')
const webserver = require('gulp-webserver')
const styleguide = require('sc5-styleguide')

gulp.task('webserver', () => {
  gulp.src('./dist')
    .pipe(webserver({
      livereload: true,
      host: '0.0.0.0',
      port: 3000,
      proxies: [{
        source: '/styleguide',            //<-(1)
        target: 'http://localhost:4000/'
      }, {
        source: '/socket.io',             //<-(２)
        target: 'http://localhost:4000/socket.io/'
      }]
    }))
})

gulp.task('styleguide:generate', () => {
  return gulp.src('./src/**/*.scss')
    .pipe(styleguide.generate({
        port: 4000,
        title: 'Style Guide',
        server: true,
        rootPath: './dist/styleguide',  //<-(3)
        appRoot: '/styleguide',         //<-(4)
        overviewPath: 'README.md'
      }))
    .pipe(gulp.dest('./dist/styleguide'))
})

gulp.task('styleguide:applystyles', () => {
  return gulp.src('./src/**/*.scss')
    .pipe(styleguide.applyStyles())
    .pipe(gulp.dest('./dist/styleguide'))
})

gulp.task('styleguide', ['styleguide:generate', 'styleguide:applystyles'])
  1. proxies
    gulp-webserverのプロキシの設定です。 http://localhost:3000/styleguide/にアクセスされたら
    http://localhost:4000/にアクセスする
    を実現しています。
  2. トライアンドエラーで必要だとわかったので設定しました。
  3. rootPath
    スタイルガイドのルートパスです。
    http://localhost:4000/でスタイルガイドのTOPページが表示できるようにするため./dist/styleguideにします。
  4. appRoot
    これはルートディレクトリ以外のディレクトリからスタイルガイドをホスティングする場合に定義します。
    つまり、先ほどのスタイルガイド用静的コンテツのパスが、設定しなければ
    <link rel="icon" href="/assets/img/favicon.ico">
    となるのところを/styleguideと設定することで
    <link rel="icon" href="/styleguide/assets/img/favicon.ico">
    となります。

あとはgulp-webserverとsc5-styleguideのREADME通りです。

これで、共通の静的コンテンツを参照するようになりました。

参考

http://qiita.com/shwld/items/188fd8495ada8e6d3125
http://qiita.com/sygw/items/55e6a3916312c502bc4f
http://labs.septeni.co.jp/entry/2015/10/26/233737
http://sanooo.jp/gulp/sc5-styleguide-settings/