shakapacker 6.2.1 → 6.4.0

data/docs/react.md

@@ -0,0 +1,262 @@
+# React Integration
+
+These steps describe how to create a Rails/React app, using Shakapacker as the bundler.
+
+Before starting, ensure that you have Yarn installed, for example:
+
+```shell
+npm i -g yarn
+```
+
+## Basic Setup
+
+Create a new Rails app as per the [installation instructions in the README](https://github.com/shakacode/shakapacker#installation).
+
+Add React, as well as the necessary libraries to enable CSS support in your application:
+
+```shell
+yarn add react react-dom @babel/preset-react
+yarn add css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
+```
+
+Update the Babel configuration in the `package.json` file:
+
+```diff
+"babel": {
+  "presets": [
+    "./node_modules/shakapacker/package/babel/preset.js",
++   "@babel/preset-react"
+  ]
+},
+```
+
+And that's it. You can now create a React app using `app/javascript/application.js` as your entry point.
+
+## Enabling Hot Module Replacement (HMR)
+
+With HMR enabled, Shakapacker will automatically update only that part of the page that changed when it detects changes in your project files. This has the nice advantage of preserving your app’s state.
+
+To enable HMR in a React app, proceed as follows:.
+
+In `config/webpacker.yml` set `hmr` is set to `true`.
+
+Install the [react-refresh](https://www.npmjs.com/package/react-refresh) package, as well as [@pmmmwh/react-refresh-webpack-plugin](https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin):
+
+```shell
+yarn add --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
+```
+
+Alter `config/webpack/webpack.config.js` like so:
+
+```js
+const { webpackConfig, inliningCss } = require('shakapacker');
+const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
+const isDevelopment = process.env.NODE_ENV !== 'production';
+
+if (isDevelopment && inliningCss) {
+  webpackConfig.plugins.push(
+    new ReactRefreshWebpackPlugin({
+      overlay: {
+        sockPort: webpackConfig.devServer.port,
+      },
+    })
+  );
+}
+
+module.exports = webpackConfig;
+```
+
+This applies the plugin to the webpack configuration.
+
+Delete the Babel configuration from `package.json`:
+
+```diff
+- "babel": {
+-   "presets": [
+-     "./node_modules/shakapacker/package/babel/preset.js",
+-     "@babel/preset-react"
+-   ]
+- },
+```
+
+Then create a `babel.config.js` file in the root of project and add the following:
+
+```js
+module.exports = function (api) {
+  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const resultConfig = defaultConfigFunc(api)
+  const isDevelopmentEnv = api.env('development')
+  const isProductionEnv = api.env('production')
+  const isTestEnv = api.env('test')
+
+  const changesOnDefault = {
+    presets: [
+      [
+        '@babel/preset-react',
+        {
+          development: isDevelopmentEnv || isTestEnv,
+          useBuiltIns: true
+        }
+      ]
+    ].filter(Boolean),
+    plugins: [
+      isProductionEnv && ['babel-plugin-transform-react-remove-prop-types',
+        {
+          removeImport: true
+        }
+      ],
+      process.env.WEBPACK_SERVE && 'react-refresh/babel'
+    ].filter(Boolean),
+  }
+
+  resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
+  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins ]
+
+  return resultConfig
+}
+```
+
+This is taken from the [sample React Babel config](https://github.com/jameshibbard/shakapacker/blob/master/docs/customizing_babel_config.md#react-configuration).
+
+HMR for your React app is now enabled. 🚀
+
+## A Basic Demo App
+
+To test that all of the above is working, you can follow these instructions to create a basic React app using Shakapacker.
+
+1. Create a new Rails app:
+```shell
+rails new myapp --skip-javascript
+cd myapp
+bundle add shakapacker --strict
+./bin/bundle install
+./bin/rails webpacker:install
+yarn add react react-dom @babel/preset-react
+yarn add css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
+```
+
+2. Generate a controller
+```shell
+rails g controller site index
+echo '<div id="root"></div>' > app/views/site/index.html.erb
+```
+
+3. Create a CSS file and a React component:
+```shell
+touch app/javascript/App.css app/javascript/App.js
+```
+
+4. Edit `app/javascript/application.js` like so:
+```jsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import HelloMessage from './App';
+
+const container = document.getElementById('root');
+const root = createRoot(container);
+
+document.addEventListener('DOMContentLoaded', () => {
+  root.render(<HelloMessage name="World" />);
+});
+```
+
+5. Add the following to `app/javascript/App.js`:
+```jsx
+import React from 'react';
+import 'App.css';
+const HelloMessage = ({ name }) => <h1>Hello, {name}!</h1>;
+export default HelloMessage;
+```
+
+6. Add the following to `app/javascript/App.css`:
+```css
+h1 { color: blue; }
+```
+
+7. Enable HMR in config/webpacker.yml:
+```shell
+hmr: true
+```
+
+8. Install the [react-refresh](https://www.npmjs.com/package/react-refresh) package, as well as [@pmmmwh/react-refresh-webpack-plugin](https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin):
+
+```shell
+yarn add --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
+```
+
+9. Alter `config/webpack/webpack.config.js` like so:
+
+```js
+const { webpackConfig, inliningCss } = require('shakapacker');
+const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
+const isDevelopment = process.env.NODE_ENV !== 'production';
+
+if (isDevelopment && inliningCss) {
+  webpackConfig.plugins.push(
+    new ReactRefreshWebpackPlugin({
+      overlay: {
+        sockPort: webpackConfig.devServer.port,
+      },
+    })
+  );
+}
+
+module.exports = webpackConfig;
+```
+
+10. Remove the Babel configuration from `package.json`
+```diff
+- "babel": {
+-   "presets": [
+-     "./node_modules/shakapacker/package/babel/preset.js"
+-   ]
+- },
+```
+
+11. Create a `babel.config.js` file in the project root and add the following [sample code](https://github.com/shakacode/shakapacker/blob/master/docs/customizing_babel_config.md#react-configuration):
+```js
+module.exports = function (api) {
+  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const resultConfig = defaultConfigFunc(api)
+  const isDevelopmentEnv = api.env('development')
+  const isProductionEnv = api.env('production')
+  const isTestEnv = api.env('test')
+
+  const changesOnDefault = {
+    presets: [
+      [
+        '@babel/preset-react',
+        {
+          development: isDevelopmentEnv || isTestEnv,
+          useBuiltIns: true
+        }
+      ]
+    ].filter(Boolean),
+    plugins: [
+      isProductionEnv && ['babel-plugin-transform-react-remove-prop-types',
+        {
+          removeImport: true
+        }
+      ],
+      process.env.WEBPACK_SERVE && 'react-refresh/babel'
+    ].filter(Boolean),
+  }
+
+  resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
+  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins ]
+
+  return resultConfig
+}
+```
+
+9. Start the Rails server and the webpack-dev-server in separate console windows:
+```shell
+rails s
+./bin/webpacker-dev-server
+```
+
+10. Hit: <http://localhost:3000/site/index>
+
+11. Edit either the React component at `app/javascript/App.js` or the CSS file at `app/javascript/App.css` and observe the HMR goodness.
+
+Note that HMR will not work if you edit `app/javascript/application.js` and you experience a full refresh with a warning in the console. For more info on this, see here: https://github.com/pmmmwh/react-refresh-webpack-plugin/issues/177

data/docs/sprockets.md

@@ -0,0 +1,10 @@
+# Sprockets
+
+### Note for Sprockets usage
+
+If you are still using Sprockets for some of your assets, you might want to include files from `node_modules` directory in your asset pipeline. This is useful, for example, if you want to reference a stylesheet from a node package in your `.scss` stylesheet.
+
+In order to enable this, make sure you add `node_modules` to the asset load path by adding the following in an initializer (for example `config/initializers/assets.rb`)
+```ruby
+Rails.application.config.assets.paths << Rails.root.join('node_modules')
+```

data/docs/v6_upgrade.md

@@ -2,7 +2,7 @@
 
 There are several substantial changes in Shakapacker v6 that you need to manually account for when coming from Webpacker 5. This guide will help you through it.
 
-[ShakaCode](https://www.shakacode.com) offers suppport for upgrading from webpacker or using Shakapacker. If interested, contact [justin@shakacode.com](mailto:justin@shakacode.com).
+[ShakaCode](https://www.shakacode.com) offers support for upgrading from webpacker or using Shakapacker. If interested, contact [justin@shakacode.com](mailto:justin@shakacode.com).
 
 ## Webpacker/Shakapacker has become a slimmer wrapper around Webpack
 

data/lib/install/config/webpacker.yml

@@ -2,11 +2,21 @@
 
 default: &default
   source_path: app/javascript
+
+  # You can have a subdirectory of the source_path, like 'packs' (recommended).
+  # Alternatively, you can use '/' to use the whole source_path directory.
   source_entry_path: /
+
+  # If nested_entries is true, then we'll pick up subdirectories within the source_entry_path.
+  # You cannot set this option to true if you set source_entry_path to '/'
+  nested_entries: false
+
   public_root_path: public
   public_output_path: packs
   cache_path: tmp/webpacker
   webpack_compile_output: true
+  # See https://github.com/shakacode/shakapacker#deployment
+  webpacker_precompile: true
 
   # Location for manifest.json, defaults to {public_output_path}/manifest.json if unset
   # manifest_path: public/packs/manifest.json
@@ -24,9 +34,13 @@ default: &default
   # Set to true to enable check for matching versions of shakapacker gem and NPM package - will raise an error if there is a mismatch or wildcard versioning is used
   ensure_consistent_versioning: false
 
+  # Select whether the compiler will use SHA digest ('digest' option) or most most recent modified timestamp ('mtime') to determine freshness
+  compiler_strategy: digest
+
 development:
   <<: *default
   compile: true
+  compiler_strategy: mtime
 
   # Reference: https://webpack.js.org/configuration/dev-server/
   dev_server:

data/lib/tasks/webpacker/clean.rake

@@ -11,9 +11,7 @@ namespace :webpacker do
   end
 end
 
-skip_webpacker_clean = %w(no false n f).include?(ENV["WEBPACKER_PRECOMPILE"])
-
-unless skip_webpacker_clean
+if Webpacker.config.webpacker_precompile?
   # Run clean if the assets:clean is run
   if Rake::Task.task_defined?("assets:clean")
     Rake::Task["assets:clean"].enhance do

data/lib/tasks/webpacker/clobber.rake

@@ -8,9 +8,7 @@ namespace :webpacker do
   end
 end
 
-skip_webpacker_clobber = %w(no false n f).include?(ENV["WEBPACKER_PRECOMPILE"])
-
-unless skip_webpacker_clobber
+if Webpacker.config.webpacker_precompile?
   # Run clobber if the assets:clobber is run
   if Rake::Task.task_defined?("assets:clobber")
     Rake::Task["assets:clobber"].enhance do

data/lib/tasks/webpacker/compile.rake

@@ -1,16 +1,8 @@
 $stdout.sync = true
 
-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? ? [] : ["webpacker:yarn_install"]
-  Rake::Task["assets:precompile"].enhance(deps) do |task|
+  Rake::Task["assets:precompile"].enhance do |task|
     prefix = task.name.split(/#|assets:precompile/).first
 
     Rake::Task["#{prefix}webpacker:compile"].invoke
@@ -33,13 +25,10 @@ namespace :webpacker do
   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 Webpacker.config.webpacker_precompile?
   if Rake::Task.task_defined?("assets:precompile")
     enhance_assets_precompile
   else
-    Rake::Task.define_task("assets:precompile" => ["webpacker:yarn_install", "webpacker:compile"])
+    Rake::Task.define_task("assets:precompile" => ["webpacker:compile"])
   end
 end

data/lib/tasks/webpacker.rake

@@ -9,7 +9,6 @@ tasks = {
   "webpacker:check_binstubs"          => "Verifies that bin/webpacker is present",
   "webpacker:binstubs"                => "Installs Webpacker binstubs in this application",
   "webpacker:verify_install"          => "Verifies if Webpacker is installed",
-  "webpacker:yarn_install"            => "Support for older Rails versions. Install all JavaScript dependencies as specified via Yarn"
 }.freeze
 
 desc "Lists all available tasks in Webpacker"

data/lib/webpacker/base_strategy.rb

@@ -0,0 +1,24 @@
+module Webpacker
+  class BaseStrategy
+    def initialize
+      @config = Webpacker.config
+    end
+
+    def after_compile_hook
+      nil
+    end
+
+    private
+
+      attr_reader :config
+
+      def default_watched_paths
+        [
+          *config.additional_paths.map { |path| "#{path}{,/**/*}" },
+          "#{config.source_path}{,/**/*}",
+          "yarn.lock", "package.json",
+          "config/webpack{,/**/*}"
+        ].freeze
+      end
+  end
+end

data/lib/webpacker/compiler.rb

@@ -1,18 +1,13 @@
 require "open3"
-require "digest/sha1"
+require "webpacker/compiler_strategy"
 
 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
   # Webpacker::Compiler.env['FRONTEND_API_KEY'] = 'your_secret_key'
   cattr_accessor(:env) { {} }
 
-  delegate :config, :logger, to: :webpacker
+  delegate :config, :logger, :strategy, to: :webpacker
+  delegate :fresh?, :stale?, :after_compile_hook, to: :strategy
 
   def initialize(webpacker)
     @webpacker = webpacker
@@ -21,11 +16,7 @@ class Webpacker::Compiler
   def compile
     if stale?
       run_webpack.tap do |success|
-        # We used to only record the digest on success
-        # However, the output file is still written on error, meaning that the digest should still be updated.
-        # If it's not, you can end up in a situation where a recompile doesn't take place when it should.
-        # See https://github.com/rails/webpacker/issues/2113
-        record_compilation_digest
+        after_compile_hook
       end
     else
       logger.debug "Everything's up-to-date. Nothing to do"
@@ -33,50 +24,9 @@ class Webpacker::Compiler
     end
   end
 
-  # Returns true if all the compiled packs are up to date with the underlying asset files.
-  def fresh?
-    last_compilation_digest&.== watched_files_digest
-  end
-
-  # Returns true if the compiled packs are out of date with the underlying asset files.
-  def stale?
-    !fresh?
-  end
-
   private
     attr_reader :webpacker
 
-    def last_compilation_digest
-      compilation_digest_path.read if compilation_digest_path.exist? && config.manifest_path.exist?
-    rescue Errno::ENOENT, Errno::ENOTDIR
-    end
-
-    def watched_files_digest
-      if Rails.env.development?
-        warn <<~MSG.strip
-          Webpacker::Compiler - Slow setup for development
-
-          Prepare JS assets with either:
-          1. Running `bin/webpacker-dev-server`
-          2. Set `compile` to false in webpacker.yml and run `bin/webpacker -w`
-        MSG
-      end
-
-      warn "Webpacker::Compiler.watched_paths has been deprecated. Set additional_paths in webpacker.yml instead." unless watched_paths.empty?
-      root_path = Pathname.new(File.expand_path(config.root_path))
-      expanded_paths = [*default_watched_paths, *watched_paths].map do |path|
-        root_path.join(path)
-      end
-      files = Dir[*expanded_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("/"))
-    end
-
-    def record_compilation_digest
-      config.cache_path.mkpath
-      compilation_digest_path.write(watched_files_digest)
-    end
-
     def optionalRubyRunner
       bin_webpack_path = config.root_path.join("bin/webpacker")
       first_line = File.readlines(bin_webpack_path).first.chomp
@@ -107,19 +57,6 @@ class Webpacker::Compiler
       status.success?
     end
 
-    def default_watched_paths
-      [
-        *config.additional_paths.map { |path| "#{path}/**/*" },
-        "#{config.source_path}/**/*",
-        "yarn.lock", "package.json",
-        "config/webpack/**/*"
-      ].freeze
-    end
-
-    def compilation_digest_path
-      config.cache_path.join("last-compilation-digest-#{webpacker.env}")
-    end
-
     def webpack_env
       return env unless defined?(ActionController::Base)
 

data/lib/webpacker/compiler_strategy.rb

@@ -0,0 +1,20 @@
+require "webpacker/mtime_strategy"
+require "webpacker/digest_strategy"
+
+module Webpacker
+  class CompilerStrategy
+    def self.from_config
+      strategy_from_config = Webpacker.config.compiler_strategy
+
+      case strategy_from_config
+      when "mtime"
+        Webpacker::MtimeStrategy.new
+      when "digest"
+        Webpacker::DigestStrategy.new
+      else
+        raise "Unknown strategy '#{strategy_from_config}'. " \
+              "Available options are 'mtime' and 'digest'."
+      end
+    end
+  end
+end

data/lib/webpacker/configuration.rb

@@ -27,6 +27,15 @@ class Webpacker::Configuration
     fetch(:ensure_consistent_versioning)
   end
 
+  def webpacker_precompile?
+    # ENV of false takes precedence
+    return false if %w(no false n f).include?(ENV["WEBPACKER_PRECOMPILE"])
+    return true if %w(yes true t).include?(ENV["WEBPACKER_PRECOMPILE"])
+
+    return false unless config_path.exist?
+    fetch(:webpacker_precompile)
+  end
+
   def source_path
     root_path.join(fetch(:source_path))
   end
@@ -79,6 +88,10 @@ class Webpacker::Configuration
     fetch(:webpack_compile_output)
   end
 
+  def compiler_strategy
+    fetch(:compiler_strategy)
+  end
+
   def fetch(key)
     data.fetch(key, defaults[key])
   end

data/lib/webpacker/digest_strategy.rb

@@ -0,0 +1,59 @@
+require "digest/sha1"
+require "webpacker/base_strategy"
+
+module Webpacker
+  class DigestStrategy < BaseStrategy
+    # Returns true if all the compiled packs are up to date with the underlying asset files.
+    def fresh?
+      last_compilation_digest&.== watched_files_digest
+    end
+
+    # Returns true if the compiled packs are out of date with the underlying asset files.
+    def stale?
+      !fresh?
+    end
+
+    def after_compile_hook
+      # We used to only record the digest on success
+      # However, the output file is still written on error, meaning that the digest should still be updated.
+      # If it's not, you can end up in a situation where a recompile doesn't take place when it should.
+      # See https://github.com/rails/webpacker/issues/2113
+      record_compilation_digest
+    end
+
+    private
+
+      def last_compilation_digest
+        compilation_digest_path.read if compilation_digest_path.exist? && config.manifest_path.exist?
+      rescue Errno::ENOENT, Errno::ENOTDIR
+      end
+
+      def watched_files_digest
+        if Rails.env.development?
+          warn <<~MSG.strip
+          Webpacker::Compiler - Slow setup for development
+          Prepare JS assets with either:
+          1. Running `bin/webpacker-dev-server`
+          2. Set `compile` to false in webpacker.yml and run `bin/webpacker -w`
+        MSG
+        end
+
+        root_path = Pathname.new(File.expand_path(config.root_path))
+        expanded_paths = [*default_watched_paths].map do |path|
+          root_path.join(path)
+        end
+        files = Dir[*expanded_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("/"))
+      end
+
+      def record_compilation_digest
+        config.cache_path.mkpath
+        compilation_digest_path.write(watched_files_digest)
+      end
+
+      def compilation_digest_path
+        config.cache_path.join("last-compilation-digest-#{Webpacker.env}")
+      end
+  end
+end

data/lib/webpacker/helper.rb

@@ -101,9 +101,17 @@ module Webpacker::Helper
       "Please refer to https://github.com/shakacode/shakapacker/blob/master/README.md#usage for the usage guide"
     end
 
+    append_javascript_pack_tag(*names, defer: defer)
+    non_deferred = sources_from_manifest_entrypoints(javascript_pack_tag_queue[:non_deferred], type: :javascript)
+    deferred = sources_from_manifest_entrypoints(javascript_pack_tag_queue[:deferred], type: :javascript) - non_deferred
+
     @javascript_pack_tag_loaded = true
 
-    javascript_include_tag(*sources_from_manifest_entrypoints(names, type: :javascript), **options.tap { |o| o[:defer] = defer })
+    capture do
+      concat javascript_include_tag(*deferred, **options.tap { |o| o[:defer] = true })
+      concat "\n" if non_deferred.any? && deferred.any?
+      concat javascript_include_tag(*non_deferred, **options.tap { |o| o[:defer] = false })
+    end
   end
 
   # Creates a link tag, for preloading, that references a given Webpacker asset.
@@ -153,8 +161,25 @@ module Webpacker::Helper
     stylesheet_link_tag(*sources_from_manifest_entrypoints(names, type: :stylesheet), **options)
   end
 
+  def append_javascript_pack_tag(*names, defer: true)
+    if @javascript_pack_tag_loaded
+      raise "You can only call append_javascript_pack_tag before javascript_pack_tag helper. " \
+      "Please refer to https://github.com/shakacode/shakapacker/blob/master/README.md#usage for the usage guide"
+    end
+
+    hash_key = defer ? :deferred : :non_deferred
+    javascript_pack_tag_queue[hash_key] |= names
+  end
+
   private
 
+    def javascript_pack_tag_queue
+      @javascript_pack_tag_queue ||= {
+        deferred: [],
+        non_deferred: []
+      }
+    end
+
     def sources_from_manifest_entrypoints(names, type:)
       names.map { |name| current_webpacker_instance.manifest.lookup_pack_with_chunks!(name.to_s, type: type) }.flatten.uniq
     end

data/lib/webpacker/instance.rb

@@ -19,6 +19,10 @@ class Webpacker::Instance
     )
   end
 
+  def strategy
+    @strategy ||= Webpacker::CompilerStrategy.from_config
+  end
+
   def compiler
     @compiler ||= Webpacker::Compiler.new self
   end