webpacker 6.0.0.beta.2 → 6.0.0.pre.1

data/docs/deployment.md

@@ -0,0 +1,148 @@
+# 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.
+
+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">
+```
+
+
+## Heroku
+
+In order for your Webpacker app to run on Heroku, you'll need to do a bit of configuration before hand.
+
+```
+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 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;
+
+  location @app {
+    proxy_pass http://app;
+    proxy_redirect off;
+
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+
+  location / {
+    try_files $uri @app;
+  }
+
+  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
+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"
+```
+
+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
+```
+
+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'
+```