webpacker 4.0.7 → 5.0.0

data/docs/css.md

@@ -3,6 +3,18 @@
 
 Webpacker supports importing CSS, Sass and SCSS files directly into your JavaScript files.
 
+Importing and loading styles is a two step process:
+
+1. You need to tell webpack which file(s) it has to compile and know how to load
+  
+   When you do `import '../scss/application.scss'`, you're telling webpack to include `application.scss` in the build. This does not mean it's going to be compiled into your javascript, only that webpack now compiles and knows how to load this file. (How that file compilation is handled is depending on how your loaders (`css-loader`, `sass-loader`, `file-loader`, etc.) are configured.)
+
+2. You need to load those files in your views
+
+   In order to have styles load in production, you need to include `stylesheet_pack_tag` with the same name as the javascript file that imports the styles.
+
+   When you do `<%= stylesheet_pack_tag 'application' %>`, that's a run-time inclusion from Rails, where Rails gets the correct "asset path" to that file from webpack.
+
 
 ## Import global styles into your JS app
 
@@ -201,11 +213,10 @@ const { environment } = require('@rails/webpacker')
 
 // resolve-url-loader must be used before sass-loader
 environment.loaders.get('sass').use.splice(-1, 0, {
-  loader: 'resolve-url-loader',
-  options: {
-    attempts: 1
-  }
+  loader: 'resolve-url-loader'
 });
+
+module.exports = environment
 ```
 
 ## Working with TypeScript

data/docs/deployment.md

@@ -1,7 +1,7 @@
 # Deployment
 
 
-Webpacker hooks up a new `webpacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`. 
+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 `webpacker:compile` is automatically aliased to `assets:precompile`. Remember to set NODE_ENV environment variable to production during deployment or when running the rake task.
 
 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.
@@ -13,37 +13,46 @@ By default the output will look like this in different environments:
   <script src="http://localhost:8080/calendar-0bd141f6d9360cf4a7f5.js"></script>
   <link rel="stylesheet" media="screen" href="http://localhost:8080/calendar-dc02976b5f94b507e3b6.css">
   <!-- In production or development mode -->
-  <script src="/packs/calendar-0bd141f6d9360cf4a7f5.js"></script>
-  <link rel="stylesheet" media="screen" href="/packs/calendar-dc02976b5f94b507e3b6.css">
+  <script src="/packs/js/calendar-0bd141f6d9360cf4a7f5.js"></script>
+  <link rel="stylesheet" media="screen" href="/packs/css/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:
+In order for your Webpacker app to run on Heroku, you'll need to do a bit of configuration before hand.
 
-```bash
-heroku create shiny-webpacker-app
+```
+heroku create my-webpacker-heroku-app
 heroku addons:create heroku-postgresql:hobby-dev
+heroku buildpacks:add heroku/nodejs
+heroku buildpacks:add heroku/ruby
 git push heroku master
 ```
 
+We're essentially doing the following here:
+
+* Creating an app on Heroku
+* Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
+* Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
+* Pushing our code to Heroku and kicking off the deployment
+
 
 ## Nginx
 
 Webpacker doesn't serve anything in production. You’re expected to configure your web server to serve files in public/ directly.
 
-Some servers support sending precompressed versions of files with the `.gz` extension when they're available. For example, nginx offers a `gzip_static` directive.
+Some servers support sending precompressed versions of files when they're available. For example, nginx offers a `gzip_static` directive that serves files with the `.gz` extension to supported clients. With an optional module, nginx can also serve Brotli compressed files with the `.br` extension (see below for installation and configuration instructions).
 
 Here's a sample nginx site config for a Rails app using Webpacker:
 
 ```nginx
 upstream app {
-  # ...
+  # server unix:///path/to/app/tmp/puma.sock;
 }
 
 server {
+  listen 80;
   server_name www.example.com;
   root /path/to/app/public;
 
@@ -61,13 +70,34 @@ server {
     try_files $uri @app;
   }
 
-  location ^~ /packs/ {
+  location = /favicon.ico { access_log off; log_not_found off; }
+  location = /robots.txt  { access_log off; log_not_found off; }
+
+  location ~ /\.(?!well-known).* {
+    deny all;
+  }
+
+  location ~ ^/(assets|packs)/ {
     gzip_static on;
+    brotli_static on; # Optional, see below
     expires max;
+    add_header Cache-Control public;
   }
 }
 ```
 
