webpacker 2.0 → 3.0.0

data/docs/testing.md

@@ -0,0 +1,45 @@
+# Testing
+
+
+## Lazy compilation
+
+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
+```

data/docs/troubleshooting.md

@@ -0,0 +1,65 @@
+# Troubleshooting
+
+
+## ENOENT: no such file or directory - node-sass
+
+*  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 of a 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 rebuilt whenever
+you install any new modules.
+
+
+## Can't find hello_react.js in manifest.json
+
+* 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.
+
+
+## throw er; // Unhandled 'error' event
+
+* If you get this error while trying to use Elm, try rebuilding Elm. You can do
+  so with a postinstall hook in your `package.json`:
+
+```
+"scripts": {
+  "postinstall": "npm rebuild elm"
+}
+```
+
+
+## webpack or webpack-dev-server not found
+
+* This could happen if  `webpacker:install` step is skipped. Please run `bundle exec rails webpacker:install` to fix the issue.
+
+* If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
+
+```bash
+bundle config --delete bin
+./bin/rails app:update:bin # or rails app:update:bin
+```
+
+
+## Running Webpack on Windows
+
+If you are running Webpack on Windows, your command shell may not be able to interpret the preferred interpreter
+for the scripts generated in `bin/webpack` and `bin/webpack-dev-server`. Instead you'll want to run the scripts
+manually with Ruby:
+
+```
+C:\path>ruby bin\webpack
+C:\path>ruby bin\webpack-dev-server
+```
+
+
+## Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema.
+
+If you receive this error when running `$ ./bin/webpack-dev-server` ensure your configuration is correct; most likely the path to your "packs" folder is incorrect if you modified from the original "source_path" defined in `config/webpacker.yml`.

data/docs/typescript.md

@@ -0,0 +1,115 @@
+# Typescript
+
+
+## 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
+```
+
+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. 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.
+
+
+
+## HTML templates with Typescript and Angular
+
+After you have installed angular using `bundle exec rails webpacker:install:angular`
+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/webpack/environment.js`
+
+```js
+environment.loaders.add('html', {
+  test: /\.html$/,
+  use: [{
+    loader: 'html-loader',
+    options: {
+      minimize: true,
+      removeAttributeQuotes: false,
+      caseSensitive: true,
+      customAttrSurround: [ [/#/, /(?:)/], [/\*/, /(?:)/], [/\[?\(?/, /(?:)/] ],
+      customAttrAssign: [ /\)?\]?=/ ]
+    }
+  }]
+})
+```
+
+3. Add `.html` to `config/webpacker.yml`
+
+```yml
+  extensions:
+    - .elm
+    - .coffee
+    - .html
+```
+
+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!

data/docs/webpack-dev-server.md

@@ -0,0 +1,32 @@
+# Webpack Dev Server
+
+
+## HTTPS
+
+If you're using the `webpack-dev-server` in development, you can serve your packs over HTTPS
+by setting 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/exception upon accessing the page. If you get
+`https://localhost:3035/sockjs-node/info?t=1503127986584 net::ERR_INSECURE_RESPONSE`
+in your console, simply open the link in your browser and accept the SSL exception.
+Now if you refresh your rails view everything should work as expected.
+
+
+## HOT module replacement
+
+Webpacker out-of-the-box supports HMR with `webpack-dev-server` and
+you can toggle it by setting `dev_server/hmr` option inside webpacker.yml.
+
+Checkout this guide for more information:
+
+- https://webpack.js.org/configuration/dev-server/#devserver-hot
+
+To support HMR with React you would need to add `react-hot-loader`. Checkout this guide for
+more information:
+
+- https://gaearon.github.io/react-hot-loader/getstarted/
+
+**Note:** Don't forget to disable `HMR` if you are not running `webpack-dev-server`
+otherwise you will get not found error for stylesheets.

data/docs/webpack.md

