webpacker 2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a0e2ae99bad3184ab44d798809fbd0efe458e38
-  data.tar.gz: 0a6a47fa0b5a829e4ff418891310a1cfeb7e2288
+  metadata.gz: d46b2ad0a755995989397dd57d6a3f62fd8b6e29
+  data.tar.gz: 3bc409359bdb19b000d18a85e43d5e32c53c2160
 SHA512:
-  metadata.gz: e162e508430b3179b5e0aded52ddf815be5b4f6f67dbf01cd822a18c9f6227773b0f44adfef45a74d9c11e2b73dce64e0209352236f8156602bd08e2009b95b4
-  data.tar.gz: da29a763948aadb84689b1cc94f884e78489d28319a920bfd76e43f8d6ac8b6d61df74db4de707de101c47407fbafe770b29db9e67c1e9d24292042c55bdbdf7
+  metadata.gz: b6b403b49ea4bd344acb77cf3d02f4d05cee50ace386f05d598f70583ba6f19d3f6114fcec33944e46dd8d7bbaccf6590598225ec0d6159168fe1d016844f9d6
+  data.tar.gz: 48d1d6686da5d7a9127bff68a26827e95c772b6f7966960b9ee0000707c0579b86db76bfae232dd4cfb74fbfc062b24940147eae270058f8bb8bcdf4ee4cf75c

data/.gitignore

@@ -2,3 +2,5 @@
 /pkg
 /test/test_app/log
 node_modules
+.byebug_history
+/test/test_app/tmp

data/.rubocop.yml

@@ -18,27 +18,27 @@ Style/BracesAroundHashParameters:
   Enabled: true
 
 # Align `when` with `case`.
-Style/CaseIndentation:
+Layout/CaseIndentation:
   Enabled: true
 
 # Align comments with method definitions.
-Style/CommentIndentation:
+Layout/CommentIndentation:
   Enabled: true
 
 # No extra empty lines.
-Style/EmptyLines:
+Layout/EmptyLines:
   Enabled: true
 
 # In a regular class definition, no empty lines around the body.
-Style/EmptyLinesAroundClassBody:
+Layout/EmptyLinesAroundClassBody:
   Enabled: true
 
 # In a regular method definition, no empty lines around the body.
-Style/EmptyLinesAroundMethodBody:
+Layout/EmptyLinesAroundMethodBody:
   Enabled: true
 
 # In a regular module definition, no empty lines around the body.
-Style/EmptyLinesAroundModuleBody:
+Layout/EmptyLinesAroundModuleBody:
   Enabled: true
 
 # Use Ruby >= 1.9 syntax for hashes. Prefer { a: :b } over { :a => :b }.
@@ -47,30 +47,30 @@ Style/HashSyntax:
 
 # Method definitions after `private` or `protected` isolated calls need one
 # extra level of indentation.
-Style/IndentationConsistency:
+Layout/IndentationConsistency:
   Enabled: true
   EnforcedStyle: rails
 
 # Two spaces, no tabs (for indentation).
-Style/IndentationWidth:
+Layout/IndentationWidth:
   Enabled: true
 
-Style/SpaceAfterColon:
+Layout/SpaceAfterColon:
   Enabled: true
 
-Style/SpaceAfterComma:
+Layout/SpaceAfterComma:
   Enabled: true
 
-Style/SpaceAroundEqualsInParameterDefault:
+Layout/SpaceAroundEqualsInParameterDefault:
   Enabled: true
 
-Style/SpaceAroundKeyword:
+Layout/SpaceAroundKeyword:
   Enabled: true
 
-Style/SpaceAroundOperators:
+Layout/SpaceAroundOperators:
   Enabled: true
 
-Style/SpaceBeforeFirstArg:
+Layout/SpaceBeforeFirstArg:
     Enabled: true
 
 # Defining a method with parameters needs parentheses.
@@ -78,18 +78,18 @@ Style/MethodDefParentheses:
   Enabled: true
 
 # Use `foo {}` not `foo{}`.
-Style/SpaceBeforeBlockBraces:
+Layout/SpaceBeforeBlockBraces:
   Enabled: true
 
 # Use `foo { bar }` not `foo {bar}`.
-Style/SpaceInsideBlockBraces:
+Layout/SpaceInsideBlockBraces:
   Enabled: true
 
 # Use `{ a: 1 }` not `{a:1}`.
-Style/SpaceInsideHashLiteralBraces:
+Layout/SpaceInsideHashLiteralBraces:
   Enabled: true
 
-Style/SpaceInsideParens:
+Layout/SpaceInsideParens:
   Enabled: true
 
 # Check quotes usage according to lint rule below.
@@ -98,15 +98,15 @@ Style/StringLiterals:
   EnforcedStyle: double_quotes
 
 # Detect hard tabs, no hard tabs.
-Style/Tab:
+Layout/Tab:
   Enabled: true
 
 # Blank lines should not have any spaces.
-Style/TrailingBlankLines:
+Layout/TrailingBlankLines:
   Enabled: true
 
 # No trailing whitespace.
-Style/TrailingWhitespace:
+Layout/TrailingWhitespace:
   Enabled: true
 
 # Use quotes for string literals when they are enough.

data/CHANGELOG.md

