【保存版】Rails 5 Webpacker公式ドキュメントの歩き方+追加情報

こんにちは、hachi8833です。

Rails 5のWebpackerでつらみを踏まないために、公式のWebpackerドキュメントの要点をまとめてみました。追加情報がありましたら今後も更新したいと思います。


rails/webpackerより

公式のドキュメントが分散しているのと、mdファイル名から内容が推測しにくくて見通しがよくないので、ファイルの並びを再編成して概要を一覧できるようにしました(せめてファイル名の頭に番号でも振ってくれれば…)。具体的な設定方法についてはリンク先をご覧ください。

概要

  • ドキュメントリポジトリ: rails/webpacker/tree/master/docs — mdが16ファイルあります。本記事ではこちらのみを扱います。
  • 上のドキュメントリポジトリの最終更新日: 2018/04/23
    • 更新や誤りにお気づきの方は@hachi8833までお知らせください。
  • 参考: Webpack公式ガイド
  • 参考: README rails/webpacker — こちらが網羅的ですが、ドキュメントと重複している部分もあります。READMEの日本語訳は以下の記事をご覧ください。

Rails 5: Webpacker公式README — Webpack v4対応版(翻訳)

Webpackerのインストール方法

Rails 5のWebpackerは以下のいずれかの方法で導入できます。

  • 新規の場合: rails new アプリ名 --webpack
  • 後からの場合: Gemfileでgem 'webpacker'を有効にして、bin/rails webpacker:installを実行

Webpacker公式ドキュメントの一覧

以下、重要な順にリストアップします。

1. 最初に読むもの

  • yarn.mdyarnで nodeのモジュールを追加する方法です。ほんのちょっぴりです。
  • webpack.md — Webpackの公式な設定方法が記載されています。重要度高し(後述)。
  • folder-structure.md — Webpackerを使った場合のフォルダ構造や名前空間の切り方について説明されています。
  • env.md — オプションで設定できるWebpacker環境変数について説明されています。開発環境でForemanInvokerを併用する場合の注意点についても書かれてます。

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.mdwebpack-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さん、情報ありがとうございました!🙇

4. 参考に読むもの

  • docker.md — Docker化されたRailsアプリでWebpackerを使う方法について説明されています。簡単だと言ってます。
  • cloud9.md — devサーバーをAWSのCloud9環境で使う方法について説明されています。
  • es6.md — Webpackerに同梱されているBabel経由で利用できるECMA6の機能や、require()module.exportsではなくimportexportを使うべきという注意事項が記載されています。
  • 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)を作成できるようになる。
    • 共通モジュールをバンドルから切り離すことで、生成されたチャンクファイルが最初に一括読み込みされ、キャッシュに保存されて後で利用できるようになる。
    • 共通コードがキャッシュから読み出されるのでブラウザ表示が高速化される。
    • 新しいページを開くたびに巨大なバンドルを毎度強制読み込みしなくてよくなる。
  • 設定方法はドキュメントを参照

関連記事

Rails 5: Webpacker公式README — Webpack v4対応版(翻訳)

新しいRailsフロントエンド開発(1)Asset PipelineからWebpackへ(翻訳)

RailsのVue.jsをWebpackerとJestでテストする(翻訳)

デザインも頼めるシステム開発会社をお探しならBPS株式会社までどうぞ 開発エンジニア積極採用中です! Ruby on Rails の開発なら実績豊富なBPS

この記事の著者

hachi8833

Twitter: @hachi8833、GitHub: @hachi8833 コボラー、ITコンサル、ローカライズ業界、Rails開発を経てTechRachoの編集・記事作成を担当。 これまでにRuby on Rails チュートリアル第2版の半分ほど、Railsガイドの初期翻訳ではほぼすべてを翻訳。その後も折に触れてそれぞれ一部を翻訳。 かと思うと、正規表現の粋を尽くした日本語エラーチェックサービス enno.jpを運営。 実は最近Go言語が好き。 仕事に関係ないすっとこブログ「あけてくれ」は2000年頃から多少の中断をはさんで継続、現在はnote.muに移転。

hachi8833の書いた記事

週刊Railsウォッチ

インフラ

ActiveSupport探訪シリーズ