@@ -0,0 +1,108 @@
+# Webpack
+
+
+## Configuration
+
+Webpacker gives you a default set of configuration files for test, development and
+production environments in `config/webpack/*.js`. You can configure each individual
+environment in their respective files or configure them all in the base
+`config/webpack/environment.js` file.
+
+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
+
+You can add additional loaders beyond the base set that webpacker provides by
+adding it to your environment. We'll use `json-loader` as an example:
+
+```
+yarn add json-loader
+```
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+environment.loaders.add('json', {
+  test: /\.json$/,
+  use: 'json-loader'
+})
+
+module.exports = environment
+```
+
+Finally add `.json` to the list of extensions in `config/webpacker.yml`. Now if you `import()` any `.json` files inside your javascript
+they will be processed using `json-loader`. Voila!
+
+You can also modify the loaders that webpacker pre-configures for you. We'll update
+the `babel` loader as an example:
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+// Update an option directly
+const babelLoader = environment.loaders.get('babel')
+babelLoader.options.cacheDirectory = false
+
+module.exports = environment
+```
+
+
+## Plugins
+
+The process for adding or modifying webpack plugins is the same as the process
+for loaders above:
+
+```js
+// config/webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+// Get a pre-configured plugin
+environment.plugins.get('ExtractText') // Is an ExtractTextPlugin instance
+
+// Add an additional plugin of your choosing
+environment.plugins.add('Fancy', new MyFancyWebpackPlugin)
+
+module.exports = environment
+```
+
+
+### 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.
+
+Add the plugins in `config/webpack/environment.js`:
+
+```js
+environment.plugins.add('CommonsChunkVendor', 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;
+  }
+}))
+
+environment.plugins.add('CommonsChunkManifest', new webpack.optimize.CommonsChunkPlugin({
+  name: 'manifest',
+  minChunks: Infinity
+}))
+```
+
+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' %>
+```
+
+More detailed guides available here: [Webpack guides](https://webpack.js.org/guides/)

data/docs/yarn.md

@@ -0,0 +1,12 @@
+# Yarn
+
+Webpacker by default uses `yarn` as package manager for node modules
+
+
+## Add a new npm module
+
+To add any new JS module you can use `yarn`:
+
+```bash
+yarn add bootstrap material-ui
+```

data/lib/install/angular.rb

@@ -1,13 +1,10 @@
 require "webpacker/configuration"
 
-puts "Copying angular loader to config/webpack/loaders"
-copy_file "#{__dir__}/config/loaders/installers/angular.js", "config/webpack/loaders/angular.js"
+puts "Copying angular example entry file to #{Webpacker.config.source_entry_path}"
+copy_file "#{__dir__}/examples/angular/hello_angular.js", "#{Webpacker.config.source_entry_path}/hello_angular.js"
 
-puts "Copying angular example entry file to #{Webpacker::Configuration.entry_path}"
-copy_file "#{__dir__}/examples/angular/hello_angular.js", "#{Webpacker::Configuration.entry_path}/hello_angular.js"
-
-puts "Copying hello_angular app to #{Webpacker::Configuration.source_path}"
-directory "#{__dir__}/examples/angular/hello_angular", "#{Webpacker::Configuration.source_path}/hello_angular"
+puts "Copying hello_angular app to #{Webpacker.config.source_path}"
+directory "#{__dir__}/examples/angular/hello_angular", "#{Webpacker.config.source_path}/hello_angular"
 
 puts "Copying tsconfig.json to the Rails root directory for typescript"
 copy_file "#{__dir__}/examples/angular/tsconfig.json", "tsconfig.json"

data/lib/install/bin/webpack-dev-server.tt

@@ -3,6 +3,7 @@ $stdout.sync = true
 
 require "shellwords"
 require "yaml"
+require "socket"
 
 ENV["RAILS_ENV"] ||= "development"
 RAILS_ENV = ENV["RAILS_ENV"]
@@ -13,7 +14,9 @@ NODE_ENV = ENV["NODE_ENV"]
 APP_PATH          = File.expand_path("../", __dir__)
 CONFIG_FILE       = File.join(APP_PATH, "config/webpacker.yml")
 NODE_MODULES_PATH = File.join(APP_PATH, "node_modules")
-WEBPACK_CONFIG    = File.join(APP_PATH, "config/webpack/development.js")
+WEBPACK_CONFIG    = File.join(APP_PATH, "config/webpack/#{NODE_ENV}.js")
+
+LISTEN_HOST_ADDR = NODE_ENV == 'development' ? 'localhost' : '0.0.0.0'
 
 def args(key)
   index = ARGV.index(key)
@@ -21,23 +24,44 @@ def args(key)
 end
 
 begin
-  dev_server = YAML.load_file(CONFIG_FILE)["development"]["dev_server"]
+  dev_server = YAML.load_file(CONFIG_FILE)[RAILS_ENV]["dev_server"]
 
-  DEV_SERVER_HOST = "http#{"s" if args('--https') || dev_server["https"]}://#{args('--host') || dev_server["host"]}:#{args('--port') || dev_server["port"]}"
+  HOSTNAME        = args('--host') || dev_server["host"]
+  PORT            = args('--port') || dev_server["port"]
+  HTTPS           = ARGV.include?('--https') || dev_server["https"]
+  DEV_SERVER_ADDR = "http#{"s" if HTTPS}://#{HOSTNAME}:#{PORT}"
 
 rescue Errno::ENOENT, NoMethodError
-  puts "Webpack dev_server configuration not found in #{CONFIG_FILE}."
-  puts "Please run bundle exec rails webpacker:install to install webpacker"
+  $stdout.puts "Webpack dev_server configuration not found in #{CONFIG_FILE}."
+  $stdout.puts "Please run bundle exec rails webpacker:install to install webpacker"
+  exit!
+end
+
+begin
+  server = TCPServer.new(LISTEN_HOST_ADDR, PORT)
+  server.close
+
+rescue Errno::EADDRINUSE
+  $stdout.puts "Another program is running on port #{PORT}. Set a new port in #{CONFIG_FILE} for dev_server"
   exit!
 end
 
-newenv = {
-  "NODE_PATH" => NODE_MODULES_PATH.shellescape,
-  "ASSET_HOST" => DEV_SERVER_HOST.shellescape
-}.freeze
+# Delete supplied host and port CLI arguments
+["--host", "--port"].each do |arg|
+  ARGV.delete(args(arg))
+  ARGV.delete(arg)
+end
+
+env = { "NODE_PATH" => NODE_MODULES_PATH.shellescape }
 
-cmdline = ["yarn", "run", "webpack-dev-server", "--", "--progress", "--color", "--config", WEBPACK_CONFIG] + ARGV
+cmd = [
+  "#{NODE_MODULES_PATH}/.bin/webpack-dev-server", "--progress", "--color",
+  "--config", WEBPACK_CONFIG,
+  "--host", LISTEN_HOST_ADDR,
+  "--public", "#{HOSTNAME}:#{PORT}",
+  "--port", PORT.to_s
+] + ARGV
 
 Dir.chdir(APP_PATH) do
-  exec newenv, *cmdline
+  exec env, *cmd
 end