もやぶろ

moyashidaisukeのブログだからもやぶろ。フリーランスのエンジニアのダイスケです。プログラム関連とかギター関連とか旅行関連とか色々。

【JavaScript】JSDocでhot reloadを無理やり有効にするやり方

概要

JavaScriptのドキュメンテンションツールのJSDocですが、最近のツールのようhot reload(コードを書き換えるとブラウザ開きっぱなしでも自動で更新してくれるやつ。hot build?hot replacement?)がありません。

既存のツールを組み合わせて実現する手段を紹介します。

JSDoc?

jsdoc.app

JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor.

JavaScriptのためのAPIドキュメント生成ツールです。JavadocとかphpDocumentorみたいな。

こういうHTMLが生成されます。

f:id:moyashidaisuke:20191029221925p:plain

hot reloadのやり方

issueでひっそりと紹介されていました。

github.com

概要

nodemonを使った自動ビルドと、livereloadを使った自動更新の組み合わせで実現します。

chromeのextentionいれる(livereload)

chrome.google.com

こちらからいれてください。 SafriとFirefoxもあるようです。

livereload.com

npmでインストール

私の環境ではyarnを使っているのでyarnで。

$ yarn add -D  livereload nodemon




[4/4] Building fresh packages...
success Saved lockfile.
success Saved 34 new dependencies.
info Direct dependencies
├─ livereload@0.8.2
└─ nodemon@1.19.4
info All dependencies
├─ ansi-align@2.0.0
├─ boxen@1.3.0
├─ capture-stack-trace@1.0.1
├─ cli-boxes@1.0.0
├─ configstore@3.1.2
├─ create-error-class@3.0.2
├─ crypto-random-string@1.0.0
├─ duplexer3@0.1.4
├─ global-dirs@0.1.1
├─ got@6.7.1
├─ ignore-by-default@1.0.1
├─ is-installed-globally@0.1.0
├─ is-npm@1.0.0
├─ is-redirect@1.0.0
├─ is-retry-allowed@1.2.0
├─ latest-version@3.1.0
├─ livereload@0.8.2
├─ nodemon@1.19.4
├─ opts@1.2.6
├─ package-json@4.0.1
├─ prepend-http@1.0.4
├─ pstree.remy@1.1.7
├─ registry-auth-token@3.4.0
├─ registry-url@3.1.0
├─ semver-diff@2.1.0
├─ term-size@1.2.0
├─ timed-out@4.0.1
├─ touch@3.1.0
├─ undefsafe@2.0.2
├─ unique-string@1.0.0
├─ unzip-response@2.0.1
├─ update-notifier@2.5.0
├─ url-parse-lax@1.0.0
└─ widest-line@2.0.1

npmの人はこっち

$ npm i -D livereload nodemon

nodemonでファイル監視して自動ビルド

まず、jsdocのビルドを実行しているコマンドを確認しましょう。

私の場合は、

yarn run jsdoc -c jsdoc.config.js

です。

次に、対象となるJavaScriptのディレクトリを確認します。

私の場合は

resources です。

これを組み合わせて実行します。

$ yarn run nodemon  --exec 'yarn run jsdoc -c jsdoc.config.js' --watch resources

# 以下はログ
$ /var/www/node_modules/.bin/nodemon --exec 'yarn run jsdoc -c jsdoc.config.js' --watch resources
[nodemon] 1.19.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching dir(s): resources/**/*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `yarn run jsdoc -c jsdoc.config.js`
$ /var/www/node_modules/.bin/jsdoc -c jsdoc.config.js
[nodemon] clean exit - waiting for changes before restart

yarnを使っていない方は、yarn runnpxに差し替えてください。

これで、jsファイルを更新したら自動でJSDocのビルドが走るはずです。

対象の拡張子を追加する

デフォルトだと [nodemon] watching extensions: js,mjs,json となっている通り、3つの拡張子が対象になっています。mdファイル等を増やしたい場合は、 -e で指定できます。

こんな感じです。

yarn run nodemon  --exec 'yarn run jsdoc -c jsdoc.config.js' --watch resources -e js,md

ブラウザの自動更新を有効にする①

livereloadを使ってブラウザで開きっぱなしにしてても自動更新されるようにします。

まず、jsdocがファイル出力しているディレクトリを確認します。 私の場合は、

docs

です。

$ yarn run livereload docs

# 以下はログ
yarn run v1.13.0
$ /var/www/node_modules/.bin/livereload docs
Starting LiveReload v0.8.2 for /var/www/docs on port 35729.

npmな方はyarn runnpxに置き換えてください。

dockerを使っている場合

livereloadはデフォルトで35729というよくわからないポートを使うので、Dockerを使ってる場合はポートをあける必要があります。

私の場合は、こんな感じでdocker-compose.yamlに追加しました。

php-fpm:
      image: php-fpm
      ports:
        - "${WORKSPACE_SSH_PORT}:22"
        - 8080:8080  # npm run hot
        - 6060:6060 # styleguide
        - 35729:35729 # livereload ← 追加!

ブラウザの自動更新を有効にする②

次はChrome側です。

吐き出されたHTMLファイルを開いて、ChromeExteintionのlivereloadを有効にします。 なんかアイコンがやたらわかりにくいので画像で説明します。

f:id:moyashidaisuke:20191029221602p:plain

f:id:moyashidaisuke:20191029221606p:plain

これで完了です!