webpacker 6.0.0.beta.7 → 6.0.0.pre.1

data/docs/deployment.md

@@ -1,27 +1,28 @@
 # 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`. Remember to set `NODE_ENV` environment variable to production during deployment or when running the rake task.
+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.
 
 By default the output will look like this in different environments:
 
 ```html
-<!-- In development mode with webpack-dev-server -->
-<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/js/calendar-0bd141f6d9360cf4a7f5.js"></script>
-<link rel="stylesheet" media="screen" href="/packs/css/calendar-dc02976b5f94b507e3b6.css">
+  <!-- In development mode with webpack-dev-server -->
+  <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/js/calendar-0bd141f6d9360cf4a7f5.js"></script>
+  <link rel="stylesheet" media="screen" href="/packs/css/calendar-dc02976b5f94b507e3b6.css">
 ```
 
+
 ## Heroku
 
 In order for your Webpacker app to run on Heroku, you'll need to do a bit of configuration before hand.
 
-```bash
+```
 heroku create my-webpacker-heroku-app
 heroku addons:create heroku-postgresql:hobby-dev
 heroku buildpacks:add heroku/nodejs
@@ -36,6 +37,7 @@ We're essentially doing the following here:
 * 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.
@@ -126,3 +128,21 @@ namespace :deploy do
   end
 end
 ```
+
+If you use [nvm](https://github.com/nvm-sh/nvm) to manage node versions for your deployment user, use the below snippet instead:
+
+```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("source ~/.nvm/nvm.sh && cd #{release_path} && yarn install --silent --no-progress --no-audit --no-optional")
+      end
+    end
+  end
+end
+```
+The `source ~/.nvm/nvm.sh` is required because [nvm is not automatically loaded in non-interactive shells](https://github.com/nvm-sh/nvm/issues/1718).
+

data/docs/docker.md

@@ -0,0 +1,68 @@
+# Docker
+
+To setup webpacker with a dockerized Rails application.
+
+First, add a new service for webpacker in docker-compose.yml:
+
+```Dockerfile
+version: '3'
+services:
+  webpacker:
+    build: .
+    environment:
+      - NODE_ENV=development
+      - RAILS_ENV=development
+      - WEBPACKER_DEV_SERVER_HOST=0.0.0.0
+    command: ./bin/webpack-dev-server
+    volumes:
+      - .:/webpacker-example-app
+    ports:
+      - '127.0.0.1:3035:3035'
+```
+
+add nodejs and yarn as dependencies in Dockerfile,
+
+```dockerfile
+FROM ruby:2.4.1
+
+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
+
+# 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....
+```
+
+then add the webpacker host name environment variable to the web/app service:
+
+```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:
+      - "127.0.0.1:3000:3000"
+    environment:
+      - WEBPACKER_DEV_SERVER_HOST=webpacker
+```
+
+Lastly, rebuild your container:
+
+```bash
+docker-compose up --build
+```

data/docs/engines.md

@@ -0,0 +1,213 @@
+# 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 official [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.
+
+- File `lib/my_engine.rb`
+
+```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.
+
+- File `lib/my_engine/engine.rb`
+
+```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.
+
+- File `app/helpers/my_engine/application_helper.rb`
+
+```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`)
+
+- File `lib/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"
+    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
+        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.
+
+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"
+)
+```
+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

@@ -0,0 +1,68 @@
+# Environment variables
+
+
+Environment variables are supported out of the box in Webpacker. For example if
+you run the webpack dev server like so:
+```
+FOO=hello BAR=world ./bin/webpack-dev-server
+```
+
+You can then reference these variables in your JavaScript app code with
+`process.env`:
+
+```js
+console.log(process.env.FOO) // Compiles to console.log("hello")
+```
+
+You may want to store configuration in environment variables via `.env` files,
+similar to the [dotenv Ruby gem](https://github.com/bkeepers/dotenv).
+
+In development, if you use [Foreman](http://ddollar.github.io/foreman) or [Invoker](http://invoker.codemancers.com)
+to launch the webpack server, both of these tools have basic support for a
+`.env` file (Invoker also supports `.env.local`), so no further configuration
+is needed.
+
+However, if you run the webpack server without Foreman/Invoker, or if you
+want more control over what `.env` files to load, you can use the
+[dotenv npm package](https://github.com/motdotla/dotenv). Here is what you could
+do to support a "Ruby-like" dotenv:
+
+```
+yarn add dotenv
+```
+
+```javascript
+// config/webpack/environment.js
+
+...
+const { environment } = require('@rails/webpacker')
+const webpack = require('webpack')
+const dotenv = require('dotenv')
+
+const dotenvFiles = [
+  `.env.${process.env.NODE_ENV}.local`,
+  '.env.local',
+  `.env.${process.env.NODE_ENV}`,
+  '.env'
+]
+dotenvFiles.forEach((dotenvFile) => {
+  dotenv.config({ path: dotenvFile, silent: true })
+})
+
+environment.plugins.insert(
+  "Environment",
+  new webpack.EnvironmentPlugin(process.env)
+)
+
+module.exports = environment
+```
+
+**Warning:** using Foreman/Invoker and npm dotenv at the same time can result in
+confusing behavior, in that Foreman/Invoker variables take precedence over
+npm dotenv variables.
+
+If you'd like to pass custom variables to the on demand compiler, use `Webpacker::Compiler.env` attribute.
+
+```rb
+Webpacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
+```

data/docs/es6.md

@@ -0,0 +1,72 @@
+# ES6
+
+## Babel
+
+Webpacker ships with [babel](https://babeljs.io/) - a JavaScript compiler so
+you can use next generation JavaScript, today. The Webpacker installer sets up a
+standard `babel.config.js` file in your app root, which will work great in most cases
+because of [@babel/preset-env](https://github.com/babel/babel/tree/master/packages/babel-preset-env).
+
+Following ES6/7 features are supported out of the box:
+
+* Async/await.
+* Object Rest/Spread Properties.
+* Exponentiation Operator.
+* Dynamic import() - useful for route level code-splitting
+* Class Fields and Static Properties.
+
+We have also included [core-js](https://github.com/zloirock/core-js) to polyfill features in the
+older browsers.
+
+Don't forget to add these lines into your main entry point:
+
+```js
+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](/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()
+
+While you are free to use `require()` and `module.exports`, we encourage you
+to use `import` and `export` instead since it reads and looks much better.
+
+```js
+import Button from 'react-bootstrap/lib/Button'
+
+// or
+import { Button } from 'react-bootstrap'
+
+class Foo {
+  // code...
+}
+
+export default Foo
+import Foo from './foo'
+```
+
+You can also use named export and import
+
+```js
+export const foo = () => console.log('hello world')
+import { foo } from './foo'
+```