公式テーマの webpack ビルド環境の使い方
Beginnerテーマ以外の公式テーマには、 webpack のビルド環境が用意されています。このエントリーでは、webpack に馴染みがない方を対象に、導入の手順を解説します。
導入する前にはとっつきにくい印象のある webpack ですが、いったん慣れてしまうと意外に簡単でとても便利です。特に a-blog cms の公式テーマに同梱されているビルド環境はすべて設定済みであとは「使うだけ」なので最初の一歩として最適です。
（このエントリーの末尾で webpack を使用しない場合の注意点 についても触れています。）
webpack 導入のメリット
- 文法チェックやプロパティ順の整理を自動でやってくれるのでコードが読みやすく、メンテナンスしやすくなる
- スタイルや機能のモジュール化をしやすいので他案件への転用が簡単になる
- 使用しているエディタやツールに依存しないのでチームでの開発環境を揃えることができる
- LiveReload ( npm run start )を使うとファイルを保存すればブラウザが自動でリロードされるので開発効率が上がる
- CSSは /dest/bundle.min.css、JavaScript は /dest/bundle.js にまとめられ、パフォーマンスが向上する
- 慣れてくると外部のライブラリを読み込んで利用することも簡単にできるようになる
webpack 導入の手順
node.js をまだインストールしていない場合は .node-version でバージョンを確認し、node.js をインストールする
2022年8月現在、UTSUWA同梱のビルド環境の .node-version ファイルを開くと v14.16.0 になっています。
公式サイトのインストーラを使ってインストールする場合は、バージョン一覧から該当のバージョンを選んでください。コマンドでの操作に慣れている場合は、nodenv (Mac)、fnm (Windows) などの node バージョン管理ツールを使用するのがお勧めです。
インストールした後、ターミナルやコマンドプロンプトで
$ node -v （ または node --version ）
と打って該当のバージョン番号が表示されればオーケーです。
package.json でローカル環境のアドレスとテーマ名を設定する
LiveReload ( npm run start ) を使う場合に基準となる設定です。LiveReload を使わない場合はこの手順は飛ばしてかまいません。
"config": {
"local": "acms.lab", （ http:// や https:// は不要です ）
"theme": "テーマ名" （ テーマ名を utsuwa 以外にする場合は変更します ）
},
cd コマンドで themes/テーマ名 に移動して npm を使ってパッケージをインストールする
cd は change directory の略です。今いる場所が分からない場合は pwd ( present working directory ) コマンドで確認できます。
$ cd www/themes/テーマ名 （ パスはローカル環境のフォルダ構成や現在地によって異なります ）
$ npm i（ または npm install ）
必要なパッケージがインストールされると themes/テーマ名/node_modules というフォルダができて中にたくさんのファイルがダウンロードされます。ダウンロードが終わったらメッセージを見て、必要そうであれば
$ npm audit fix
しておきましょう。
※ 子テーマを使用する場合でも、ビルド環境は親テーマだけでまとめておきましょう。
ファイルを watch してコンパイルする
$ npm run dev
あるいは
$ npm run start
で src フォルダ内のファイルを watch して dest フォルダにコンパイルし始めます。npm run start は LiveReload の機能を含んでいるので、src フォルダ内のファイルを変更して保存するたびに自動的にブラウザがリロードされます。LiveReload 使用時にはブラウザのURL欄には「localhost::3000」が表示されます。これらのコマンドを止めるには「Ctrl + C」を押します。
ファイルを build する
納品時やリモートへの反映時などには
$ npm run build
でファイルを build することによって、最適化されたコンパイルになります。このコマンドは実行に少しだけ時間がかかり、終わったら自動的に止まります。
JavaScript について
/src/js/index.js からさまざまなファイルを読み込んで /dest/bundle.js にコンパイルされています。その内容については各テーマフォルダに同梱されている README.md をご確認ください。
エラーが出たら
コマンドが問題なく実行されているときにはターミナルの画面に実行結果がスラスラと表示され続けていますが、赤字でエラーが表示された場合は、エラーメッセージを読んで対処しましょう。
Sass のルールは .stylelintrc、 JavaScript のルールは .eslintrc の rules のブロックに追記することでそれぞれ個別にオンオフすることができます。.stylelintrc では true / null で、.eslintrc では 0 / 1（警告を出す） / 2（エラーを出す）という値で設定します。たとえば、.stylelintrc の rules ブロックに
"block-no-empty": null,
と追記すると、Sass ファイルに空のブロックがあってもエラーがでなくなります。
より高度な内容について
これだけで一通りのビルドはできますが、全CSSのインライン化や組み込みJSの整理、各ファイルの役割など、より高度な内容についてはこちらもご確認ください。
webpack を使用しない場合の注意点
補足として、webpack を使用しない場合に抑えておいたほうが良い点について説明します。
独自カスタマイズ用の CSS と JavaScript
/include/head/link.html において
<link rel="stylesheet" href="/dest/bundle.min.css">
<link rel="stylesheet" href="/css/style.css">
/include/head/js.html において
<script src="/dest/bundle.js" defer></script>
<script src="/js/script.js" defer></script>
のように独自カスタマイズ用の CSS ファイル、JS ファイルへのパスを追記して、追加した CSS ファイルでスタイルを上書き、追加していきます。script タグでは JSファイルの実行順を担保するため、async属性ではなく、defer属性を使います。
不要なファイルを削除する
不要なファイルはそのままにしておいても問題はありませんが、削除するとファイル構成が分かりやすくなります。コンパイルによる予期せぬ先祖がえりを防ぐためにも削除しておくことをお勧めします。
utsuwa/ 直下の不要なファイル
- .eslintrc
- .node-version
- .stylelintrc
- babel.config.js
- package-lock.json
- package.json
- webpack.analyze.js
- webpack.common.js
- webpack.dev.js
- webpack.prod.js
- webpack.uncompress.js
/src/ フォルダ
Sassを使用しない場合はフォルダごと削除してください。Sassを使用する場合は /src/scss を残して、お使いのコンパイルツールにあった設定にしてください。