webpacker 3.6.0 → 4.0.2

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2018 David Heinemeier Hansson, Basecamp
+Copyright (c) 2016-2019 David Heinemeier Hansson, Basecamp
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,11 +1,11 @@
 # Webpacker
 
-![travis-ci status](https://api.travis-ci.org/rails/webpacker.svg?branch=3-x-stable)
-[![node.js](https://img.shields.io/badge/node-%3E%3D%206.0.0-brightgreen.svg)](https://nodejs.org/en/)
+![travis-ci status](https://api.travis-ci.org/rails/webpacker.svg?branch=master)
+[![node.js](https://img.shields.io/badge/node-%3E%3D%206.14.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 3.x.x+](https://webpack.js.org/)
+[webpack 4.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).
@@ -13,6 +13,8 @@ even JavaScript Sprinkles (that all continues to live in app/assets).
 However, it is possible to use Webpacker for CSS, images and fonts assets as well,
 in which case you may not even need the asset pipeline. This is mostly relevant when exclusively using component-based JavaScript frameworks.
 
+**NOTE:** The master branch now hosts the code for v4.x.x. Please refer to [3-x-stable](https://github.com/rails/webpacker/tree/3-x-stable) branch for 3.x documentation. See the [v4-upgrade guide](docs/v4-upgrade.md) for an overview of the changes.
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table of Contents
@@ -39,6 +41,7 @@ in which case you may not even need the asset pipeline. This is mostly relevant
   - [Watched](#watched)
 - [Deployment](#deployment)
 - [Docs](#docs)
+- [Contributing](#contributing)
 - [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -48,13 +51,13 @@ in which case you may not even need the asset pipeline. This is mostly relevant
 
 * Ruby 2.2+
 * Rails 4.2+
-* Node.js 6.0.0+
-* Yarn 0.25.2+
+* Node.js 6.14.4+
+* Yarn 1.x+
 
 
 ## Features
 
-* [webpack 3.x.x](https://webpack.js.org/)
+* [webpack 4.x.x](https://webpack.js.org/)
 * ES6 with [babel](https://babeljs.io/)
 * Automatic code splitting using multiple entry points
 * Stylesheets - Sass and CSS
@@ -85,9 +88,14 @@ gem 'webpacker', '~> 3.5'
 
 # OR if you prefer to use master
 gem 'webpacker', git: 'https://github.com/rails/webpacker.git'
+yarn add https://github.com/rails/webpacker.git
+
+# OR to try out 4.x pre-release
+gem 'webpacker', '>= 4.0.x'
+yarn add @rails/webpacker@next
 ```
 
-Finally, run following to install Webpacker:
+Finally, run the following to install Webpacker:
 
 ```bash
 bundle
@@ -97,6 +105,11 @@ bundle exec rails webpacker:install
 bundle exec rake webpacker:install
 ```
 
+Optional: To fix ["unmet peer dependency" warnings](https://github.com/rails/webpacker/issues/1078),
+
+```bash
+yarn upgrade
+```
 
 ### Usage
 
@@ -129,6 +142,31 @@ can use the `asset_pack_path` helper:
 <img src="<%= asset_pack_path 'images/logo.svg' %>" />
 ```
 
+If you are using new webpack 4 split chunks API, then consider using `javascript_packs_with_chunks_tag` helper, which creates html
+tags for a pack and all the dependent chunks.
+
+```erb
+<%= javascript_packs_with_chunks_tag 'calendar', 'map', 'data-turbolinks-track': 'reload' %>
+
+<script src="/packs/vendor-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
+<script src="/packs/calendar~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
+<script src="/packs/calendar-1016838bab065ae1e314.js" data-turbolinks-track="reload"></script>
+<script src="/packs/map~runtime-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
+<script src="/packs/map-16838bab065ae1e314.js" data-turbolinks-track="reload"></script>
+```
+
+**Important:** Pass all your pack names when using `javascript_packs_with_chunks_tag`
+helper otherwise you will get duplicated chunks on the page.
+
+```erb
+<%# DO %>
+<%= javascript_packs_with_chunks_tag 'calendar', 'map' %>
+
+<%# DON'T %>
+<%= javascript_packs_with_chunks_tag 'calendar' %>
+<%= javascript_packs_with_chunks_tag 'map' %>
+```
+
 **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.
 
@@ -186,7 +224,9 @@ WEBPACKER_DEV_SERVER_HOST=0.0.0.0 ./bin/webpack-dev-server
 **Note:** You need to allow webpack-dev-server host as an allowed origin for `connect-src` if you are running your application in a restrict CSP environment (like Rails 5.2+). This can be done in Rails 5.2+ in the CSP initializer `config/initializers/content_security_policy.rb` with a snippet like this:
 
 ```ruby
-  policy.connect_src :self, :https, 'http://localhost:3035', 'ws://localhost:3035' if Rails.env.development?
+  Rails.application.config.content_security_policy do |policy|
+    policy.connect_src :self, :https, 'http://localhost:3035', 'ws://localhost:3035' if Rails.env.development?
+  end
 ```
 
 **Note:** Don't forget to prefix `ruby` when running these binstubs on Windows
@@ -216,7 +256,7 @@ staging:
   public_output_path: packs-staging
 ```
 
-or, Webpacker will use production environment as a fallback environment for loading configurations. Please note, `NODE_ENV` can either be set to `production` or `development`.
+or, Webpacker will use production environment as a fallback environment for loading configurations. Please note, `NODE_ENV` can either be set to `production`, `development` or `test`.
 This means you don't need to create additional environment files inside `config/webpacker/*` and instead use webpacker.yml to load different configurations using `RAILS_ENV`.
 
 For example, the below command will compile assets in production mode but will use staging configurations from `config/webpacker.yml` if available or use fallback production environment configuration:
@@ -252,24 +292,32 @@ You can run following commands to upgrade Webpacker to the latest stable version
 
 ```bash
 bundle update webpacker
+rails webpacker:binstubs
 yarn upgrade @rails/webpacker --latest
-yarn add webpack-dev-server@^2.11.1
+yarn add webpack-dev-server@^3.1.14
+
+# Or to install a latest release (including pre-releases)
+yarn add @rails/webpacker@next
 ```
 
 ### Yarn Integrity
 
 By default, in development, webpacker runs a yarn integrity check to ensure that all local JavaScript packages are up-to-date. This is similar to what bundler does currently in Rails, but for JavaScript packages. If your system is out of date, then Rails will not initialize. You will be asked to upgrade your local JavaScript packages by running `yarn install`.
 
-To turn off this option, you will need to override the default by adding a new config option to your Rails development environment configuration file (`config/environment/development.rb`):
+To turn off this option, you will need to change the default setting in `config/webpacker.yml`:
 
-```
-config.webpacker.check_yarn_integrity = false
+```yaml
+# config/webpacker.yml
+development:
+  ...
+  # Verifies that versions and hashed value of the package contents in the project's package.json
+  check_yarn_integrity: false
 ```
 
-You may also turn on this feature by adding the config option to any Rails environment configuration file:
+You may also turn on this feature by adding the config option for any Rails environment in `config/webpacker.yml`:
 
-```
-config.webpacker.check_yarn_integrity = true
+```yaml
+  check_yarn_integrity: true
 ```
 
 ## Integrations
@@ -323,11 +371,13 @@ development environment. This can be done in the `config/initializers/content_se
 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
 ```
 
 
@@ -351,11 +401,13 @@ This can be done in the `config/initializers/content_security_policy.rb` with th
 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).
 
@@ -488,10 +540,17 @@ Webpacker::Compiler.watched_paths << 'bower_components'
 
 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).
 
+
 ## Docs
 
 You can find more detailed guides under [docs](./docs).
 
 
+## Contributing
+[![Code Helpers](https://www.codetriage.com/rails/webpacker/badges/users.svg)](https://www.codetriage.com/rails/webpacker)
+
+We encourage you to contribute to Webpacker! See [CONTRIBUTING](CONTRIBUTING.md) for guidelines about how to proceed.
+
+
 ## License
 Webpacker is released under the [MIT License](https://opensource.org/licenses/MIT).

data/docs/assets.md

@@ -56,12 +56,12 @@ You can also use [babel-plugin-module-resolver](https://github.com/tleunen/babel
 yarn add babel-plugin-module-resolver
 ```
 
-Specify the plugin in your `.babelrc` with the custom root or alias. Here's an example:
+Specify the plugin in your `babel.config.js` with the custom root or alias. Here's an example:
 
-```json
+```js
 {
-  "plugins": [
-    ["module-resolver", {
+  plugins: [
+    [require("babel-plugin-module-resolver").default, {
       "root": ["./app"],
       "alias": {
         "assets": "./assets"
@@ -103,4 +103,7 @@ app/javascript:
 
 <img src="<%= asset_pack_path 'images/calendar.png' %>" />
 <% # => <img src="/packs/images/calendar.png" /> %>
+
+<%= image_pack_tag 'images/calendar.png' %>
+<% # => <img src="/packs/images/calendar.png" /> %>
 ```

data/docs/css.md

@@ -16,7 +16,7 @@ Webpacker supports importing CSS, Sass and SCSS files directly into your JavaScr
 
 ```js
 // React component example
-// app/javascripts/packs/hello_react.jsx
+// app/javascript/packs/hello_react.jsx
 
 import React from 'react'
 import helloIcon from '../hello_react/images/icon.png'
@@ -44,7 +44,7 @@ Stylesheets end with `.module.*` is treated as [CSS Modules](https://github.com/
 
 ```js
 // React component example
-// app/javascripts/packs/hello_react.jsx
+// app/javascript/packs/hello_react.jsx
 
 import React from 'react'
 import helloIcon from '../hello_react/images/icon.png'
@@ -64,7 +64,7 @@ const Hello = props => (
 ## Link styles from your Rails 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
+[mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-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.
 
@@ -72,6 +72,7 @@ a separate `[pack_name].css` bundle so that in your view you can use the
 <%= stylesheet_pack_tag 'hello_react' %>
 ```
 
+Webpacker emits css files only if `extract_css` is set to true in webpacker.yml otherwise `stylesheet_pack_tag` returns nil.
 
 ## Add bootstrap
 
@@ -102,13 +103,22 @@ Or in your app/javascript/app.sass file:
 
 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`
+and the installer sets up a standard `postcss.config.js`
 file in your app root with standard plugins.
 
-```yml
-plugins:
-  postcss-import: {}
-  postcss-cssnext: {}
+```js
+module.exports = {
+  plugins: [
+    require('postcss-import'),
+    require('postcss-flexbugs-fixes'),
+    require('postcss-preset-env')({
+      autoprefixer: {
+        flexbox: 'no-2009'
+      },
+      stage: 3
+    })
+  ]
+}
 ```
 
 ## Using CSS with [vue-loader](https://github.com/vuejs/vue-loader)
@@ -145,12 +155,35 @@ environment.loaders.get('sass').use.splice(-1, 0, {
 });
 ```
 
-## Configure [Autoprefixer](https://github.com/postcss/autoprefixer)
+## Working with TypeScript
+
+In order to get CSS to work with typescript you have two options.
+You can either use `require` to bypass typescript special `import`.
+
+```ts
+const styles = require('../hello_react/styles/hello-react');
+```
+You may also use the package [typings-for-css-modules-loader](https://github.com/Jimdo/typings-for-css-modules-loader) instead of `css-loader` to automatically generate typescript `.d.ts` files in order to help resolve any css/scss styles. To do that:
 
-By default, Autoprefixer does not apply Internet Explorer CSS grid polyfills. If you wish to enable these, or change any other Autoprefixer config, do it through `.postcssrc.yml`:
+```js
+// app/javascript/packs/hello_react.jsx
+import * as styles from '../hello_react.styles/hello-react.module.scss';
+```
 
-```yml
-plugins:
-  postcss-import: {}
-  postcss-cssnext: { features: { autoprefixer: { grid: true } } }
+```bash
+yarn add --dev typings-for-css-modules-loader
+```
+
+```js
+// webpack/environment.js
+const { environment } = require('@rails/webpacker')
+
+// replace css-loader with typings-for-css-modules-loader
+environment.loaders.get('moduleSass').use = environment.loaders.get('moduleSass').use.map((u) => {
+  if(u.loader == 'css-loader') {
+    return { ...u, loader: 'typings-for-css-modules-loader' };
+  } else {
+    return u;
+  }
+});
 ```

data/docs/deployment.md

@@ -72,3 +72,14 @@ server {
 
 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.
+
+## Capistrano
+
+### Assets compiling on every deployment even if JavaScript and CSS files are not changed
+
+Make sure you have `public/packs` and `node_modules` in `:linked_dirs`
+
+```ruby
+append :linked_dirs, "log", "tmp/pids", "tmp/cache", "tmp/sockets", "public/packs", ".bundle", "node_modules"
+```
+

data/docs/engines.md

@@ -0,0 +1,155 @@
+# Using in Rails engines
+
+If the application UI consists of multiple frontend application, you'd probably like to isolate their building too (e.g. if you use different frameworks/versions). Hence we needed our webpack(-er) to be isolated too: separate `package.json`, dev server, compilation process.
+
+You can do this by adding another Webpacker instance to your application.
+
+This guide describes how to do that using [Rails engines](https://guides.rubyonrails.org/engines.html).
+
+
+## Step 1: create Rails engine.
+
+First, you create a Rails engine (say, `MyEngine`). See the offical [Rails guide](https://guides.rubyonrails.org/engines.html).
+
+## Step 2: install Webpacker within the engine.
+
+There is no built-in tasks to install Webpacker within the engine, thus you have to add all the require files manually (you can copy them from the main app):
+- Add `config/webpacker.yml` and `config/webpack/*.js` files
+- Add `bin/webpack` and `bin/webpack-dev-server` files
+- Add `package.json` with required deps.
+
+
+## Step 3: configure Webpacker instance.
+
+```ruby
+module MyEngine
+  ROOT_PATH = Pathname.new(File.join(__dir__, ".."))
+
+  class << self
+    def webpacker
+      @webpacker ||= ::Webpacker::Instance.new(
+        root_path: ROOT_PATH,
+        config_path: ROOT_PATH.join("config/webpacker.yml")
+      )
+    end
+  end
+end
+```
+
+## Step 4: Configure dev server proxy.
+
+```ruby
+module MyEngine
+  class Engine < ::Rails::Engine
+    initializer "webpacker.proxy" do |app|
+        insert_middleware = begin
+                            MyEngine.webpacker.config.dev_server.present?
+                          rescue
+                            nil
+                          end
+        next unless insert_middleware
+
+        app.middleware.insert_before(
+          0, Webpacker::DevServerProxy, # "Webpacker::DevServerProxy" if Rails version < 5
+          ssl_verify_none: true,
+          webpacker: MyEngine.webpacker
+        )
+      end
+  end
+end
+```
+
+If you have multiple webpackers, you would probably want to run multiple dev servers at a time, and hence be able to configure their setting through env vars (e.g. within a `docker-compose.yml` file):
+
+```yml
+# webpacker.yml
+# ...
+development:
+  # ...
+  dev_server:
+    env_prefix: "MY_ENGINE_WEBPACKER_DEV_SERVER"
+    # ...
+```
+
+## Step 5: configure helper.
+
+```ruby
+require "webpacker/helper"
+
+module MyEngine
+  module ApplicationHelper
+    include ::Webpacker::Helper
+
+    def current_webpacker_instance
+      MyEngine.webpacker
+    end
+  end
+end
+```
+
+Now you can use `stylesheet_pack_tag` and `javascript_pack_tag` from within your engine.
+
+## Step 6: rake tasks.
+
+Add Rake task to compile assets in production (`rake my_engine:webpacker:compile`)
+
+```ruby
+namespace :my_engine do
+  namespace :webpacker do
+    desc "Install deps with yarn"
+    task :yarn_install do
+      Dir.chdir(File.join(__dir__, "../..")) do
+        system "yarn install --no-progress --production"
+      end
+    end
+
+    desc "Compile JavaScript packs using webpack for production with digests"
+    task compile: [:yarn_install, :environment] do
+      Webpacker.with_node_env("production") do
+          if MyEngine.webpacker.commands.compile
+            # Successful compilation!
+          else
+            # Failed compilation
+            exit!
+          end
+      end
+    end
+  end
+end
+```
+
+## Step 7: serving compiled packs.
+
+There are two approaches on serving compiled assets.
+
+### Put engine's assets to the root app's public/ folder
+
+You can serve engine's assets using the main app's static files server which serves files from `public/` folder.
+
+For that you must configure your engine's webpacker to put compiled assets to the app's `public/` folder:
+
+```yml
+# my_engine/config/webpacker.yml
+default: &default
+  # ...
+  # public_root_path could be used to override the path to `public/` folder
+  # (relative to the engine root)
+  public_root_path: ../public
+  # use a different sub-folder name
+  public_output_path: my-engine-packs
+```
+
+### Use a separate middleware
+
+To serve static assets from the engine's `public/` folder you must add a middleware and point it to your engine's webpacker output path:
+
+```ruby
+# application.rb
+
+config.middleware.use(
+  "Rack::Static",
+  urls: ["/my-engine-packs"], root: "my_engine/public"
+)
+```
+
+**NOTE:** in the example above we assume that your `public_output_path` is set to `my-engine-packs` in your engine's `webpacker.yml`.