webpacker 4.0.2 → 5.4.3

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
@@ -83,3 +113,18 @@ Make sure you have `public/packs` and `node_modules` in `:linked_dirs`
 append :linked_dirs, "log", "tmp/pids", "tmp/cache", "tmp/sockets", "public/packs", ".bundle", "node_modules"
 ```
 
+If you have `node_modules` added to `:linked_dirs` you'll need to run yarn install before `deploy:assets:precompile`, so you can add this code snippet at the bottom deploy.rb
+
+```ruby
+before "deploy:assets:precompile", "deploy:yarn_install"
+namespace :deploy do
+  desc "Run rake yarn install"
+  task :yarn_install do
+    on roles(:web) do
+      within release_path do
+        execute("cd #{release_path} && yarn install --silent --no-progress --no-audit --no-optional")
+      end
+    end
+  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.
 
@@ -21,6 +21,8 @@ There is no built-in tasks to install Webpacker within the engine, thus you have
 
 ## Step 3: configure Webpacker instance.
 
+- File `lib/my_engine.rb`
+
 ```ruby
 module MyEngine
   ROOT_PATH = Pathname.new(File.join(__dir__, ".."))
@@ -38,6 +40,8 @@ end
 
 ## Step 4: Configure dev server proxy.
 
+- File `lib/my_engine/engine.rb`
+
 ```ruby
 module MyEngine
   class Engine < ::Rails::Engine
@@ -73,6 +77,8 @@ development:
 
 ## Step 5: configure helper.
 
+- File `app/helpers/my_engine/application_helper.rb`
+
 ```ruby
 require "webpacker/helper"
 
@@ -93,7 +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 `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"
@@ -106,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.
@@ -147,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/env.md

@@ -49,8 +49,6 @@ dotenvFiles.forEach((dotenvFile) => {
   dotenv.config({ path: dotenvFile, silent: true })
 })
 
-environment.plugins.prepend('Environment', new webpack.EnvironmentPlugin(JSON.parse(JSON.stringify(process.env))))
-
 module.exports = environment
 ```
 

data/docs/es6.md

@@ -1,6 +1,5 @@
 # ES6
 
-
 ## Babel
 
 Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so
@@ -16,15 +15,35 @@ Following ES6/7 features are supported out of the box:
 * 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.
+We have also included [core-js](https://github.com/zloirock/core-js) to polyfill features in the
+older browsers.
 
-Don't forget to import `@babel/polyfill` in your main entry point like so:
+Don't forget to add these lines into your main entry point:
 
 ```js
-import "@babel/polyfill"
+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](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.

data/docs/target.md

@@ -0,0 +1,22 @@
+# Target browsers
+
+By default webpacker provides these front-end tools:
+- [@babel/preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env)
+- [Autoprefixer](https://github.com/postcss/autoprefixer)
+- [postcss-preset-env](https://github.com/csstools/postcss-preset-env)
+
+All these tools use [Browserslist](https://github.com/browserslist/browserslist) to detect which environment your users have
+
+Webpacker browserslist default target:
+```
+defaults
+```
+
+`defaults`: `(> 0.5%, last 2 versions, Firefox ESR, not dead)`, [browserl.ist](https://browserl.ist/) is an online tool to check what browsers will be selected by some query.
+
+To keep browsers data up to date, you need to run:
+```bash
+yarn upgrade caniuse-lite
+```
+
+at least once every few months, to prevent such [problems](https://github.com/browserslist/browserslist/issues/492)

data/docs/testing.md

@@ -10,8 +10,7 @@ Webpacker does not setup `Karma` by default, so you've to manually install it al
   "test": "NODE_ENV=test karma start"
 },
 "dependencies": {
-  "typescript": "^2.5.2",
-  "ts-loader": "^2.3.7"
+  "typescript": "^2.5.2"
 },
 "devDependencies": {
   "karma": "^1.7.1",
@@ -33,7 +32,7 @@ It is beneficial to use the same webpack configuration file (generated by webpac
 ```js
 // config/webpack/test.js
 const environment = require('./environment')
-environment.plugins.get('Manifest').opts.writeToFileEmit = process.env.NODE_ENV !== 'test'
+environment.plugins.get('Manifest').options.writeToFileEmit = process.env.NODE_ENV !== 'test'
 environment.loaders.append('istanbul-instrumenter', {
   test: /\.ts$/,
   enforce: "post",