webpacker_helpers 3.0.0.beta.1

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2016 David Heinemeier Hansson, Basecamp, and
+2017 Justin Gordon, ShakaCode
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+# Webpacker Helpers
+![Gem Version](https://badge.fury.io/rb/webpacker_helpers.svg)
+
+**VERSION 8 of [React on Rails](https://github.com/shakacode/react_on_rails) is super close!!!** [VERSION 8.0.0-beta.3](https://rubygems.org/gems/react_on_rails/versions/8.0.0.beta.3) has shipped with [webpacker_helpers](https://github.com/shakacode/webpacker_helpers) support! Please try [the 8.0.0-beta.3 beta](https://rubygems.org/gems/react_on_rails/versions/8.0.0.beta.3) and please report issues! We're **SUPER** close as we've also upgraded the [shakacode/react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) with [PR #395](https://github.com/shakacode/react-webpack-rails-tutorial/pull/395). That PR shows the changes needed to go to Webpacker Helpers.
+
+
+*A slimmer version of Webpacker*
+
+Webpacker Helpers provides similar webpack enabled view helpers from [Webpacker](https://github.com/rails/webpacker).
+[React on Rails](https://github.com/shakacode/react_on_rails) version 8 and greater defaults to using Webpacker Helpers.
+
+For example, these view helpers allow your application's layout to easily reference JavaScript and CSS files created by your Webpack setup, taking into account differences in the Rails environments. With these helpers, there is no reason for Webpack created assets to run through the [Asset Pipeline](http://guides.rubyonrails.org/asset_pipeline.html), as was done in React on Rails 7.x and earlier.
+
+If you like this project, show your support by giving us a star!
+
+# Why Fork?
+
+> Everything should be made as simple as possible, but not simpler.
+
+[Albert Einstein on Wikiquote](https://en.wikiquote.org/wiki/Albert_Einstein)
+
+Why did [ShakaCode](http://www.shakacode.com) fork [rails/webpacker](https://github.com/rails/webpacker)? For [react_on_rails](https://github.com/shakacode/react_on_rails), we wanted a simpler configuration to get the core functionality needed. You configure 2 things:
+
+1. Name of the manifest file.
+2. The directory within `/public` where Webpack will create the manifest and output file.
+
+Then you need to configure your Webpack to generate a simple manifest that maps the base output names to the possibly fingerprinted versions. Note, unlike Webpacker, Webpacker Helpers wants your manifest to **NOT** contain any host information.
+
+Optionally, you can configure the name of the server and port for hot reloading, and if hot reloading is the default for a given Rails.env.
+
+For more details on how this project differs from Webpacker and why we forked, please see [Webpacker Helpers: Why Did  We Fork Webpacker?](https://medium.com/@railsonmaui/webpacker-lite-why-did-we-fork-webpacker-ee3305688d66)
+
+# NEWS
+ 
+* 2017-05-03: React on Rails 8.0.0 beta defaults to using webpacker_helpers.
+
+## Installation
+
+The best way to see the installation of webpacker_helpers is to use the generator for React on Rails 8.0.0 or greater. Otherwise, add the gem and create the configuration file described below.
+
+## Overview
+
+1. Configure the `config/webpacker_helpers.yml` file, as described below. You will specify the name of the manifest file and the output directory used by step 2.
+2. Use the [webpack-manifest-plugin](https://www.npmjs.com/package/webpack-manifest-plugin) to generate a manifest
+   in the output directory (`webpack_public_output_dir`) that you configured in your `/config/webpacker_helpers.yml` file. 
+3. Use the view helpers on your layouts to provide the webpack generated files. Note, these are the same names used by [rails/webpacker](https://github.com/rails/webpacker).
+   These `output` names are **NOT** the actual file names, as the file name may have a [fingerprint](http://guides.rubyonrails.org/asset_pipeline.html#what-is-fingerprinting-and-why-should-i-care-questionmark).
+   ```erb
+   <%# app/views/layouts/application.html.erb %>
+   <%= javascript_pack_tag('main') %>
+   <%= stylesheet_pack_tag('main') %>
+   ```
+4. When hot-reloading, the extract-text-plugin (extracted CSS from being inlined in the JavaScript)is not supported. Therefore, all your hot-reloaded Webpack-compiled CSS will be inlined and we will skip the CSS file by default. If you're not worried about hot-reloading for your CSS, use the `enabled_when_hot_loading: true` option. 
+
+   ```erb
+   <%= stylesheet_pack_tag('main', enabled_when_hot_loading: true) %> <% # Default is false %>
+   ```
+   
+For more details on the helper documentation, see the Ruby comments in [lib/webpacker_helpers/helper.rb](lib/webpacker_helpers/helper.rb) and please submit PRs here to help us improve the docs!
+
+## Configuration
+Webpacker Helpers takes one configuration file: `config/webpacker_helpers.yml` used to configure two required values and a couple optional values. Note, this file is configured like `config/database.yml` in that you place the values beneath the name of the Rails.env. 
+
+### Mandatory Configuration within `config/webpacker_helpers.yml` 
+
+1. `manifest`: The manifest file name 
+1. `webpack_public_output_dir`: The output directory of both the manifest and the webpack static generated files within the `/public` directory.
+
+Note, placing output files within the Rails `/public` directory is not configurable.
+
+### Optional Configuration within `config/webpacker_helpers.yml` 
+1. `hot_reloading_host`: The name of the hot reloading `webpack-dev-server` including the port
+2. `hot_reloading_enabled_by_default`: If hot reloading should default to true
+
+### Hot Reloading Notes
+
+Do not put the output server in your `manifest.json` file. The rails view helpers will automatically prepend the hot_reloading_host to the asset path.
+
+### Example Configuration `/config/webpacker_helpers.yml`
+
+This example config shows how we use different output directories for the webpack generated assets per the type of environment. This is extremely convenient when you want to log redux messages in development but not in your tests.
+
+```yaml
+# /config/webpacker_helpers.yml
+# Note: Base output directory of /public is assumed for static files
+default: &default
+  manifest: manifest.json  
+  # Used in your webpack configuration. Must be created in the
+  # webpack_public_output_dir folder.
+  
+development:
+  <<: *default
+  # generated files for development, in /public/webpack/development
+  webpack_public_output_dir: webpack/development
+  
+  # Default is localhost:3500. You can specify the protocol if needed. Defaults to http://.
+  hot_reloading_host: localhost:3500
+  
+  # Developer note: considering removing this option so it can ONLY be turned by using an ENV value.
+  # Default is false, ENV 'HOT_RELOADING' will always override 
+  hot_reloading_enabled_by_default: false 
+  
+test:
+  <<: *default
+  # generated files for tests, in /public/webpack/test   
+  webpack_public_output_dir: webpack/test
+
+production:
+  <<: *default
+  # generated files for tests, in /public/webpack/production
+  webpack_public_output_dir: webpack/production
+```
+
+## Example for Development vs Hot Reloading vs Production Mode
+
+**erb file**
+
+```erb
+  <% # app/views/layouts/application.html.erb %>
+  <%= javascript_pack_tag('main') %>
+  <%= stylesheet_pack_tag('main') %>
+```
+
+**html file**
+
+```html
+  <!-- In test mode -->
+  <script src="/webpack/test/main.js"></script>
+  <link rel="stylesheet" media="screen" href="/webpack/test/main-0bd141f6d9360cf4a7f5.js">
+  
+  <!-- In development mode -->
+  <script src="/webpack/development/main.js"></script>
+  <link rel="stylesheet" media="screen" href="/webpack/development/main-0bd141f6d9360cf4a7f5.js">
+  
+  <!-- In development mode with hot reloading, using the webpack-dev-server -->
+  <script src="http://localhost:8080/webpack/development/main.js"></script>
+  <!-- Note, there's no stylesheet tag by default, as your CSS should be inlined in your JS. -->
+  
+  <!-- In production mode -->
+  <script src="/webpack/production/main-0bd141f6d9360cf4a7f5.js"></script>
+  <link rel="stylesheet" media="screen" href="/webpack/production/main-dc02976b5f94b507e3b6.css">
+```
+
+## Other Helpers: Getting the asset path
+
+The `asset_pack_path` helper provides the path of any given asset that's been compiled by webpack.
+Note, the real file path is the subdirectory of the public.
+
+For example, if you want to create a `<link rel="prefetch">` or `<img />`
+for an asset used in your pack code you can reference them like this in your view,
+
+```erb
+<img src="<%= asset_pack_path 'calendar.png' %>" />
+<% # => <img src="/webpack/calendar.png" /> %>
+<% # real file path "public/webpack/calendar.png" /> %>
+```
+
+## Webpack Helper
+You may use the [React on Rails NPM Package](https://www.npmjs.com/package/react-on-rails), [react-on-rails/webpackConfigLoader](https://github.com/shakacode/react_on_rails/blob/master/webpackConfigLoader.js) to provide your Webpack config with easy access to the YAML settings. Even if you don't use the NPM package, you can use that file to inspire your Webpack configuration.
+
+## Rake Tasks
+
+### Examples
+
+To see available webpacker_helpers rake tasks:
+
+```
+rake webpacker_helpers
+```
+
+If you are using different directories for the output paths per RAILS_ENV, this is how you'd delete the files created for tests: 
+```
+RAILS_ENV=test rake webpacker_helpers:clobber
+```
+
+## Differences from Webpacker
+
+1. Configuration setup of an optional single file `/config/webpacker_helpers.yml`
+2. Webpacker helpers expect the manifest to contain the server URL when hot reloading. Webpacker Helpers expects the manifest to never contain any host information.
+
+## Hot Reloading
+
+1. Tell Rails and Webpacker Helpers that you're hot reloading by setting the ENV value of `HOT_RELOADING=YES` if you are not hot reloading by default by setting the `hot_reloading_enabled_by_default` key in your config file.
+1. By default, the `stylesheet_pack_tag` helper will not create a tag when hot reloading is enabled. Per the note above, when hot-reloading, the extract-text-plugin (extracted CSS from being inlined in the JavaScript)is not supported. Therefore, all your hot-reloaded Webpack-compiled CSS will be inlined and we will skip the CSS file by default.
+
+   ```erb
+   <%= stylesheet_pack_tag('main', enabled_when_hot_loading: true) %> <% # Default is false %>
+   ```
+   
+
+
+## Prerequisites
+* Ruby 2+
+* Rails 4.2+

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+# Executes a string or an array of strings in a shell in the given directory
+def sh_in_dir(dir, shell_commands)
+  shell_commands = [shell_commands] if shell_commands.is_a?(String)
+  shell_commands.each { |shell_command| sh %(cd #{dir} && #{shell_command.strip}) }
+end
+
+def gem_root
+  File.expand_path("../.", __FILE__)
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+desc "Run Rubocop as shell"
+task :rubocop do
+  sh_in_dir(gem_root, "bundle exec rubocop .")
+end
+
+task default: [:test, :rubocop]

data/lib/tasks/webpacker.rake

@@ -0,0 +1,12 @@
+tasks = {
+  "webpacker_helpers:clobber" => "Remove the webpack compiled output directory as defined in config/webpack/paths.yml",
+  "webpacker_helpers:check_node"      => "Verifies if Node.js is installed",
+  "webpacker_helpers:check_yarn"      => "Verifies if yarn is installed",
+  "webpacker_helpers:verify_install"  => "Verifies if webpacker is installed"
+}.freeze
+
+desc "Lists all available tasks in webpacker_helpers"
+task :webpacker_helpers do
+  puts "Available webpacker_helpers tasks are:"
+  tasks.each { |task, message| puts task.ljust(30) + message }
+end

data/lib/tasks/webpacker_lite/check_node.rake

@@ -0,0 +1,19 @@
+namespace :webpacker_helpers do
+  desc "Verifies if Node.js is installed"
+  task :check_node do
+    begin
+      node_version = `node -v`
+      required_node_version = "6.4"
+
+      raise Errno::ENOENT if node_version.blank?
+      if Gem::Version.new(node_version.strip.tr("v", "")) < Gem::Version.new(required_node_version)
+        puts "WebpackerHelpers requires Node.js >= v#{required_node_version} and you are using #{node_version}"
+        puts "Please upgrade Node.js https://nodejs.org/en/download/"
+        puts "Exiting!" && exit!
+      end
+    rescue Errno::ENOENT
+      puts "Node.js not installed. Please download and install Node.js https://nodejs.org/en/download/"
+      puts "Exiting!" && exit!
+    end
+  end
+end

data/lib/tasks/webpacker_lite/check_yarn.rake

@@ -0,0 +1,12 @@
+namespace :webpacker_helpers do
+  desc "Verifies if yarn is installed"
+  task :check_yarn do
+    begin
+      version = `yarn --version`
+      raise Errno::ENOENT if version.blank?
+    rescue Errno::ENOENT
+      puts "WebpackerHelpers requires yarn. Please download and install Yarn https://yarnpkg.com/lang/en/docs/install/"
+      puts "Exiting!" && exit!
+    end
+  end
+end

data/lib/tasks/webpacker_lite/clobber.rake

@@ -0,0 +1,17 @@
+require "webpacker_helpers/configuration"
+
+namespace :webpacker_helpers do
+  desc "Remove the webpack compiled output directory as defined in config/webpack/paths.yml"
+  task clobber: ["webpacker_helpers:verify_install", :environment] do
+    output_path = WebpackerHelpers::Configuration.webpack_public_output_dir
+    FileUtils.rm_r(output_path) if File.exist?(output_path)
+    puts "Removed webpack output path directory #{output_path}"
+  end
+end
+
+# Run clobber if the assets:clobber is run
+if Rake::Task.task_defined?("assets:clobber")
+  Rake::Task["assets:clobber"].enhance do
+    Rake::Task["webpacker_helpers:clobber"].invoke
+  end
+end

data/lib/tasks/webpacker_lite/verify_install.rake

@@ -0,0 +1,16 @@
+require "webpacker_helpers/configuration"
+
+namespace :webpacker_helpers do
+  desc "Verifies if webpacker_helpers is installed"
+  task verify_install: [:check_node, :check_yarn] do
+    if File.exist?(WebpackerHelpers::Env.file_path)
+      puts "WebpackerHelpers is installed 🎉 🍰"
+      puts "Using #{WebpackerHelpers::Env.file_path} file for setting up webpack paths"
+    else
+      puts "Configuration config/webpack/paths.yml file not found. \n"\
+           "Make sure webpacker_helpers:install is run successfully before " \
+           "running dependent tasks"
+      exit!
+    end
+  end
+end

data/lib/webpacker_helpers.rb

@@ -0,0 +1,13 @@
+module WebpackerHelpers
+  def self.bootstrap
+    WebpackerHelpers::Env.load_instance
+    WebpackerHelpers::Configuration.load_instance
+    WebpackerHelpers::Manifest.load_instance
+  end
+
+  def env
+    WebpackerHelpers::Env.current.inquiry
+  end
+end
+
+require "webpacker_helpers/railtie" if defined?(Rails)

data/lib/webpacker_helpers/configuration.rb

@@ -0,0 +1,56 @@
+# Loads webpacker configuration from config/webpack/paths.yml
+require "webpacker_helpers/file_loader"
+require "webpacker_helpers/env"
+
+class WebpackerHelpers::Configuration < WebpackerHelpers::FileLoader
+  RAILS_WEB_PUBLIC = "public"
+
+  class << self
+    def manifest_path
+      Rails.root.join(webpack_public_output_dir,
+                      configuration.fetch(:manifest, "manifest.json"))
+    end
+
+    def webpack_public_output_dir
+      Rails.root.join(RAILS_WEB_PUBLIC, configuration.fetch(:webpack_public_output_dir, "webpack"))
+    end
+
+    def base_path
+      "/#{configuration.fetch(:webpack_public_output_dir, "webpack")}"
+    end
+
+    # Uses the hot_reloading_host if appropriate
+    def base_url
+      if WebpackerHelpers::Env.hot_loading?
+        host = configuration[:hot_reloading_host]
+        if host.blank?
+          raise "WebpackerHelpers's /config/webpacker_helpers.yml needs a configuration value for the "\
+            "`hot_reloading_host` for environment #{Rails.env}."
+        end
+        if host.starts_with?("http")
+          host
+        else
+          "http://#{host}"
+        end
+      else
+        base_path
+      end
+    end
+
+    def configuration
+      load_instance
+      raise WebpackerHelpers::FileLoader::FileLoaderError.new("WebpackerHelpers::Configuration.load_instance must be called first") unless instance
+      instance.data
+    end
+
+    def file_path
+      Rails.root.join("config", "webpacker_helpers.yml")
+    end
+  end
+
+  private
+    def load_data
+      return super unless File.exist?(@path)
+      HashWithIndifferentAccess.new(YAML.load(File.read(@path))[WebpackerHelpers::Env.current])
+    end
+end

data/lib/webpacker_helpers/env.rb

@@ -0,0 +1,30 @@
+# Singleton registry for determining NODE_ENV from config/webpacker_helpers.yml
+require "webpacker_helpers/file_loader"
+
+class WebpackerHelpers::Env < WebpackerHelpers::FileLoader
+  class << self
+    def current
+      raise WebpackerHelpers::FileLoader::FileLoaderError.new("WebpackerHelpers::Env.load must be called first") unless instance
+      instance.data
+    end
+
+    def hot_loading?
+      (ENV["HOT_RELOADING"].present? && (
+      ENV["HOT_RELOADING"].upcase == "YES" ||
+        ENV["HOT_RELOADING"].upcase == "TRUE")) ||
+        current["hot_reloading_enabled_by_default"]
+    end
+
+    def file_path
+      Rails.root.join("config", "webpacker_helpers.yml")
+    end
+  end
+
+  private
+    def load_data
+      environments = File.exist?(@path) ? YAML.load(File.read(@path)).keys : [].freeze
+      return ENV["NODE_ENV"] if environments.include?(ENV["NODE_ENV"])
+      return Rails.env if environments.include?(Rails.env)
+      "production"
+    end
+end

data/lib/webpacker_helpers/file_loader.rb

@@ -0,0 +1,41 @@
+# Provides a base singleton-configuration pattern for loading a JSON or YAML file, given a path
+class WebpackerHelpers::FileLoader
+  class NotFoundError < StandardError; end
+  class FileLoaderError < StandardError; end
+
+  class_attribute :instance
+  attr_accessor :data, :mtime
+
+  class << self
+    def load_instance(path = file_path)
+      # Assume production is 100% cached
+      return if self.instance && # if we have a singleton
+        (env == "production" || # skip if production bc always cached
+          (File.exist?(path) && self.instance.mtime == File.mtime(path))) # skip if mtime not changed
+
+      self.instance = new(path)
+    end
+
+    def file_path
+      raise FileLoaderError.new("Subclass of WebpackerHelpers::FileLoader should override this method")
+    end
+
+    private
+
+    # Prefer the NODE_ENV to the rails env.
+    def env
+      ENV["NODE_ENV"].presence || Rails.env
+    end
+  end
+
+  private
+    def initialize(path)
+      @path = path
+      @mtime = File.exist?(path) ? File.mtime(path) : nil
+      @data = load_data
+    end
+
+    def load_data
+      {}.freeze
+    end
+end