+### Installing the ngx_brotli module
+
+If you want to serve Brotli compressed files with nginx, you will need to install the `nginx_brotli` module. Installation instructions from source can be found in the official [google/ngx_brotli](https://github.com/google/ngx_brotli) git repository. Alternatively, depending on your platform, the module might be available via a pre-compiled package.
+
+Once installed, you need to load the module. As we want to serve the pre-compressed files, we only need the static module. Add the following line to your `nginx.conf` file and reload nginx:
+
+```
+load_module modules/ngx_http_brotli_static_module.so;
+```
+
+Now, you can set `brotli_static on;` in your nginx site config, as per the config in the last section above.
+
 ## 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
@@ -98,4 +128,3 @@ namespace :deploy do
   end
 end
 ```
-

data/docs/docker.md

@@ -1,6 +1,6 @@
 # Docker
 
-To setup webpacker with a dockerized Rails application is trivial.
+To setup webpacker with a dockerized Rails application.
 
 First, add a new service for webpacker in docker-compose.yml:
 
@@ -9,8 +9,10 @@ version: '3'
 services:
   webpacker:
     build: .
-    env_file:
-      - '.env.docker'
+    environment:
+      - NODE_ENV=development
+      - RAILS_ENV=development
+      - WEBPACKER_DEV_SERVER_HOST=0.0.0.0
     command: ./bin/webpack-dev-server
     volumes:
       - .:/webpacker-example-app
@@ -22,24 +24,41 @@ add nodejs and yarn as dependencies in Dockerfile,
 
 ```dockerfile
 FROM ruby:2.4.1
-RUN apt-get update -qq
 
-RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
-RUN curl -sL https://deb.nodesource.com/setup_8.x | bash
-RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
+RUN apt-get update -qq && apt-get install -y build-essential nodejs \
+ && rm -rf /var/lib/apt/lists/* \
+ && curl -o- -L https://yarnpkg.com/install.sh | bash
 
-RUN apt-get install -y nodejs
-RUN apt-get update && apt-get install -y yarn
+# Rest of the commands....
+```
+
+Please note: if using `assets:precompile` in the Dockerfile or have issues with the snippet above then try:
+
+```dockerfile
+FROM ruby:2.4.1
+
+RUN curl -sL https://deb.nodesource.com/setup_8.x | bash \
+ && apt-get update && apt-get install -y nodejs && rm -rf /var/lib/apt/lists/* \
+ && curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
+ && echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list \
+ && apt-get update && apt-get install -y yarn && rm -rf /var/lib/apt/lists/*
 
 # Rest of the commands....
 ```
 
-and create an env file to load environment variables from:
+then add the webpacker host name environment variable to the web/app service:
 
-```env
-NODE_ENV=development
-RAILS_ENV=development
-WEBPACKER_DEV_SERVER_HOST=0.0.0.0
+```Dockerfile
+  web:
+    build:
+      context: .
+    command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -p 3000 -b '0.0.0.0'"
+    volumes:
+      - .:/usr/src/app
+    ports:
+      - "3000:3000"
+    environment:
+      - WEBPACKER_DEV_SERVER_HOST=webpacker
 ```
 
 Lastly, rebuild your container:

data/docs/engines.md

@@ -9,7 +9,7 @@ This guide describes how to do that using [Rails engines](https://guides.rubyonr
 
 ## Step 1: create Rails engine.
 
-First, you create a Rails engine (say, `MyEngine`). See the offical [Rails guide](https://guides.rubyonrails.org/engines.html).
+First, you create a Rails engine (say, `MyEngine`). See the official [Rails guide](https://guides.rubyonrails.org/engines.html).
 
 ## Step 2: install Webpacker within the engine.
 
@@ -99,9 +99,18 @@ Now you can use `stylesheet_pack_tag` and `javascript_pack_tag` from within your
 
 Add Rake task to compile assets in production (`rake my_engine:webpacker:compile`)
 
-- File `lib/tasks/my_engine_tasks.rake`
+- File `my_engine_rootlib/tasks/my_engine_tasks.rake`
 
 ```ruby
+def ensure_log_goes_to_stdout
+  old_logger = Webpacker.logger
+  Webpacker.logger = ActiveSupport::Logger.new(STDOUT)
+  yield
+ensure
+  Webpacker.logger = old_logger
+end
+
+
 namespace :my_engine do
   namespace :webpacker do
     desc "Install deps with yarn"
@@ -114,16 +123,44 @@ namespace :my_engine do
     desc "Compile JavaScript packs using webpack for production with digests"
     task compile: [:yarn_install, :environment] do
       Webpacker.with_node_env("production") do
+        ensure_log_goes_to_stdout do
           if MyEngine.webpacker.commands.compile
             # Successful compilation!
           else
             # Failed compilation
             exit!
           end
+        end
       end
     end
   end
 end
+
+def yarn_install_available?
+  rails_major = Rails::VERSION::MAJOR
+  rails_minor = Rails::VERSION::MINOR
+
+  rails_major > 5 || (rails_major == 5 && rails_minor >= 1)
+end
+
+def enhance_assets_precompile
+  # yarn:install was added in Rails 5.1
+  deps = yarn_install_available? ? [] : ["my_engine:webpacker:yarn_install"]
+  Rake::Task["assets:precompile"].enhance(deps) do
+    Rake::Task["my_engine:webpacker:compile"].invoke
+  end
+end
+
+# Compile packs after we've compiled all other assets during precompilation
+skip_webpacker_precompile = %w(no false n f).include?(ENV["WEBPACKER_PRECOMPILE"])
+
+unless skip_webpacker_precompile
+  if Rake::Task.task_defined?("assets:precompile")
+    enhance_assets_precompile
+  else
+    Rake::Task.define_task("assets:precompile" => "my_engine:webpacker:compile")
+  end
+end
 ```
 
 ## Step 7: serving compiled packs.
@@ -155,9 +192,22 @@ To serve static assets from the engine's `public/` folder you must add a middlew
 # application.rb
 
 config.middleware.use(
-  "Rack::Static",
+  Rack::Static,
   urls: ["/my-engine-packs"], root: "my_engine/public"
 )
 ```
+or if you prefer to keep your engine-related configuration within the engine itself
+
+```ruby
+# my-engine-root/lib/my-engine/engine.rb
+module MyEngine
+  class Engine < ::Rails:Engine
+    config.app_middleware.use(
+      Rack::Static,
+      urls: ["/my-engine-packs"], root: "my_engine/public"
+    )
+  end
+end
+```
 
 **NOTE:** in the example above we assume that your `public_output_path` is set to `my-engine-packs` in your engine's `webpacker.yml`.

data/docs/es6.md

@@ -1,6 +1,5 @@
 # ES6
 
-
 ## Babel
 
 Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so
@@ -26,6 +25,25 @@ import "core-js/stable";
 import "regenerator-runtime/runtime";
 ```
 
+## Dynamic/Lazy Chunk Loading
+
+For this section, you need Webpack and Webpacker 4. Then enable `SplitChunks` as it is explained in [docs/webpack](webpack.md).
+
+[Dynamic code splitting](https://webpack.js.org/guides/code-splitting#dynamic-imports) enables you to conditionally request/run only the JS that you need. For example, if your site has a `searchBarComponent` on every page, you can reduce the page overhead by deferring the request for the `searchBarComponent` code until after the page has loaded, until the user has scrolled it into view, or until the user has clicked on an element.
+
+```js
+ function loadSearchBarComponent() {
+   return import(/* webpackChunkName: "searchBarComponent" */ './pathTo/searchBarComponent')
+ }
+```
+
+The comment you see above (`/* webpackChunkName */`) is not arbitrary, it is one of webpacks [magic comments](https://webpack.js.org/api/module-methods/#magic-comments). They can be used to fine-tune `import()` with settings such as `defer` or `prefetch`.
+
+**Warning**: You should not attempt to dynamically load anything from your `packs/` folder. Instead, try to make your `pack` scripts a hub from which you dynamically load `non-pack` scripts.
+
+- [Docs for using magic comments](https://webpack.js.org/api/module-methods/#magic-comments)
+- [Docs for configuring `splitChunks` in webpacker](https://github.com/rails/webpacker/blob/master/docs/webpack.md#add-splitchunks-webpack-v4).
+- [Docs for using dynamic `import()`](https://webpack.js.org/guides/code-splitting#dynamic-imports).
 
 ## Module import vs require()
 

data/docs/integrations.md

@@ -0,0 +1,220 @@
+# 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
+
+To use Webpacker with [React](https://facebook.github.io/react/), create a
+new Rails 5.1+ app using `--webpack=react` option:
+
+```bash
+# Rails 5.1+
+rails new myapp --webpack=react
+```
+
+(or run `bundle exec rails webpacker:install:react` in an existing Rails app already
+setup with Webpacker).
+
+The installer will add all relevant dependencies using Yarn, changes
+to the configuration files, and an example React component to your
+project in `app/javascript/packs` so that you can experiment with React right away.
+
+
+## Angular with TypeScript
+
+To use Webpacker with [Angular](https://angular.io/), create a
+new Rails 5.1+ app using `--webpack=angular` option:
+
+```bash
+# Rails 5.1+
+rails new myapp --webpack=angular
+```
+
+(or run `bundle exec rails webpacker:install:angular` on a Rails app already
+setup with Webpacker).
+
+The installer will add the TypeScript and Angular core libraries using Yarn alongside
+a few changes to the configuration files. An example component written in
+TypeScript will also be added to your project in `app/javascript` so that
+you can experiment with Angular right away.
+
+By default, Angular uses a JIT compiler for development environment. This
+compiler is not compatible with restrictive CSP (Content Security
+Policy) environments like Rails 5.2+. You can use Angular AOT compiler
+in development with the [@ngtools/webpack](https://www.npmjs.com/package/@ngtools/webpack#usage) plugin.
+
+Alternatively if you're using Rails 5.2+ you can enable `unsafe-eval` rule for your
+development environment. This can be done in the `config/initializers/content_security_policy.rb`
+with the following code:
+
+```ruby
+Rails.application.config.content_security_policy do |policy|
+  if Rails.env.development?
+    policy.script_src :self, :https, :unsafe_eval
+  else
+    policy.script_src :self, :https
+  end
+end
+```
+
+
+## Vue
+
+To use Webpacker with [Vue](https://vuejs.org/), create a
+new Rails 5.1+ app using `--webpack=vue` option:
+
+```bash
+# Rails 5.1+
+rails new myapp --webpack=vue
+```
+(or run `bundle exec rails webpacker:install:vue` on a Rails app already setup with Webpacker).
+
+The installer will add Vue and its required libraries using Yarn alongside
+automatically applying changes needed to the configuration files. An example component will
+be added to your project in `app/javascript` so that you can experiment with Vue right away.
+
+If you're using Rails 5.2+ you'll need to enable `unsafe-eval` rule for your development environment.
+This can be done in the `config/initializers/content_security_policy.rb` with the following
+configuration:
+
+```ruby
+Rails.application.config.content_security_policy do |policy|
+  if Rails.env.development?
+    policy.script_src :self, :https, :unsafe_eval
+  else
+    policy.script_src :self, :https
+  end
+end
+```
+You can read more about this in the [Vue docs](https://vuejs.org/v2/guide/installation.html#CSP-environments).
+
+### Lazy loading integration
+
+See [docs/es6](docs/es6.md) to know more about Webpack and Webpacker configuration.
+
+For instance, you can lazy load Vue JS components:
+
+Before:
+```js
+import Vue from 'vue'
+import { VCard } from 'vuetify/lib'
+
+Vue.component('VCard', VCard)
+```
+
+After:
+```js
+import Vue from 'vue'
+
+// With destructuring assignment
+Vue.component('VCard', import('vuetify/lib').then(({ VCard }) => VCard)
+
+// Or without destructuring assignment
+Vue.component('OtherComponent', () => import('./OtherComponent'))
+```
+
+You can use it in a Single File Component as well:
+
+```html
+<template>
+  ...
+</template>
+
+<script>
+export default {
+  components: {
+    OtherComponent: () => import('./OtherComponent')
+  }
+}
+</script>
+```
+
+By wrapping the import function into an arrow function, Vue will execute it only when it gets requested, loading the module in that moment.
+
+##### Automatic registration
+
+```js
+/**
+ * The following block of code may be used to automatically register your
+ * Vue components. It will recursively scan this directory for the Vue
+ * components and automatically register them with their "basename".
+ *
+ * Eg. ./components/OtherComponent.vue -> <other-component></other-component>
+ * Eg. ./UI/ButtonComponent.vue -> <button-component></button-component>
+ */
+
+const files = require.context('./', true, /\.vue$/i)
+files.keys().map(key => {
+  const component = key.split('/').pop().split('.')[0]
+
+  // With Lazy Loading
+  Vue.component(component, () => import(`${key}`))
+
+  // Or without Lazy Loading
+  Vue.component(component, files(key).default)
+})
+```
+
+## Elm
+
+To use Webpacker with [Elm](http://elm-lang.org), create a
+new Rails 5.1+ app using `--webpack=elm` option:
+
+```
+# Rails 5.1+
+rails new myapp --webpack=elm
+```
+
+(or run `bundle exec rails webpacker:install:elm` on a Rails app already setup with Webpacker).
+
+The Elm library and its core packages will be added via Yarn and Elm.
+An example `Main.elm` app will also be added to your project in `app/javascript`
+so that you can experiment with Elm right away.
+
+## Svelte
+
+To use Webpacker with [Svelte](https://svelte.dev), create a
+new Rails 5.1+ app using `--webpack=svelte` option:
+
+```
+# Rails 5.1+
+rails new myapp --webpack=svelte
+```
+
+(or run `bundle exec rails webpacker:install:svelte` on a Rails app already setup with Webpacker).
+
+Please play with the [Svelte Tutorial](https://svelte.dev/tutorial/basics) or learn more about its API at https://svelte.dev/docs
+
+## Stimulus
+
+To use Webpacker with [Stimulus](http://stimulusjs.org), create a
+new Rails 5.1+ app using `--webpack=stimulus` option:
+
+```
+# Rails 5.1+
+rails new myapp --webpack=stimulus
+```
+
+(or run `bundle exec rails webpacker:install:stimulus` on a Rails app already setup with Webpacker).
+
+Please read [The Stimulus Handbook](https://stimulusjs.org/handbook/introduction) or learn more about its source code at https://github.com/stimulusjs/stimulus
+
+## CoffeeScript
+
+To add [CoffeeScript](http://coffeescript.org/) support,
+run `bundle exec rails webpacker:install:coffee` on a Rails app already
+setup with Webpacker.
+
+An example `hello_coffee.coffee` file will also be added to your project
+in `app/javascript/packs` so that you can experiment with CoffeeScript right away.
+
+## Erb
+
+To add [Erb](https://apidock.com/ruby/ERB) support in your JS templates,
+run `bundle exec rails webpacker:install:erb` on a Rails app already
+setup with Webpacker.
+
+An example `hello_erb.js.erb` file will also be added to your project
+in `app/javascript/packs` so that you can experiment with Erb-flavoured
+javascript right away.