webpacker 5.1.1 → 5.2.0

data/README.md

@@ -1,7 +1,7 @@
 # Webpacker
 
 [![Build Status](https://travis-ci.org/rails/webpacker.svg?branch=master)](https://travis-ci.org/rails/webpacker)
-[![node.js](https://img.shields.io/badge/node-%3E%3D%2010.13.0-brightgreen.svg)](https://www.npmjs.com/package/@rails/webpacker)
+[![node.js](https://img.shields.io/badge/node-%3E%3D%2010.17.0-brightgreen.svg)](https://www.npmjs.com/package/@rails/webpacker)
 [![Gem](https://img.shields.io/gem/v/webpacker.svg)](https://rubygems.org/gems/webpacker)
 
 Webpacker makes it easy to use the JavaScript pre-processor and bundler
@@ -35,6 +35,7 @@ in which case you may not even need the asset pipeline. This is mostly relevant
   - [Elm](./docs/integrations.md#elm)
   - [Stimulus](./docs/integrations.md#stimulus)
   - [Svelte](./docs/integrations.md#svelte)
+  - [Typescript](./docs/typescript.md)
   - [CoffeeScript](./docs/integrations.md#coffeescript)
   - [Erb](./docs/integrations.md#erb)
 - [Paths](#paths)
@@ -51,7 +52,7 @@ in which case you may not even need the asset pipeline. This is mostly relevant
 
 - Ruby 2.4+
 - Rails 5.2+
-- Node.js 10.13.0+
+- Node.js 10.17.0+
 - Yarn 1.x+
 
 ## Features
@@ -121,8 +122,11 @@ app/javascript:
   ├── packs:
   │   # only webpack entry files here
   │   └── application.js
-  └── src:
   │   └── application.css
+  └── src:
+  │   └── my_component.js
+  └── stylesheets:
+  │   └── my_styles.css
   └── images:
       └── logo.svg
 ```
@@ -318,7 +322,7 @@ Included install integrations:
 - [Svelte](./docs/integrations.md#Svelte)
 - [Stimulus](./docs/integrations.md#Stimulus)
 - [CoffeeScript](./docs/integrations.md#CoffeeScript)
-- [Typescript](./docs/integrations.md)
+- [Typescript](./docs/typescript.md)
 - [Erb](./docs/integrations.md#Erb)
 
 See [Integrations](./docs/integrations.md) for further details.
@@ -362,12 +366,12 @@ If you have `hmr` turned to true, then the `stylesheet_pack_tag` generates no ou
 
 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, you can use the `resolved_paths`
+with webpack modules, you can use the `additional_paths`
 option available in `config/webpacker.yml`. This lets you
 add additional paths that webpack should lookup when resolving modules:
 
 ```yml
-resolved_paths: ['app/assets']
+additional_paths: ['app/assets']
 ```
 
 You can then import these items inside your modules like so:
@@ -382,18 +386,6 @@ import 'images/rails.png'
 will make the compilation slow, consider adding specific paths instead of
 whole parent directory if you just need to reference one or two modules
 
-### Watched
-
-By default, the lazy compilation is cached until a file is changed under your
-tracked paths. You can configure which paths are tracked
-by adding new paths to `watched_paths` array. This is much like Rails' `autoload_paths`:
-
-```rb
-# config/initializers/webpacker.rb
-# or config/application.rb
-Webpacker::Compiler.watched_paths << 'bower_components'
-```
-
 ## 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, `webpacker:compile` is automatically aliased to `assets:precompile`. Similar to sprockets both rake tasks will compile packs in production mode but will use `RAILS_ENV` to load configuration from `config/webpacker.yml` (if available).
@@ -407,7 +399,7 @@ When compiling assets for production on a remote server, such as a continuous in
   - [Webpack-dev-server](./docs/webpack-dev-server.md)
   - [Environment Variables](./docs/env.md)
   - [Folder Structure](./docs/folder-structure.md)
-  - [Assets](./docs/assets.md) - [CSS, Sass and SCSS](./docs/css.md) - [ES6](./docs/es6.md)
+  - [Assets](./docs/assets.md) - [CSS, Sass and SCSS](./docs/css.md) - [ES6](./docs/es6.md), [Target browsers](./docs/target.md)
     - [Props](./docs/props.md)
     - [Typescript](./docs/typescript.md)
   - [Yarn](./docs/yarn.md)

data/docs/css.md

@@ -6,7 +6,7 @@ Webpacker supports importing CSS, Sass and SCSS files directly into your JavaScr
 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
@@ -18,6 +18,51 @@ Importing and loading styles is a two step process:
 
 ## Import global styles into your JS app
 
+### Importing CSS as a multi-file pack (Webpacker v5)
+
+When you add a CSS/SCSS/SASS file to `app/javascript/packs/` directory, make sure to use the same pack name as its complementary JavaScript pack, e.g. `application.js` and `application.css`. By Webpacker convention (as of Webpacker v5), this will bundle `application.js` and `application.scss` as part of the same entry point (also described as [a multi-file entry point in the webpack docs](https://webpack.js.org/concepts/entry-points/#single-entry-shorthand-syntax)). With this approach, you can avoid importing CSS from JS, if desired.
+
+```
+app/
+  javascript/
+    packs/
+      application.js
+      application.scss
+```
+
+### Importing CSS from CSS
+
+You can import additional CSS/SCSS/SASS files from within a CSS file:
+
+```
+app/
+  javascript/
+    stylesheets/
+      application.scss
+      posts.scss
+      comments.scss
+```
+
+```css
+/* app/javascript/stylesheets/application.scss */
+
+@import './posts';
+@import './comments';
+```
+
+### Importing CSS provided by an NPM package from SCSS/CSS
+
+Given your application installs an NPM package that provides CSS, such as `flatpickr`, you can import the CSS file(s) by path from the package directory within `node_modules/`:
+
+```js
+/* app/javascript/stylesheets/application.scss */
+
+@import "flatpickr/dist/flatpickr.css"
+```
+
+
+### Importing CSS from JS
+
 ```sass
 // app/javascript/hello_react/styles/hello-react.sass
 
@@ -42,6 +87,16 @@ const Hello = props => (
 )
 ```
 
+### Importing CSS provided by an NPM package from JS
+
+Given your application installs an NPM package that provides CSS, such as `flatpickr`, you can import the CSS file(s) by path from the package directory within `node_modules/`. This is an alternative to importing from within a CSS file, as above:
+
+```js
+// app/javascript/packs/application.js
+
+import "flatpickr/dist/flatpickr.css"
+```
+
 ## Import scoped styles into your JS app
 
 Stylesheets that end with `.module.*` are treated as [CSS Modules](https://github.com/css-modules/css-modules).
@@ -147,14 +202,14 @@ You can use Yarn to add bootstrap or any other modules available on npm:
 yarn add bootstrap
 ```
 
-Import Bootstrap and theme (optional) CSS in your app/javascript/packs/app.js file:
+Import Bootstrap and theme (optional) CSS in your app/javascript/packs/application.js file:
 
 ```js
 import 'bootstrap/dist/css/bootstrap'
 import 'bootstrap/dist/css/bootstrap-theme'
 ```
 
-Or in your app/javascript/app.sass file:
+Or in your app/javascript/packs/application.sass file:
 
 ```sass
 // ~ to tell that this is not a relative import

data/docs/integrations.md

@@ -91,7 +91,7 @@ You can read more about this in the [Vue docs](https://vuejs.org/v2/guide/instal
 
 ### Lazy loading integration
 
-See [docs/es6](docs/es6.md) to know more about Webpack and Webpacker configuration.
+See [docs/es6](es6.md) to know more about Webpack and Webpacker configuration.
 
 For instance, you can lazy load Vue JS components:
 

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

@@ -32,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",

data/docs/troubleshooting.md

@@ -4,11 +4,13 @@
 
 1. Read the error message carefully. The error message will tell you the precise key value
    that is not matching what Webpack expects.
-2. Put a `debugger` statement in your Webpack configuration and run `bin/webpack --debug`.
+2. Put a `debugger` statement in your Webpack configuration and run `bin/webpack --debug-webpacker`.
    If you have a node debugger installed, you'll see the Chrome debugger for your webpack
    config. For example, install the Chrome extension [NiM](https://chrome.google.com/webstore/detail/nodejs-v8-inspector-manag/gnhhdgbaldcilmgcpfddgdbkhjohddkj) and
    set the option for the dev tools to open automatically. For more details on debugging,
    see the official [Webpack docs on debugging](https://webpack.js.org/contribute/debugging/#devtools)
+3. Any arguments that you add to bin/webpack get sent to webpack. For example, you can pass `--debug` to switch loaders to debug mode. See [webpack CLI debug options](https://webpack.js.org/api/cli/#debug-options) for more information on the available options.
+4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-webpacker`
 
 ## ENOENT: no such file or directory - node-sass
 

data/docs/typescript.md

@@ -10,6 +10,50 @@ bundle exec rails webpacker:install:typescript
 
 After that, a new file called `hello_typescript.ts` will be present in your `packs` directory (or rather the `source_entry_path` of your `webpacker.yml` configuration). You're now ready to write TypeScript. 
 
+## (Optional) Adding Compile-Time Type Checking
+
+The default installation only transpiles your TypeScript code using Babel. If you would like to enable type checking as part of the Webpack compilation process (i.e. fail the build if there are TS errors), you can do the following:
+
+1. Install the Fork TS Checker Webpack Plugin
+
+    ```sh
+    yarn add --dev fork-ts-checker-webpack-plugin
+    ```
+
+2. Then add it to your development environment config in `config/webpack/development.js`
+
+    ```js
+    const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
+    const path = require("path");
+
+    environment.plugins.append(
+      "ForkTsCheckerWebpackPlugin",
+      new ForkTsCheckerWebpackPlugin({
+        typescript: {
+          configFile: path.resolve(__dirname, "../../tsconfig.json"),
+        },
+        async: false,
+      })
+    );
+    ```
+
+    If you are `fork-ts-checker-webpack-plugin` older than 5.0, the `tsconfig` option also needs to be specified:
+
+    ```js
+    const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
+    const path = require("path");
+
+    environment.plugins.append(
+      "ForkTsCheckerWebpackPlugin",
+      new ForkTsCheckerWebpackPlugin({
+        // this is a relative path to your project's TypeScript config
+        tsconfig: path.resolve(__dirname, "../../tsconfig.json"),
+        // non-async so type checking will block compilation
+        async: false,
+      })
+    );
+    ```
+
 ## Upgrading to 5.1
 
 If you update your App to `webpacker >= 5.1` and had TypeScript installed before, you need to add some new/remove some old configurations:

data/docs/webpack-dev-server.md

@@ -19,7 +19,7 @@ Now if you refresh your Rails view everything should work as expected.
 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:
+Check out this guide for more information:
 
 - https://webpack.js.org/configuration/dev-server/#devserver-hot
 

data/lib/install/config/babel.config.js

@@ -56,9 +56,7 @@ module.exports = function(api) {
       [
         '@babel/plugin-transform-runtime',
         {
-          helpers: false,
-          regenerator: true,
-          corejs: false
+          helpers: false
         }
       ],
       [

data/lib/install/config/webpacker.yml

@@ -10,7 +10,7 @@ default: &default
 
   # Additional paths webpack should lookup modules
   # ['app/assets', 'engine/foo/app/assets']
-  resolved_paths: []
+  additional_paths: []
 
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false

data/lib/tasks/webpacker/check_node.rake

@@ -3,7 +3,7 @@ namespace :webpacker do
   desc "Verifies if Node.js is installed"
   task :check_node do
     begin
-      node_version = `node -v || nodejs -v`
+      node_version = `node -v || nodejs -v`.strip
       raise Errno::ENOENT if node_version.blank?
 
       pkg_path = Pathname.new("#{__dir__}/../../../package.json").realpath

data/lib/tasks/webpacker/check_yarn.rake

@@ -3,7 +3,7 @@ namespace :webpacker do
   desc "Verifies if Yarn is installed"
   task :check_yarn do
     begin
-      yarn_version = `yarn --version`
+      yarn_version = `yarn --version`.strip
       raise Errno::ENOENT if yarn_version.blank?
 
       pkg_path = Pathname.new("#{__dir__}/../../../package.json").realpath

data/lib/webpacker/compiler.rb

@@ -4,6 +4,8 @@ require "digest/sha1"
 class Webpacker::Compiler
   # Additional paths that test compiler needs to watch
   # Webpacker::Compiler.watched_paths << 'bower_components'
+  #
+  # Deprecated. Use additional_paths in the YAML configuration instead.
   cattr_accessor(:watched_paths) { [] }
 
   # Additional environment variables that the compiler is being run with
@@ -50,6 +52,8 @@ class Webpacker::Compiler
     end
 
     def watched_files_digest
+      warn "Webpacker::Compiler.watched_paths has been deprecated. Set additional_paths in webpacker.yml instead." unless watched_paths.empty?
+
       files = Dir[*default_watched_paths, *watched_paths].reject { |f| File.directory?(f) }
       file_ids = files.sort.map { |f| "#{File.basename(f)}/#{Digest::SHA1.file(f).hexdigest}" }
       Digest::SHA1.hexdigest(file_ids.join("/"))
@@ -86,7 +90,7 @@ class Webpacker::Compiler
 
     def default_watched_paths
       [
-        *config.resolved_paths_globbed,
+        *config.additional_paths_globbed,
         config.source_path_globbed,
         "yarn.lock", "package.json",
         "config/webpack/**/*"
@@ -101,6 +105,7 @@ class Webpacker::Compiler
       return env unless defined?(ActionController::Base)
 
       env.merge("WEBPACKER_ASSET_HOST"        => ENV.fetch("WEBPACKER_ASSET_HOST", ActionController::Base.helpers.compute_asset_host),
-                "WEBPACKER_RELATIVE_URL_ROOT" => ENV.fetch("WEBPACKER_RELATIVE_URL_ROOT", ActionController::Base.relative_url_root))
+                "WEBPACKER_RELATIVE_URL_ROOT" => ENV.fetch("WEBPACKER_RELATIVE_URL_ROOT", ActionController::Base.relative_url_root),
+                "WEBPACKER_CONFIG" => webpacker.config_path.to_s)
     end
 end

data/lib/webpacker/configuration.rb

@@ -27,12 +27,12 @@ class Webpacker::Configuration
     globbed_path_with_extensions(source_path.relative_path_from(root_path))
   end
 
-  def resolved_paths
-    fetch(:resolved_paths)
+  def additional_paths
+    fetch(:additional_paths) + resolved_paths
   end
 
-  def resolved_paths_globbed
-    resolved_paths.map { |p| globbed_path_with_extensions(p) }
+  def additional_paths_globbed
+    additional_paths.map { |p| globbed_path_with_extensions(p) }
   end
 
   def source_entry_path
@@ -76,6 +76,14 @@ class Webpacker::Configuration
   end
 
   private
+    def resolved_paths
+      paths = data.fetch(:resolved_paths, [])
+
+      warn "The resolved_paths option has been deprecated. Use additional_paths instead." unless paths.empty?
+
+      paths
+    end
+
     def fetch(key)
       data.fetch(key, defaults[key])
     end

data/lib/webpacker/dev_server_runner.rb

@@ -45,6 +45,7 @@ module Webpacker
 
       def execute_cmd
         env = Webpacker::Compiler.env
+        env["WEBPACKER_CONFIG"] = @webpacker_config
 
         cmd = if node_modules_bin_exist?
           ["#{@node_modules_bin_path}/webpack-dev-server"]
@@ -52,9 +53,8 @@ module Webpacker
           ["yarn", "webpack-dev-server"]
         end
 
-        if ARGV.include?("--debug")
+        if @argv.include?("--debug-webpacker")
           cmd = [ "node", "--inspect-brk"] + cmd
-          ARGV.delete("--debug")
         end
 
         cmd += ["--config", @webpack_config]

data/lib/webpacker/helper.rb

@@ -46,7 +46,16 @@ module Webpacker::Helper
   #
   #  <%= image_pack_tag 'application.png', size: '16x10', alt: 'Edit Entry' %>
   #  <img alt='Edit Entry' src='/packs/application-k344a6d59eef8632c9d1.png' width='16' height='10' />
+  #
+  #  <%= image_pack_tag 'picture.png', srcset: { 'picture-2x.png' => '2x' } %>
+  #  <img srcset= "/packs/picture-2x-7cca48e6cae66ec07b8e.png 2x" src="/packs/picture-c38deda30895059837cf.png" >
   def image_pack_tag(name, **options)
+    if options[:srcset] && !options[:srcset].is_a?(String)
+      options[:srcset] = options[:srcset].map do |src_name, size|
+        "#{resolve_path_to_image(src_name)} #{size}"
+      end.join(", ")
+    end
+
     image_tag(resolve_path_to_image(name), options)
   end
 
@@ -77,6 +86,7 @@ module Webpacker::Helper
   # By default, this list is auto-generated to match everything in
   # app/javascript/packs/*.js and all the dependent chunks. In production mode, the digested reference is automatically looked up.
   # See: https://webpack.js.org/plugins/split-chunks-plugin/
+  #
   # Example:
   #
   #   <%= javascript_packs_with_chunks_tag 'calendar', 'map', 'data-turbolinks-track': 'reload' %> # =>
@@ -85,11 +95,15 @@ module Webpacker::Helper
   #   <script src="/packs/calendar-1016838bab065ae1e314.chunk.js" data-turbolinks-track="reload"></script>
   #   <script src="/packs/map~runtime-16838bab065ae1e314.chunk.js" data-turbolinks-track="reload"></script>
   #   <script src="/packs/map-16838bab065ae1e314.chunk.js" data-turbolinks-track="reload"></script>
+  #
   # DO:
-  # <%= javascript_packs_with_chunks_tag 'calendar', 'map' %>
+  #
+  #   <%= javascript_packs_with_chunks_tag 'calendar', 'map' %>
+  #
   # DON'T:
-  # <%= javascript_packs_with_chunks_tag 'calendar' %>
-  # <%= javascript_packs_with_chunks_tag 'map' %>
+  #
+  #   <%= javascript_packs_with_chunks_tag 'calendar' %>
+  #   <%= javascript_packs_with_chunks_tag 'map' %>
   def javascript_packs_with_chunks_tag(*names, **options)
     javascript_include_tag(*sources_from_manifest_entrypoints(names, type: :javascript), **options)
   end
@@ -97,6 +111,7 @@ module Webpacker::Helper
   # Creates a link tag, for preloading, that references a given Webpacker asset.
   # In production mode, the digested reference is automatically looked up.
   # See: https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content
+  #
   # Example:
   #
   #   <%= preload_pack_asset 'fonts/fa-regular-400.woff2' %> # =>
@@ -143,11 +158,15 @@ module Webpacker::Helper
   #   <link rel="stylesheet" media="screen" href="/packs/3-8c7ce31a.chunk.css" />
   #   <link rel="stylesheet" media="screen" href="/packs/calendar-8c7ce31a.chunk.css" />
   #   <link rel="stylesheet" media="screen" href="/packs/map-8c7ce31a.chunk.css" />
+  #
   # DO:
-  # <%= stylesheet_packs_with_chunks_tag 'calendar', 'map' %>
+  #
+  #   <%= stylesheet_packs_with_chunks_tag 'calendar', 'map' %>
+  #
   # DON'T:
-  # <%= stylesheet_packs_with_chunks_tag 'calendar' %>
-  # <%= stylesheet_packs_with_chunks_tag 'map' %>
+  #
+  #   <%= stylesheet_packs_with_chunks_tag 'calendar' %>
+  #   <%= stylesheet_packs_with_chunks_tag 'map' %>
   def stylesheet_packs_with_chunks_tag(*names, **options)
     if current_webpacker_instance.config.extract_css?
       stylesheet_link_tag(*sources_from_manifest_entrypoints(names, type: :stylesheet), **options)