@@ -1,5 +1,102 @@
-## [2.0] - 2017-05-24
+## [3.0.0] - 2017-08-30
+
+### Added
+
+- `resolved_paths` option to allow adding additional paths webpack should lookup when resolving modules
+
+```yml
+  # config/webpacker.yml
+  # Additional paths webpack should lookup modules
+  resolved_paths: [] # empty by default
+```
+
+- `Webpacker::Compiler.fresh?` and `Webpacker::Compiler.stale?` answer the question of whether compilation is needed.
+  The old `Webpacker::Compiler.compile?` predicate is deprecated.
+
+- Dev server config class that exposes config options through singleton.
+
+  ```rb
+  Webpacker.dev_server.running?
+  ```
+
+- Rack middleware proxies webpacker requests to dev server so we can always serve from same-origin and the lookup works out of the box - no more paths prefixing
+
+- `env` attribute on `Webpacker::Compiler` allows setting custom environment variables that the compilation is being run with
+
+  ```rb
+  Webpacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
+  ```
+
+### Breaking changes
+
+**Note:** requires running `bundle exec rails webpacker:install`
+
+`config/webpack/**/*.js`:
+
+- The majority of this config moved to the [@rails/webpacker npm package](https://www.npmjs.com/package/@rails/webpacker). `webpacker:install` only creates `config/webpack/{environment,development,test,production}.js` now so if you're upgrading from a previous version you can remove all other files.
+
+`webpacker.yml`:
+
+- Move dev-server config options under defaults so it's transparently available in all environments
+
+- Add new `HMR` option for hot-module-replacement
+
+- Add HTTPS
+
+### Removed
+
+- Host info from manifest.json, now looks like this:
+
+  ```json
+  {
+    "hello_react.js": "/packs/hello_react.js"
+  }
+  ```
+
+### Fixed
+
+- Update `webpack-dev-server.tt` to respect RAILS_ENV and NODE_ENV values [#502](https://github.com/rails/webpacker/issues/502)
+- Use `0.0.0.0` as default listen address for `webpack-dev-server`
+- Serve assets using `localhost` from dev server - [#424](https://github.com/rails/webpacker/issues/424)
+
+```yml
+  dev_server:
+    host: localhost
+```
+
+- On Windows, `ruby bin/webpacker` and `ruby bin/webpacker-dev-server` will now bypass yarn, and execute via `node_modules/.bin` directly - [#584](https://github.com/rails/webpacker/pull/584)
+
+### Breaking changes
+
+- Add `compile` option to `config/webpacker.yml` for configuring lazy compilation of packs when a file under tracked paths is changed [#503](https://github.com/rails/webpacker/pull/503). To enable expected behavior, update `config/webpacker.yml`:
 
+  ```yaml
+    test:
+      compile: true
+
+    development:
+      compile: true
+
+    production:
+      compile: false
+  ```
+
+- Make test compilation cacheable and configurable so that the lazy compilation
+only triggers if files are changed under tracked paths.
+Following paths are watched by default -
+
+  ```rb
+    ["app/javascript/**/*", "yarn.lock", "package.json", "config/webpack/**/*"]
+  ```
+
+  To add more paths:
+
+  ```rb
+  # config/initializers/webpacker.rb or config/application.rb
+  Webpacker::Compiler.watched_paths << 'bower_components'
+  ```
+
+## [2.0] - 2017-05-24
 
 ### Fixed
 - Update `.babelrc` to fix compilation issues - [#306](https://github.com/rails/webpacker/issues/306)
@@ -69,11 +166,17 @@
   bundle exec rails webpacker:install
 
   # Remove old/unused configuration files
-  rm config/paths.yml
-  rm config/development.server.yml
-  rm config/development.server.js
+  rm config/webpack/paths.yml
+  rm config/webpack/development.server.yml
+  rm config/webpack/development.server.js
   ```
 
+  __Warning__: For now you also have to add a pattern in `.gitignore` by hand.
+  ```diff
+   /public/packs
+  +/public/packs-test
+   /node_modules
+   ```
 
 ## [1.2] - 2017-04-27
 Some of the changes made requires you to run below commands to install new changes.

data/Gemfile

@@ -4,8 +4,10 @@ gemspec
 
 gem "rails"
 gem "rake", ">= 11.1"
-gem "rubocop", ">= 0.47", require: false
+gem "rubocop", ">= 0.49", require: false
+gem "rack-proxy", require: false
 
 group :test do
   gem "minitest", "~> 5.0"
+  gem "byebug"
 end

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    webpacker (1.2)
+    webpacker (2.0)
       activesupport (>= 4.2)
-      multi_json (~> 1.2)
+      rack-proxy (>= 0.6.1)
       railties (>= 4.2)
 
 GEM
@@ -49,6 +49,7 @@ GEM
     arel (7.1.4)
     ast (2.3.0)
     builder (3.2.3)
+    byebug (9.0.6)
     concurrent-ruby (1.0.5)
     erubis (2.7.0)
     globalid (0.3.7)
@@ -64,14 +65,16 @@ GEM
     mime-types-data (3.2016.0521)
     mini_portile2 (2.1.0)
     minitest (5.10.1)
-    multi_json (1.12.1)
     nio4r (1.2.1)
     nokogiri (1.7.0.1)
       mini_portile2 (~> 2.1.0)
+    parallel (1.12.0)
     parser (2.4.0.0)
       ast (~> 2.2)
     powerpack (0.1.1)
     rack (2.0.1)
+    rack-proxy (0.6.1)
+      rack
     rack-test (0.6.3)
       rack (>= 1.0)
     rails (5.0.1)
@@ -97,9 +100,11 @@ GEM
       method_source
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
-    rainbow (2.2.1)
+    rainbow (2.2.2)
+      rake
     rake (12.0.0)
-    rubocop (0.47.1)
+    rubocop (0.49.1)
+      parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
       powerpack (~> 0.1)
       rainbow (>= 1.99.1, < 3.0)
@@ -117,7 +122,7 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    unicode-display_width (1.1.3)
+    unicode-display_width (1.3.0)
     websocket-driver (0.6.5)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.2)
@@ -127,11 +132,13 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.12)
+  byebug
   minitest (~> 5.0)
+  rack-proxy
   rails
   rake (>= 11.1)
-  rubocop (>= 0.47)
+  rubocop (>= 0.49)
   webpacker!
 
 BUNDLED WITH
-   1.14.6
+   1.15.3

data/README.md

@@ -1,11 +1,11 @@
 # Webpacker
 
 ![travis-ci status](https://api.travis-ci.org/rails/webpacker.svg?branch=master)
-[![node.js](https://img.shields.io/badge/node-%3E%3D%206.4.0-brightgreen.svg)](https://nodejs.org/en/)
+[![node.js](https://img.shields.io/badge/node-%3E%3D%206.0.0-brightgreen.svg)](https://nodejs.org/en/)
 [![Gem](https://img.shields.io/gem/v/webpacker.svg)](https://github.com/rails/webpacker)
 
 Webpacker makes it easy to use the JavaScript pre-processor and bundler
-[Webpack 2.x.x+](https://webpack.js.org/)
+[Webpack 3.x.x+](https://webpack.js.org/)
 to manage application-like JavaScript in Rails. It coexists with the asset pipeline,
 as the primary purpose for Webpack is app-like JavaScript, not images, CSS, or
 even JavaScript Sprinkles (that all continues to live in app/assets).
@@ -20,51 +20,18 @@ in which case you may not even need the asset pipeline. This is mostly relevant
 - [Prerequisites](#prerequisites)
 - [Features](#features)
 - [Installation](#installation)
+  - [Usage](#usage)
+  - [Development](#development)
 - [Integrations](#integrations)
   - [React](#react)
   - [Angular with TypeScript](#angular-with-typescript)
   - [Vue](#vue)
   - [Elm](#elm)
-- [Binstubs](#binstubs)
-  - [Webpack dev server](#webpack-dev-server)
-  - [Webpack](#webpack)
-- [Configuration](#configuration)
-  - [Webpack](#webpack-1)
-  - [Loaders](#loaders)
-  - [Paths](#paths)
-  - [Babel](#babel)
-  - [Post-Processing CSS](#post-processing-css)
-  - [CDN](#cdn)
-  - [HTTPS in development](#https-in-development)
-  - [Hot module replacement](#hot-module-replacement)
-- [Linking Styles, Images and Fonts](#linking-styles-images-and-fonts)
-  - [Within your JS app](#within-your-js-app)
-  - [Inside views](#inside-views)
-  - [From node modules folder](#from-node-modules-folder)
-- [How-tos](#how-tos)
-  - [App structure](#app-structure)
-    - [Namespacing](#namespacing)
-  - [Pass data from view](#pass-data-from-view)
-    - [React](#react-1)
-    - [Vue](#vue-1)
-  - [Add common chunks](#add-common-chunks)
-  - [Module import() vs require()](#module-import-vs-require)
-  - [Add a new npm module](#add-a-new-npm-module)
-  - [Add bootstrap](#add-bootstrap)
-  - [Use Typescript with React](#use-typescript-with-react)
-  - [HTML templates with Typescript](#html-templates-with-typescript)
-  - [CSS modules](#css-modules)
-  - [CSS-Next](#css-next)
-  - [Ignoring swap files](#ignoring-swap-files)
-  - [Link sprocket assets](#link-sprocket-assets)
-    - [Using helpers](#using-helpers)
-    - [Using babel module resolver](#using-babel-module-resolver)
-- [Extending](#extending)
+- [Paths](#paths)
+  - [Resolved](#resolved)
+  - [Watched](#watched)
 - [Deployment](#deployment)
-  - [Heroku](#heroku)
-- [Testing](#testing)
-- [Troubleshooting](#troubleshooting)
-- [Wishlist](#wishlist)
+- [Docs](#docs)
 - [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -74,18 +41,18 @@ in which case you may not even need the asset pipeline. This is mostly relevant
 
 * Ruby 2.2+
 * Rails 4.2+
-* Node.js 6.4.0+
+* Node.js 6.0.0+
 * Yarn 0.20.1+
 
 
 ## Features
 
-* [Webpack 2](https://webpack.js.org/)
+* [Webpack 3.x.x](https://webpack.js.org/)
 * ES6 with [babel](https://babeljs.io/)
 * Automatic code splitting using multiple entry points
-* Stylesheets - sass and CSS
+* Stylesheets - SASS and CSS
 * Images and fonts
-* PostCSS - auto-prefixer
+* PostCSS - Auto-Prefixer
 * Asset compression, source-maps, and minification
 * CDN support
 * React, Angular, Elm and Vue support out-of-the-box
@@ -100,39 +67,107 @@ using new `--webpack` option:
 
 ```bash
 # Available Rails 5.1+
-./bin/rails new myapp --webpack
+rails new myapp --webpack
 ```
 
-Or add it to your `Gemfile`, run bundle and `./bin/rails webpacker:install` or `bundle exec rake webpacker:install` (on rails version < 5.0):
+Or add it to your `Gemfile`:
 
 ```ruby
 # Gemfile
-gem 'webpacker', '~> 2.0'
+gem 'webpacker', '~> 3.0'
 
 # OR if you prefer to use master
 gem 'webpacker', git: 'https://github.com/rails/webpacker.git'
 ```
 
-**Note:** Use `rake` instead of `rails` if you are using webpacker
-with rails version < 5.0
+and finally, run following to install webpacker:
 
+```bash
+bundle
+bundle exec rails webpacker:install
 
-## Integrations
+# OR (on rails version < 5.0)
+bundle exec rake webpacker:install
+```
+
+### Usage
+
+Once installed you can start writing modern ES6-flavored JavaScript app today:
+
+```yml
+app/javascript:
+  ├── packs:
+  │   # only webpack entry files here
+  │   └── application.js
+  └── src:
+  │   └── application.css
+  └── images:
+      └── logo.svg
+```
+
+You can then link the javascript pack in Rails view using `javascript_pack_tag` helper.
+If you have styles imported in your pack file, you can link using `stylesheet_pack_tag`:
+
+```erb
+<%= javascript_pack_tag 'application' %>
+<%= stylesheet_pack_tag 'application' %>
+```
+
+If you want to link a static asset for `<link rel="prefetch">` or `<img />` tag, you
+can use `asset_pack_path` helper:
+
+```erb
+<link rel="prefetch" href="<%= asset_pack_path 'application.css' %>" />
+<img src="<%= asset_pack_path 'images/logo.svg' %>" />
+```
+
+**Note:** In order for your styles or static assets files to be available in your view,
+you would need to link them in your "pack" or entry file.
+
+### Development
+
+Webpacker ships with two binstubs: `./bin/webpack` and `./bin/webpack-dev-server`.
+Both are thin wrappers around the standard `webpack.js` and `webpack-dev-server.js`
+executable to ensure that the right configuration file and environment variables
+are loaded depending on your environment.
+
+In development, Webpacker compiles on demand rather than upfront by default. This
+happens when you refer to any of the pack assets using the Webpacker helper methods.
+That means you don't have to run any separate process. Compilation errors are logged
+to the standard Rails log.
 
-Webpacker by default ships with basic out-of-the-box integration
-for React, Angular, Vue and Elm. You can see a list of available
-commands/tasks by running:
+If you want to use live code reloading, or you have enough JavaScript that on-demand compilation is too slow, you'll need to run `./bin/webpack-dev-server` or `ruby ./bin/webpack-dev-server` if on windows,
+in a separate terminal from `bundle exec rails s`. This process will watch for changes
+in the `app/javascript/packs/*.js` files and automatically reload the browser to match.
 
 ```bash
-./bin/rails webpacker
+# webpack dev server
+./bin/webpack-dev-server
+
+# watcher
+./bin/webpack --colors --progress
+
+# standalone build
+./bin/webpack
 ```
 
-or in rails version < 5.0
+Once you start this development server, Webpacker will automatically start proxying all
+webpack asset requests to this server. When you stop the server, it'll revert to
+on-demand compilation again.
+
+You can also pass CLI options supported by [webpack-dev-server](https://webpack.js.org/configuration/dev-server/). Please note that inline options will always take
+precedence over the ones already set in the configuration file.
 
 ```bash
-./bin/rake webpacker
+./bin/webpack-dev-server --host example.com --inline true --hot false
 ```
 
+**Note:** Don't forget to prefix `ruby` when running these binstubs on windows
+
+## Integrations
+
+Webpacker ships with basic out-of-the-box integration for React, Angular, Vue and Elm.
+You can see a list of available commands/tasks by running `bundle exec rails webpacker`:
 
 ### React
 
@@ -141,10 +176,10 @@ new Rails 5.1+ app using `--webpack=react` option:
 
 ```bash
 # Rails 5.1+
-./bin/rails new myapp --webpack=react
+rails new myapp --webpack=react
 ```
 
-(or run `./bin/rails webpacker:install:react` in a existing Rails app already
+(or run `bundle exec rails webpacker:install:react` in a existing Rails app already
 setup with webpacker).
 
 The installer will add all relevant dependencies using yarn, any changes
@@ -159,10 +194,10 @@ new Rails 5.1+ app using `--webpack=angular` option:
 
 ```bash
 # Rails 5.1+
-./bin/rails new myapp --webpack=angular
+rails new myapp --webpack=angular
 ```
 
-(or run `./bin/rails webpacker:install:angular` on a Rails app already
+(or run `bundle exec rails webpacker:install:angular` on a Rails app already
 setup with webpacker).
 
 The installer will add TypeScript and Angular core libraries using yarn plus
@@ -178,9 +213,9 @@ new Rails 5.1+ app using `--webpack=vue` option:
 
 ```bash
 # Rails 5.1+
-./bin/rails new myapp --webpack=vue
+rails new myapp --webpack=vue
 ```
-(or run `./bin/rails webpacker:install:vue` on a Rails app already setup with webpacker).
+(or run `bundle exec rails webpacker:install:vue` on a Rails app already setup with webpacker).
 
 The installer will add Vue and required libraries using yarn plus
 any changes to the configuration files. An example component will
@@ -194,114 +229,18 @@ To use Webpacker with [Elm](http://elm-lang.org), create a
 new Rails 5.1+ app using `--webpack=elm` option:
 
 ```
-./bin/rails new myapp --webpack=elm
+# Rails 5.1+
+rails new myapp --webpack=elm
 ```
 
-(or run `./bin/rails webpacker:install:elm` on a Rails app already setup with webpacker).
+(or run `bundle exec rails webpacker:install:elm` on a Rails app already setup with webpacker).
 
 The Elm library and core packages will be added via Yarn and Elm itself.
 An example `Main.elm` app will also be added to your project in `app/javascript`
 so that you can experiment with Elm right away.
 
 
-## Binstubs
-
-Webpacker ships with two binstubs: `./bin/webpack` and `./bin/webpack-dev-server`.
-Both are thin wrappers around the standard `webpack.js` and `webpack-dev-server.js`
-executable to ensure that the right configuration file and environment variables
-are loaded depending on your environment.
-
-
-### Webpack dev server
-
-In development, you'll need to run `./bin/webpack-dev-server` in a separate terminal
-from `./bin/rails server` to have your `app/javascript/packs/*.js` files compiled
-as you make changes.
-
-`./bin/webpack-dev-server` launches the [Webpack Dev Server](https://webpack.js.org/configuration/dev-server/), which serves your pack files
-on `http://localhost:8080/` by default and supports live code reloading in the development environment. You will need to install additional plugins for Webpack if you want
-features like [Hot Module Replacement](https://webpack.js.org/guides/hmr-react/)
-
-If you'd rather not have to run the two processes separately by hand, you can use [Foreman](https://ddollar.github.io/foreman):
-
-```bash
-gem install foreman
-```
-
-```yml
-# Procfile
-web: bundle exec rails s
-webpacker: ./bin/webpack-dev-server
-```
-
-```bash
-foreman start
-```
-
-You can also pass CLI options supported by [webpack-dev-server](https://webpack.js.org/configuration/dev-server/). Please note that inline options will always take
-precedence over the ones already set in the configuration file.
-
-```bash
-./bin/webpack-dev-server --host 0.0.0.0 --inline true --hot false
-```
-
-
-### Webpack
-
-We recommend using `webpack-dev-server` during development for a better experience,
-however, if you don't want that for some reason you can always use `webpack` binstub with
-watch option, which uses webpack Command Line Interface (CLI). This will use `public_output_path` from `config/webpacker.yml`
-directory to serve your packs using configured rails server.
-
-You can pass cli options available with [Webpack](https://webpack.js.org/api/cli/):
-
-```bash
-./bin/webpack --watch --progress --colours
-```
-
-
-## Configuration
-
-
-### Webpack
-
-Webpacker gives you a default set of configuration files for test, development and
-production environments. They all live together with the shared
-points in `config/webpack/*.js`.
-
-![screen shot 2017-05-23 at 19 56 18](https://cloud.githubusercontent.com/assets/771039/26371229/0983add2-3ff2-11e7-9dc3-d9c2c1094032.png)
-
-By default, you shouldn't have to make any changes to `config/webpack/*.js`
-files since it's all standard production-ready configuration however
-if you do need to customize or add a new loader this is where you would go.
-
-
-### Loaders
-
-Webpack enables the use of loaders to preprocess files. This allows you to
-bundle any static resource way beyond JavaScript. All base loaders
-that ships with webpacker are located inside `config/webpack/loaders`.
-
-If you want to add a new loader, for example, to process `json` files via webpack:
-
-```
-yarn add json-loader
-```
-
-And create a `json.js` file inside `loaders` directory:
-
-```js
-module.exports = {
-  test: /\.json$/,
-  use: 'json-loader'
-}
-```
-
-Now if you `import()` any `.json` files inside your javascript
-they will be processed using `json-loader`. Voila!
-
-
-### Paths
+## Paths
 
 By default, webpacker ships with simple conventions for where the javascript
 app files and compiled webpack bundles will go in your rails app,
@@ -310,820 +249,81 @@ but all these options are configurable from `config/webpacker.yml` file.
 The configuration for what Webpack is supposed to compile by default rests
 on the convention that every file in `app/javascript/packs/*`**(default)**
 or whatever path you set for `source_entry_path` in the `webpacker.yml` configuration
-is turned into their own output files (or entry points, as Webpack calls it).
+is turned into their own output files (or entry points, as Webpack calls it). Therefore you don't want to put anything inside `packs` directory that you do want to be
+an entry file. As a rule thumb, put all files your want to link in your views inside
+"packs" directory and keep everything else under `app/javascript`.
 
 Suppose you want to change the source directory from `app/javascript`
-to `frontend` and output to `assets/packs` this is how you would do it:
+to `frontend` and output to `assets/packs`. This is how you would do it:
 
 ```yml
 # config/webpacker.yml
 source_path: frontend
 source_entry_path: packs
-public_output_path: assets/packs => public/assets/packs
+public_output_path: assets/packs # outputs to => public/assets/packs
 ```
 
-Similary you can also control and configure `webpack-dev-server` settings from `config/webpacker.yml` file:
+Similarly you can also control and configure `webpack-dev-server` settings from `config/webpacker.yml` file:
 
 ```yml
 # config/webpacker.yml
 development:
   dev_server:
-    host: 0.0.0.0
-    port: 8080
-    https: false
-```
-
-
-### Babel
-
-Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so
-you can use next generation JavaScript, today. The Webpacker installer sets up a
-standard `.babelrc` file in your app root, which will work great in most cases
-because of [babel-env-preset](https://github.com/babel/babel-preset-env).
-
-Following ES6/7 features are supported out of the box:
-
-* Async/await.
-* Object Rest/Spread Properties.
-* Exponentiation Operator.
-* Dynamic import() - useful for route level code-splitting
-* Class Fields and Static Properties.
-
-We have also included [babel polyfill](https://babeljs.io/docs/usage/polyfill/)
-that includes a custom regenerator runtime and core-js.
-
-
-### Post-Processing CSS
-
-Webpacker out-of-the-box provides CSS post-processing using
-[postcss-loader](https://github.com/postcss/postcss-loader)
-and the installer sets up a standard `.postcssrc.yml`
-file in your app root with standard plugins.
-
-```yml
-plugins:
-  postcss-smart-import: {}
-  precss: {}
-  autoprefixer: {}
-```
-
-
-### CDN
-
-Webpacker out-of-the-box provides CDN support using your Rails app `config.action_controller.asset_host` setting. If you already have [CDN](http://guides.rubyonrails.org/asset_pipeline.html#cdns) added in your rails app
-you don't need to do anything extra for webpacker, it just works.
-
-### HTTPS in development
-
-You may require the `webpack-dev-server` to serve views over HTTPS in development.
-To do this, set the `https` option for `webpack-dev-server`
-to `true` in `config/webpacker.yml`, then start the dev server as usual
-with `./bin/webpack-dev-server`.
-
-Please note that the `webpack-dev-server` will use a self-signed certificate,
-so your web browser will display a warning upon accessing the page.
-
-
-### Hot module replacement
-
-Webpacker out-of-the-box doesn't ship with HMR just yet. You will need to
-install additional plugins for Webpack if you want to add HMR support.
-
-You can checkout these links on this subject:
-
-- https://webpack.js.org/configuration/dev-server/#devserver-hot
-- https://webpack.js.org/guides/hmr-react/
-
-
-## Linking Styles, Images and Fonts
-
-Static assets like images, fonts and stylesheets support is enabled out-of-box
-and you can link them into your javascript app code and have them
-compiled automatically.
-
-
-### Within your JS app
-
-```sass
-// app/javascript/hello_react/styles/hello-react.sass
-
-.hello-react
-  padding: 20px
-  font-size: 12px
-```
-
-```js
-// React component example
-// app/javascripts/packs/hello_react.jsx
-
-import React from 'react'
-import helloIcon from '../hello_react/images/icon.png'
-import '../hello_react/styles/hello-react.sass'
-
-const Hello = props => (
-  <div className="hello-react">
-    <img src={helloIcon} alt="hello-icon" />
-    <p>Hello {props.name}!</p>
-  </div>
-)
-```
-
-
-### Inside views
-
-Under the hood webpack uses
-[extract-text-webpack-plugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) plugin to extract all the referenced styles within your app and compile it into
-a separate `[pack_name].css` bundle so that in your view you can use the
-`stylesheet_pack_tag` helper,
-
-```erb
-<%= stylesheet_pack_tag 'hello_react' %>
-```
-
-You can also link js/images/styles used within your js app in views using
-`asset_pack_path` helper. This helper is useful in cases where you just want to
-create a `<link rel="prefetch">` or `<img />` for an asset.
-
-```erb
-<%= asset_pack_path 'hello_react.css' %>
-<% # => "/packs/hello_react.css" %>
-
-<img src="<%= asset_pack_path 'calendar.png' %>" />
-<% # => <img src="/packs/calendar.png" /> %>
-```
-
-
-### From node modules folder
-
-You can also import styles from `node_modules` using the following syntax.
-Please note that your styles will always be extracted into `[pack_name].css`:
-
-```sass
-// app/javascript/app-styles.sass
-// ~ to tell webpack that this is not a relative import:
-
-@import '~@material/animation/mdc-animation.scss'
-@import '~boostrap/dist/bootstrap.css'
-```
-
-```js
-// Your main app pack
-// app/javascript/packs/app.js
-
-import '../app-styles'
-```
-
-```erb
-<%# In your views %>
-
-<%= javascript_pack_tag 'app' %>
-<%= stylesheet_pack_tag 'app' %>
-```
-
-
-## How-tos
-
-
-### App structure
-
-Let's say you're building a calendar app. Your JS app structure could look like this:
-
-```js
-// app/javascript/packs/calendar.js
-
-import 'calendar'
-```
-
-```
-app/javascript/calendar/index.js // gets loaded by import 'calendar'
-app/javascript/calendar/components/grid.jsx
-app/javascript/calendar/styles/grid.sass
-app/javascript/calendar/models/month.js
-```
-
-```erb
-<%# app/views/layouts/application.html.erb %>
-
-<%= javascript_pack_tag 'calendar' %>
-<%= stylesheet_pack_tag 'calendar' %>
-```
-
-But it could also look a million other ways.
-
-
-#### Namespacing
-
-You can also namespace your packs using directories similar to a Rails app.
-
-```
-app/javascript/packs/admin/orders.js
-app/javascript/packs/shop/orders.js
-```
-
-and reference them in your views like this:
-
-```erb
-<%# app/views/admin/orders/index.html.erb %>
-
-<%= javascript_pack_tag 'admin/orders' %>
-```
-
-and
-
-```erb
-<%# app/views/shop/orders/index.html.erb %>
-
-<%= javascript_pack_tag 'shop/orders' %>
-```
-
-
-### Pass data from view
-
-
-#### React
-
-You may consider using [react-rails](https://github.com/reactjs/react-rails) or
-[webpacker-react](https://github.com/renchap/webpacker-react) for more advanced react integration. However here is how you can do it yourself:
-
-```erb
-<%# views/layouts/application.html.erb %>
-
-<%= content_tag :div,
-  id: "hello-react",
-  data: {
-    message: 'Hello!',
-    name: 'David'
-}.to_json do %>
-<% end %>
-```
-
-```js
-// app/javascript/packs/hello_react.js
-
-const Hello = props => (
-  <div className='react-app-wrapper'>
-    <img src={clockIcon} alt="clock" />
-    <h5 className='hello-react'>
-      {props.message} {props.name}!
-    </h5>
-  </div>
-)
-
-// Render component with data
-document.addEventListener('DOMContentLoaded', () => {
-  const node = document.getElementById('hello-react')
-  const data = JSON.parse(node.getAttribute('data'))
-
-  ReactDOM.render(<Hello {...data} />, node)
-})
+    host: localhost
+    port: 3035
 ```
 
+If you have `hmr` turned to true, then the `stylesheet_pack_tag` generates no output, as you will want to configure your styles to be inlined in your JavaScript for hot reloading. During production and testing, the `stylesheet_pack_tag` will create the appropriate HTML tags.
 
-#### Vue
 
-```erb
-<%= content_tag :div,
-  id: "hello-vue",
-  data: {
-    message: "Hello!",
-    name: "David"
-} do %>
-<% end %>
-```
-
-```html
-<div id="hello-vue" data-name="David" data-message="Hello!"></div>
-```
-
-```js
-// Render component with data
-
-document.addEventListener('DOMContentLoaded', () => {
-  const node = document.getElementById('hello-vue')
-  const data = JSON.parse(node.getAttribute('data'))
-
-  const app = new Vue({
-    data: data,
-    el: '#vue-app',
-    template: '<App/>',
-    components: { App }
-  })
-
-  console.log(app)
-})
-```
-
-You can follow same steps for Angular too.
-
-
-### Add common chunks
-
-The CommonsChunkPlugin is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in the cache for later use. This results in page speed optimizations as the browser can quickly serve the shared code from the cache, rather than being forced to load a larger bundle whenever a new page is visited.
-
-Create a `app-config.js` file inside `config/webpack` and in that file add:
-
-```js
-  module.exports = {
-    plugins: [
-      // Creates a common vendor.js with all shared modules
-      new webpack.optimize.CommonsChunkPlugin({
-        name: 'vendor',
-        minChunks: (module) => {
-          // this assumes your vendor imports exist in the node_modules directory
-          return module.context && module.context.indexOf('node_modules') !== -1;
-        }
-      }),
-      // Webpack code chunk - manifest.js
-      new webpack.optimize.CommonsChunkPlugin({
-        name: 'manifest',
-        minChunks: Infinity
-      })
-    ]
-  }
-```
-
-You can add this in `shared.js` too but we are doing this to ensure smoother upgrades.
-
-```js
-// config/webpack/shared.js
-// .... rest of the config
-
-const appConfig = require('./app-config.js')
-
-plugins: appConfig.plugins.concat([
-
-  // ...existing plugins
-
-])
-```
-
-Now, add these files to your `layouts/application.html.erb`:
-
-```erb
-<%= # Head %>
-
-<%= javascript_pack_tag 'manifest' %>
-<%= javascript_pack_tag 'vendor' %>
-
-<%= # If importing any styles from node_modules in your JS app %>
-
-<%= stylesheet_pack_tag 'vendor' %>
-```
-
-
-### Module import() vs require()
-
-While you are free to use `require()` and `module.exports`, we encourage you
-to use `import` and `export` instead since it reads and looks much better.
-
-```js
-import Button from 'react-bootstrap/lib/Button'
-
-// or
-import { Button } from 'react-bootstrap'
-
-class Foo {
-  // code...
-}
-
-export default Foo
-import Foo from './foo'
-```
-
-You can also use named export and import
-
-```js
-export const foo = () => console.log('hello world')
-import { foo } from './foo'
-```
-
-
-### Add a new npm module
+### Resolved
 
-To add any new JS module you can use `yarn`:
-
-```bash
-yarn add bootstrap material-ui
-```
-
-
-### Add bootstrap
-
-You can use yarn to add bootstrap or any other modules available on npm:
-
-```bash
-yarn add bootstrap
-```
-
-Import Bootstrap and theme(optional) CSS in your app/javascript/packs/app.js file:
-
-```js
-import 'bootstrap/dist/css/bootstrap.css'
-import 'bootstrap/dist/css/bootstrap-theme.css'
-```
-
-Or in your app/javascript/app.sass file:
-
-```sass
-// ~ to tell that this is not a relative import
-
-@import '~bootstrap/dist/css/bootstrap.css'
-@import '~bootstrap/dist/css/bootstrap-theme.css'
-```
-
-
-### Use Typescript with React
-
-1. Setup react using webpacker [react installer](#react). Then add required depedencies
-for using typescript with React:
-
-```bash
-yarn add ts-loader typescript @types/react @types/react-dom
-
-# You don't need this with typescript
-yarn remove prop-types
-```
-
-2. Add a `tsconfig.json` to project root:
-
-``` json
-{
-  "compilerOptions": {
-    "declaration": false,
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "lib": ["es6", "dom"],
-    "module": "es6",
-    "moduleResolution": "node",
-    "sourceMap": true,
-    "jsx": "react",
-    "target": "es5"
-  },
-  "exclude": [
-    "**/*.spec.ts",
-    "node_modules",
-    "public"
-  ],
-  "compileOnSave": false
-}
-```
-
-3. Add a new loader `config/webpack/loaders/typescript.js`:
-
-``` js
-module.exports = {
-  test: /.(ts|tsx)$/,
-  loader: 'ts-loader'
-}
-```
-
-4. Finally add `.tsx` to the list of extensions in `config/webpacker.yml`
-and rename your generated `hello_react.js` using react installer
-to `hello_react.tsx` and make it valid typescript and now you can use
-typescript, JSX with React.
-
-
-### Use HTML templates with Typescript and Angular
-
-After you have installed angular using [angular installer](#angular-with-typescript)
-you would need to follow these steps to add HTML templates support:
-
-1. Use `yarn` to add html-loader
-
-```bash
-yarn add html-loader
-```
-
-2. Add html-loader to `config/webpacker/loaders/html.js`
-
-```js
-module.exports = {
-  test: /\.html$/,
-  use: [{
-    loader: 'html-loader',
-    options: {
-      minimize: true,
-      removeAttributeQuotes: false,
-      caseSensitive: true,
-      customAttrSurround: [ [/#/, /(?:)/], [/\*/, /(?:)/], [/\[?\(?/, /(?:)/] ],
-      customAttrAssign: [ /\)?\]?=/ ]
-    }
-  }]
-}
-```
-
-3. Add `.html` to extensions list
+If you are adding webpacker to an existing app that has most of the assets inside
+`app/assets` or inside an engine and you want to share that
+with webpack modules then you can use `resolved_paths`
+option available in `config/webpacker.yml`, which lets you
+add additional paths webpack should lookup when resolving modules:
 
 ```yml
-  extensions:
-    - .elm
-    - .coffee
-    - .html
+resolved_paths: ['app/assets']
 ```
 
-4. Setup a custom `d.ts` definition
-
-```ts
-// app/javascript/hello_angular/html.d.ts
-
-declare module "*.html" {
-  const content: string
-  export default content
-}
-```
-
-5. Add a template.html file relative to `app.component.ts`
-
-```html
-<h1>Hello {{name}}</h1>
-```
-
-6. Import template into `app.component.ts`
-
-```ts
-import { Component } from '@angular/core'
-import templateString from './template.html'
-
-@Component({
-  selector: 'hello-angular',
-  template: templateString
-})
-
-export class AppComponent {
-  name = 'Angular!'
-}
-```
-
-That's all. Voila!
-
-
-### CSS modules
-
-To enable CSS modules, you would need to update `config/webpack/loaders/sass.js`
-file, particularly `css-loader`:
-
-```js
-// Add css-modules
-
-{
-  loader: 'css-loader',
-  options: {
-    minimize: env.NODE_ENV === 'production',
-    modules: true,
-    localIdentName: '[path][name]__[local]--[hash:base64:5]'
-  }
-}
-```
-
-That's all. Now, you can use CSS modules within your JS app:
-
-```js
-import React from 'react'
-import styles from './styles.css'
-
-const Hello = props => (
-  <div className={styles.wrapper}>
-    <img src={clockIcon} alt="clock" className={styles.img} />
-    <h5 lassName={styles.name}>
-      {props.message} {props.name}!
-    </h5>
-  </div>
-)
-```
-
-
-### CSS-Next
-
-If you want to use [css-next](http://cssnext.io/) inside your app, add postcss
-plugin for `css-next`
-
-```bash
-yarn add postcss-cssnext
-```
-
-and update your `.postcssrc.yml`
-
-```
-plugins:
-  postcss-smart-import: {}
-  cssnext: {}
-```
-
-That's all. Now, you can use latest css features, today.
-
-
-### Ignoring swap files
-
-If you are using vim or emacs and want to ignore certain files you can add `ignore-loader`:
-
-```
-yard add ignore-loader
-```
-
-and create a new loader file inside `config/webpack/loaders`:
-
-```js
-// config/webpack/loaders/ignores.js
-// ignores vue~ swap files
-
-module.exports = {
-  test: /.vue~$/,
-  loader: 'ignore-loader'
-}
-```
-
-And now all files with `.vue~` will be ignored by the webpack compiler.
-
-
-### Link sprocket assets
-
-
-#### Using helpers
-
-It's possible to link to assets that have been precompiled by sprockets. Add the `.erb` extension to your javascript file, then you can use Sprockets' asset helpers:
-
-```erb
-<%# app/javascript/my_pack/example.js.erb %>
-
-<% helpers = ActionController::Base.helpers %>
-var railsImagePath = "<%= helpers.image_path('rails.png') %>"
-```
-
-This is enabled by the `rails-erb-loader` loader rule in `config/loaders/erb.js`.
-
-
-#### Using babel module resolver
-
-You can also use [babel-plugin-module-resolver](https://github.com/tleunen/babel-plugin-module-resolver) to reference assets directly from `app/assets/**`
-
-```bash
-yarn add babel-plugin-module-resolver
-```
-
-Specify the plugin in your `.babelrc` with the custom root or alias. Here's an example:
-
-```json
-{
-  "plugins": [
-    ["module-resolver", {
-      "root": ["./app"],
-      "alias": {
-        "assets": "./assets"
-      }
-    }]
-  ]
-}
-```
-
-And then within your javascript app code:
+You can then import them inside your modules like so:
 
 ```js
-// Note: we don't have do any ../../ jazz
-
-import FooImage from 'assets/images/foo-image.png'
-import 'assets/stylesheets/bar.sass'
-```
-
-## Extending
-
-We suggest you don't directly overwrite the provided configuration files
-and extend instead for smoother upgrades. Here is one way to do it:
-
-Create a `app-config.js` file inside `config/webpack`, and in that add:
-
-```js
-module.exports = {
-  production: {
-    plugins: [
-      // ... Add plugins
-    ]
-  },
-
-  development: {
-    output: {
-      // ... Custom output path
-    }
-  }
-}
+// Note it's relative to parent directory i.e. app/assets
+import 'stylesheets/main'
+import 'images/rails.png'
 ```
 
-```js
-// config/webpack/production.js
+**Note:** Please be careful when adding paths here otherwise it
+will make the compilation slow, consider adding specific paths instead of
+whole parent directory if you just need to reference one or two modules
 
-const { plugins } = require('./app-config.js')
 
-plugins: appConfig.plugins.concat([
+### Watched
 
-  // ...existing plugins
+By default, the lazy compilation is cached until a file is changed under
+tracked paths. You can configure the paths tracked
+by adding new paths to `watched_paths` array, much like rails `autoload_paths`:
 
-])
+```rb
+# config/initializers/webpacker.rb
+# or config/application.rb
+Webpacker::Compiler.watched_paths << 'bower_components'
 ```
 
-But this could be done million other ways.
-
 
 ## Deployment
 
 Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`. If you are not using sprockets you
-can manually trigger `bundle exec rails webpacker:compile` during your app deploy.
-
-The `javascript_pack_tag` and `stylesheet_pack_tag` helper method will automatically insert the correct HTML tag for compiled pack. Just like the asset pipeline does it.
-
-By default the output will look like this in different environments:
-
-```html
-  <!-- In development mode with webpack-dev-server -->
-  <script src="http://localhost:8080/calendar.js"></script>
-  <link rel="stylesheet" media="screen" href="http://localhost:8080/calendar.css">
-  <!-- In development mode -->
-  <script src="/packs/calendar.js"></script>
-  <link rel="stylesheet" media="screen" href="/packs/calendar.css">
-  <!-- In production mode -->
-  <script src="/packs/calendar-0bd141f6d9360cf4a7f5.js"></script>
-  <link rel="stylesheet" media="screen" href="/packs/calendar-dc02976b5f94b507e3b6.css">
-```
-
-
-### Heroku
-
-Heroku installs yarn and node by default if you deploy a rails app with
-Webpacker so all you would need to do:
-
-```bash
-heroku create shiny-webpacker-app
-heroku addons:create heroku-postgresql:hobby-dev
-git push heroku master
-```
-
-
-## Testing
-
-Webpacker lazily compiles assets in test env so you can write your tests without any extra
-setup and everything will just work out of the box.
-
-Here is a sample system test case with hello_react example component:
-
-```js
-// Example react component
-
-import React from 'react'
-import ReactDOM from 'react-dom'
-import PropTypes from 'prop-types'
-
-const Hello = props => (
-  <div>Hello David</div>
-)
-
-document.addEventListener('DOMContentLoaded', () => {
-  ReactDOM.render(
-    <Hello />,
-    document.body.appendChild(document.createElement('div')),
-  )
-})
-```
-
-```erb
-# views/pages/home.html.erb
-
-<%= javascript_pack_tag "hello_react" %>
-```
-
-```rb
-# Tests example react component
-require "application_system_test_case"
-class HomesTest < ApplicationSystemTestCase
-  test "can see the hello message" do
-    visit root_url
-    assert_selector "h5", text: "Hello! David"
-  end
-end
-```
-
-
-## Troubleshooting
-
-*  If you get this error `ENOENT: no such file or directory - node-sass` on Heroku
-or elsewhere during `assets:precompile` or `bundle exec rails webpacker:compile`
-then you would need to rebuild node-sass. It's a bit weird error,
-basically, it can't find the `node-sass` binary.
-An easy solution is to create a postinstall hook - `npm rebuild node-sass` in
-`package.json` and that will ensure `node-sass` is rebuild whenever
-you install any new modules.
-
-* If you get this error `Can't find hello_react.js in manifest.json`
-when loading a view in the browser it's because Webpack is still compiling packs.
-Webpacker uses a `manifest.json` file to keep track of packs in all environments,
-however since this file is generated after packs are compiled by webpack. So,
-if you load a view in browser whilst webpack is compiling you will get this error.
-Therefore, make sure webpack
-(i.e `./bin/webpack-dev-server`) is running and has
-completed the compilation successfully before loading a view.
+can manually trigger `NODE_ENV=production bundle exec rails webpacker:compile`
+during your app deploy.
 
 
-## Wishlist
+## Docs
 
-- HMR - [#188](https://github.com/rails/webpacker/issues/188)
-- Support rails engines - [#348](https://github.com/rails/webpacker/issues/348)
+You can find more detailed guides under [docs](./docs).
 
 
 ## License