こんにちは、hachi8833です。
Rails 5のWebpackerでつらみを踏まないために、公式のWebpackerドキュメントの要点をまとめてみました。追加情報がありましたら今後も更新したいと思います。
rails/webpackerより
公式のドキュメントが分散しているのと、mdファイル名から内容が推測しにくくて見通しがよくないので、ファイルの並びを再編成して概要を一覧できるようにしました（せめてファイル名の頭に番号でも振ってくれれば...）。具体的な設定方法についてはリンク先をご覧ください。
⚓概要
- ドキュメントリポジトリ: rails/webpacker/tree/master/docs -- mdが16ファイルあります。本記事ではこちらのみを扱います。
- 上のドキュメントリポジトリの最終更新日: 2018/04/23
- 更新や誤りにお気づきの方は@hachi8833までお知らせください。
- 参考: Webpack公式ガイド
- 参考: README rails/webpacker -- こちらが網羅的ですが、ドキュメントと重複している部分もあります。READMEの日本語訳は以下の記事をご覧ください。
⚓Webpackerのインストール方法
Rails 5のWebpackerは以下のいずれかの方法で導入できます。
- 新規の場合:
rails new アプリ名 --webpack - 後からの場合: Gemfileで
gem 'webpacker'を有効にして、bin/rails webpacker:installを実行
⚓Webpacker公式ドキュメントの一覧
以下、重要な順にリストアップします。
⚓1. 最初に読むもの
- yarn.md --
yarnで nodeのモジュールを追加する方法です。ほんのちょっぴりです。 - webpack.md -- Webpackの公式な設定方法が記載されています。重要度高し（後述）。
- folder-structure.md -- Webpackerを使った場合のフォルダ構造や名前空間の切り方について説明されています。
- env.md -- オプションで設定できるWebpacker環境変数について説明されています。開発環境でForemanやInvokerを併用する場合の注意点についても書かれてます。
⚓2. 次ぐらいに読むもの
- assets.md -- Railsビューから静的アセットにリンクする方法、静的アセットをNodeモジュールからインポートする方法、ヘルパー経由でSprocketsから静的アセットをインポートする方法、Babelのモジュールリゾルバで静的アセットを直接参照する方法について説明されています。
- css.md -- CSS/SaSS/SCSSをJavaScriptファイルにグローバルまたはスコープ指定で直接インポートする方法などについて説明されています。Railsビューでのリンク方法、Bootstrapの追加方法、CSSのpost-processライブラリの読み込み方法、vue-loaderによるCSS読み込み、url-loaderによるCSS読み込み方法についても記載されています。
⚓3. その次ぐらいに読むもの
- webpack-dev-server.md --
webpack-dev-serverで開発環境向けのローカルWebサーバーを立ててファイル更新を自動で反映する方法について説明されています（追記参照↓）。- misc.md -- vimやemacsを利用中に特定のファイルを自動反映の対象外にする方法について説明されています。
- testing.md -- Capybaraの設定方法や、TypeScript向けに
Karmaを設定する方法について説明されています。 - deployment.md -- Heroku/Nginx/CDNでのデプロイの注意点について簡単に説明されています。Sprocketsを使わない場合の方法についても記載されています。
- troubleshooting.md -- 文字どおりのトラブルシューティング集です。
追記（2018/05/18）: 上で言及されているwebpack/webpack-dev-serverは現在メンテナンスモードに移行済みです。現在はdevなしのwebpack-contrib/webpack-serveに移行しましたが、現時点ではRailsのWebpackerリポジトリにまだ導入されていない様子です。新名称の末尾はserverではなくserveなので微妙に紛らわしいです。
morimorihogeさん、情報ありがとうございました！🙇
追記（2018/10/22）: さらにその後、上記のwebpack-serveはメンテナー不在などの理由によりdeprecatedとなっています。現在は元のwebpack-dev-serverを使うよう指示されています。上の情報は古いのでご注意下さい。
⚓4. 参考に読むもの
- docker.md -- Docker化されたRailsアプリでWebpackerを使う方法について説明されています。簡単だと言ってます。
- cloud9.md -- devサーバーをAWSのCloud9環境で使う方法について説明されています。
- es6.md -- Webpackerに同梱されているBabel経由で利用できるECMA6の機能や、
require()やmodule.exportsではなくimportやexportを使うべきという注意事項が記載されています。 - typescript.md -- TypeScriptをReact.jsやVue.jsで利用する方法や、HTMLテンプレートとAngularで利用する方法について説明されています。
- props.md -- React.jsやVue.jsやElm.jsでの
propsの使い方について説明されています。
⚓webpack.mdの要点
webpack.mdは重要度が高いので、以下に要点をまとめます。
⚓1. 設定
- development/test/production環境向けの設定は
config/webpack/*.jsに保存される- デフォルトの
config/webpack/*.jsはproductionで使える標準設定になっているので、基本的に変更は不要。 - 必要な場合は
config/webpack/environment.jsを参考にそれぞれの環境向けに設定するとよい。
- デフォルトの
注意: 公式の設定サンプルでやっているように
aliasで指定すること。
// config/webpack/custom.js
module.exports = {
resolve: {
alias: {
jquery: 'jquery/src/jquery',
vue: 'vue/dist/vue.js',
React: 'react',
ReactDOM: 'react-dom',
vue_resource: 'vue-resource/dist/vue-resource',
}
}
}
⚓2. ローダー
- Webpackerが持つ以外のローダーも
yarnで環境に追加できる。後はドキュメントのとおりに設定。
yarn add json-loader
- Webpackerが持つローダーの設定をカスタマイズすることも可能。以下は
babelをカスタマイズする場合。
// config/webpack/environment.js
const { environment } = require('@rails/webpacker')
const babelLoader = environment.loaders.get('babel')
babelLoader.options.cacheDirectory = false
module.exports = environment
a. CoffeeScriptの場合
- WebpackerではCoffeeScript 1がデフォルトで利用できる。CoffeeScript 2を使いたいのであれば
yarn add coffeescript@2.0.1で追加してからドキュメントに従って設定する。
b. React SVG loaderの場合
- React SVG loaderを使う場合、SVGローダーはファイルローダーより前に読み込むこと。
c. URL loaderの場合
（設定方法のみ）
d. Webpacker 3以降でローダーオプションをオーバーライドする方法
- ローダーにオプションを足したり変更したりしたい場合は、
config/webpack/environment.jsを編集してオーバーライド用のオブジェクトを用意すること。- オーバーライド方法については#756も参照
- 以下はCSS Modulesをオーバーライドする場合
const { environment } = require('@rails/webpacker')
const merge = require('webpack-merge')
const myCssLoaderOptions = {
modules: true,
sourceMap: true,
localIdentName: '[name]__[local]___[hash:base64:5]'
}
const CSSLoader = environment.loaders.get('sass').use.find(el => el.loader === 'css-loader')
CSSLoader.options = merge(CSSLoader.options, myCssLoaderOptions)
module.exports = environment
- ビューに
stylesheet_pack_tagを置かないと効かないことに注意。
<%= stylesheet_pack_tag 'YOUR_PACK_NAME_HERE' %>
⚓3. プラグイン
- Webpackプラグインの追加/変更方法は上述のローダーと同じ手順でできる。
⚓4. モジュールの解決
resolve.modulesへのパスを追加するAPIは、ローダーやプラグインの場合と同じ。
const { environment } = require('@rails/webpacker')
// Resolved modules list API - prepend, append, insert
environment.resolvedModules.append('vendor', 'vendor')
a. CommonsChunkPlugin
CommonsChunkPluginを使うと、複数のエントリポイントで使われる共通モジュールを含む個別のファイル（チャンク: chunk）を作成できるようになる。- 共通モジュールをバンドルから切り離すことで、生成されたチャンクファイルが最初に一括読み込みされ、キャッシュに保存されて後で利用できるようになる。
- 共通コードがキャッシュから読み出されるのでブラウザ表示が高速化される。
- 新しいページを開くたびに巨大なバンドルを毎度強制読み込みしなくてよくなる。
- 設定方法はドキュメントを参照
- 詳しくはWebpack公式ガイドも参照。