shakapacker 9.3.0.beta.7 → 9.3.1

data/lib/shakapacker/configuration.rb

@@ -3,13 +3,62 @@ require "json"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/hash/indifferent_access"
 
+# Configuration management for Shakapacker
+#
+# Loads and provides access to settings from +config/shakapacker.yml+, including:
+# - Source and output paths
+# - Compilation settings
+# - Dev server configuration
+# - Asset bundler selection (webpack vs rspack)
+# - JavaScript transpiler configuration (babel, swc, esbuild)
+#
+# Configuration values can be overridden via environment variables:
+# - +SHAKAPACKER_CONFIG+ - path to config file
+# - +SHAKAPACKER_PRECOMPILE+ - whether to precompile assets
+# - +SHAKAPACKER_ASSETS_BUNDLER+ - which bundler to use
+# - +SHAKAPACKER_ASSET_HOST+ - CDN or asset host URL
+#
+# @example Accessing configuration
+#   config = Shakapacker.config
+#   config.source_path
+#   #=> #<Pathname:/app/app/packs>
+#   config.webpack?
+#   #=> true
+#
+# @see https://github.com/shakacode/shakapacker/blob/main/docs/shakapacker.yml.md
 class Shakapacker::Configuration
   class << self
+    # Flag indicating whether Shakapacker is currently being installed
+    # Used to suppress certain validations during installation
+    # @return [Boolean] true if installation is in progress
+    # @api private
     attr_accessor :installing
   end
 
-  attr_reader :root_path, :config_path, :env, :bundler_override
-
+  # The application root path
+  # @return [Pathname] the root path
+  attr_reader :root_path
+
+  # The path to the shakapacker.yml configuration file
+  # @return [Pathname] the config file path
+  attr_reader :config_path
+
+  # The current Rails environment
+  # @return [ActiveSupport::StringInquirer] the environment
+  attr_reader :env
+
+  # Override for the assets bundler (set via CLI flag)
+  # @return [String, nil] the bundler override or nil
+  # @api private
+  attr_reader :bundler_override
+
+  # Creates a new configuration instance
+  #
+  # @param root_path [Pathname] the application root path
+  # @param config_path [Pathname] the path to shakapacker.yml
+  # @param env [ActiveSupport::StringInquirer] the Rails environment
+  # @param bundler_override [String, nil] optional bundler override (webpack or rspack)
+  # @return [Shakapacker::Configuration] the new configuration instance
   def initialize(root_path:, config_path:, env:, bundler_override: nil)
     @root_path = root_path
     @env = env
@@ -17,22 +66,52 @@ class Shakapacker::Configuration
     @bundler_override = bundler_override
   end
 
+  # Returns the dev server configuration hash
+  #
+  # Contains settings like host, port, https, hmr, etc. for the webpack-dev-server.
+  #
+  # @return [Hash] the dev server configuration
   def dev_server
     fetch(:dev_server)
   end
 
+  # Returns whether automatic compilation is enabled
+  #
+  # When true, Shakapacker will automatically compile assets when they're requested
+  # and are stale. This is typically enabled in development and disabled in production.
+  #
+  # @return [Boolean] true if automatic compilation is enabled
   def compile?
     fetch(:compile)
   end
 
+  # Returns whether nested entries are enabled
+  #
+  # When true, allows organizing entry points in subdirectories within the
+  # source entry path.
+  #
+  # @return [Boolean] true if nested entries are allowed
   def nested_entries?
     fetch(:nested_entries)
   end
 
+  # Returns whether consistent versioning check is enabled
+  #
+  # When true, verifies that package.json and Gemfile versions of shakapacker match.
+  #
+  # @return [Boolean] true if version consistency checking is enabled
   def ensure_consistent_versioning?
     fetch(:ensure_consistent_versioning)
   end
 
+  # Returns whether Shakapacker should precompile assets
+  #
+  # Checks in order:
+  # 1. SHAKAPACKER_PRECOMPILE environment variable (yes/true/y/t or no/false/n/f)
+  # 2. shakapacker_precompile setting in config file
+  # 3. Defaults to false if config file doesn't exist
+  #
+  # @return [Boolean] true if assets should be precompiled
   def shakapacker_precompile?
     # ENV of false takes precedence
     return false if %w(no false n f).include?(ENV["SHAKAPACKER_PRECOMPILE"])
@@ -42,18 +121,40 @@ class Shakapacker::Configuration
     fetch(:shakapacker_precompile)
   end
 
+  # Returns the absolute path to the source directory
+  #
+  # This is where your JavaScript/CSS source files live (e.g., app/packs).
+  #
+  # @return [Pathname] the absolute source path
   def source_path
     root_path.join(fetch(:source_path))
   end
 
+  # Returns additional paths to include in compilation
+  #
+  # These paths are added to webpack/rspack's resolve configuration to allow
+  # importing modules from additional directories.
+  #
+  # @return [Array<String>] array of additional paths
   def additional_paths
     fetch(:additional_paths)
   end
 
+  # Returns the absolute path to the source entry directory
+  #
+  # Entry points (application.js, etc.) are found in this directory.
+  #
+  # @return [Pathname] the absolute entry path
   def source_entry_path
     source_path.join(relative_path(fetch(:source_entry_path)))
   end
 
+  # Returns the absolute path to the manifest.json file
+  #
+  # The manifest maps source file names to their compiled output paths with digests.
+  # Defaults to manifest.json in the public output directory if not configured.
+  #
+  # @return [Pathname] the absolute manifest path
   def manifest_path
     if data.has_key?(:manifest_path)
       root_path.join(fetch(:manifest_path))
@@ -62,14 +163,30 @@ class Shakapacker::Configuration
     end
   end
 
+  # Alias for {#manifest_path}
+  #
+  # @return [Pathname] the absolute manifest path
+  # @see #manifest_path
   def public_manifest_path
     manifest_path
   end
 
+  # Returns the absolute path to the public root directory
+  #
+  # This is typically the Rails +public/+ directory where compiled assets
+  # are served from.
+  #
+  # @return [Pathname] the absolute public path
   def public_path
     root_path.join(fetch(:public_root_path))
   end
 
+  # Returns the absolute path to the private output directory
+  #
+  # The private output path is for server-side bundles (e.g., SSR) that should
+  # not be publicly accessible. Returns nil if not configured.
+  #
+  # @return [Pathname, nil] the absolute private output path or nil
   def private_output_path
     private_path = fetch(:private_output_path)
     return nil unless private_path
@@ -77,26 +194,66 @@ class Shakapacker::Configuration
     root_path.join(private_path)
   end
 
+  # Returns the absolute path to the public output directory
+  #
+  # This is where compiled assets are written for public serving
+  # (typically +public/packs+).
+  #
+  # @return [Pathname] the absolute public output path
   def public_output_path
     public_path.join(fetch(:public_output_path))
   end
 
+  # Returns whether manifest caching is enabled
+  #
+  # When true, the manifest.json file is cached in memory and only reloaded
+  # when it changes. This improves performance in production.
+  #
+  # @return [Boolean] true if manifest should be cached
   def cache_manifest?
     fetch(:cache_manifest)
   end
 
+  # Returns the absolute path to the compilation cache directory
+  #
+  # Webpack/rspack uses this directory to cache compilation results for faster
+  # subsequent builds.
+  #
+  # @return [Pathname] the absolute cache path
   def cache_path
     root_path.join(fetch(:cache_path))
   end
 
+  # Returns whether webpack/rspack compilation output should be shown
+  #
+  # When true, displays webpack/rspack's compilation progress and results.
+  #
+  # @return [Boolean] true if compilation output should be displayed
   def webpack_compile_output?
     fetch(:webpack_compile_output)
   end
 
+  # Returns the compiler strategy for determining staleness
+  #
+  # Options:
+  # - +"mtime"+ - use file modification times (faster, less accurate)
+  # - +"digest"+ - use file content digests (slower, more accurate)
+  #
+  # @return [String] the compiler strategy ("mtime" or "digest")
   def compiler_strategy
     fetch(:compiler_strategy)
   end
 
+  # Returns the assets bundler to use (webpack or rspack)
+  #
+  # Resolution order:
+  # 1. CLI --bundler flag (via bundler_override)
+  # 2. SHAKAPACKER_ASSETS_BUNDLER environment variable
+  # 3. assets_bundler setting in config file
+  # 4. bundler setting in config file (deprecated)
+  # 5. Defaults to "webpack"
+  #
+  # @return [String] "webpack" or "rspack"
   def assets_bundler
     # CLI --bundler flag takes highest precedence
     return @bundler_override if @bundler_override
@@ -108,19 +265,35 @@ class Shakapacker::Configuration
     ENV["SHAKAPACKER_ASSETS_BUNDLER"] || fetch(:assets_bundler) || fetch(:bundler) || "webpack"
   end
 
-  # Deprecated: Use assets_bundler instead
+  # Deprecated alias for {#assets_bundler}
+  #
+  # @deprecated Use {#assets_bundler} instead
+  # @return [String] the assets bundler
+  # @see #assets_bundler
   def bundler
     assets_bundler
   end
 
+  # Returns whether rspack is the configured bundler
+  #
+  # @return [Boolean] true if using rspack
   def rspack?
     assets_bundler == "rspack"
   end
 
+  # Returns whether webpack is the configured bundler
+  #
+  # @return [Boolean] true if using webpack
   def webpack?
     assets_bundler == "webpack"
   end
 
+  # Returns the precompile hook command to run after compilation
+  #
+  # The hook is a shell command that runs after successful compilation,
+  # useful for post-processing tasks.
+  #
+  # @return [String, nil] the hook command or nil if not configured
   def precompile_hook
     hook = fetch(:precompile_hook)
     return nil if hook.nil? || (hook.is_a?(String) && hook.strip.empty?)
@@ -132,6 +305,16 @@ class Shakapacker::Configuration
     hook.strip
   end
 
+  # Returns the JavaScript transpiler to use (babel, swc, or esbuild)
+  #
+  # Resolution order:
+  # 1. javascript_transpiler setting in config file
+  # 2. webpack_loader setting in config file (deprecated)
+  # 3. Default based on bundler (swc for rspack, babel for webpack)
+  #
+  # Validates that the configured transpiler matches installed packages.
+  #
+  # @return [String] "babel", "swc", or "esbuild"
   def javascript_transpiler
     # Show deprecation warning if using old 'webpack_loader' key
     if data.has_key?(:webpack_loader) && !data.has_key?(:javascript_transpiler)
@@ -147,11 +330,46 @@ class Shakapacker::Configuration
     transpiler
   end
 
-  # Deprecated: Use javascript_transpiler instead
+  # Deprecated alias for {#javascript_transpiler}
+  #
+  # @deprecated Use {#javascript_transpiler} instead
+  # @return [String] the JavaScript transpiler
+  # @see #javascript_transpiler
   def webpack_loader
     javascript_transpiler
   end
 
+  # Returns the CSS Modules export mode configuration
+  #
+  # Controls how CSS Module class names are exported in JavaScript:
+  # - "named" (default): Use named exports with camelCase conversion (v9 behavior)
+  # - "default": Use default export with both original and camelCase names (v8 behavior)
+  #
+  # @return [String] "named" or "default"
+  # @raise [ArgumentError] if an invalid value is configured
+  def css_modules_export_mode
+    @css_modules_export_mode ||= begin
+      mode = fetch(:css_modules_export_mode) || "named"
+
+      # Validate the configuration value
+      valid_modes = ["named", "default"]
+      unless valid_modes.include?(mode)
+        raise ArgumentError,
+          "Invalid css_modules_export_mode: '#{mode}'. " \
+          "Valid values are: #{valid_modes.map { |m| "'#{m}'" }.join(', ')}. " \
+          "See https://github.com/shakacode/shakapacker/blob/main/docs/css-modules-export-mode.md"
+      end
+
+      mode
+    end
+  end
+
+  # Returns the path to the bundler configuration directory
+  #
+  # This is where webpack.config.js or rspack.config.js should be located.
+  # Defaults to config/webpack for webpack or config/rspack for rspack.
+  #
+  # @return [String] the relative path to the bundler config directory
   def assets_bundler_config_path
     custom_path = fetch(:assets_bundler_config_path)
     return custom_path if custom_path
@@ -160,6 +378,25 @@ class Shakapacker::Configuration
     rspack? ? "config/rspack" : "config/webpack"
   end
 
+  # Returns the raw configuration data hash
+  #
+  # Returns the merged configuration from the shakapacker.yml file for the current environment.
+  # The hash has symbolized keys loaded from the config file. Individual config values can be
+  # accessed through specific accessor methods like {#source_path}, which apply defaults via {#fetch}.
+  #
+  # The returned hash is frozen to prevent accidental mutations. To access config values,
+  # use the provided accessor methods instead of modifying this hash directly.
+  #
+  # @return [Hash<Symbol, Object>] the raw configuration data with symbolized keys (frozen)
+  # @example
+  #   config.data[:source_path]  #=> "app/javascript"
+  #   config.data[:compile]      #=> true
+  # @note The hash is frozen to prevent mutations. Use accessor methods for safe config access.
+  # @api public
+  def data
+    @data ||= load.freeze
+  end
+
   private
 
     def default_javascript_transpiler
@@ -170,6 +407,9 @@ class Shakapacker::Configuration
     def validate_transpiler_configuration(transpiler)
       return unless ENV["NODE_ENV"] != "test" # Skip validation in test environment
 
+      # Skip validation if transpiler is set to 'none' (custom webpack config)
+      return if transpiler == "none"
+
       # Check if package.json exists
       package_json_path = root_path.join("package.json")
       return unless package_json_path.exist?
@@ -220,10 +460,28 @@ class Shakapacker::Configuration
 
   public
 
+  # Fetches a configuration value
+  #
+  # Looks up the value in the loaded configuration data, falling back to
+  # the default configuration if not found.
+  #
+  # @param key [Symbol] the configuration key to fetch
+  # @return [Object] the configuration value
+  # @api private
   def fetch(key)
     data.fetch(key, defaults[key])
   end
 
+  # Returns the asset host URL for serving assets
+  #
+  # Resolution order:
+  # 1. SHAKAPACKER_ASSET_HOST environment variable
+  # 2. asset_host setting in config file
+  # 3. Rails ActionController::Base.helpers.compute_asset_host
+  #
+  # Used to serve assets from a CDN or different domain.
+  #
+  # @return [String, nil] the asset host URL or nil
   def asset_host
     ENV.fetch(
       "SHAKAPACKER_ASSET_HOST",
@@ -231,10 +489,22 @@ class Shakapacker::Configuration
     )
   end
 
+  # Returns whether subresource integrity (SRI) is enabled
+  #
+  # When true, generates integrity hashes for script and link tags to
+  # protect against compromised CDNs or man-in-the-middle attacks.
+  #
+  # @return [Boolean] true if integrity checking is enabled
   def integrity
     fetch(:integrity)
   end
 
+  # Returns whether HTTP/2 Early Hints are enabled
+  #
+  # When true, sends Early Hints headers to start loading assets before
+  # the full response is ready.
+  #
+  # @return [Boolean] true if early hints are enabled
   def early_hints
     fetch(:early_hints)
   end
@@ -272,10 +542,6 @@ class Shakapacker::Configuration
       [private_full_path.cleanpath.to_s, public_full_path.cleanpath.to_s]
     end
 
-    def data
-      @data ||= load
-    end
-
     def load
       config = begin
         YAML.load_file(config_path.to_s, aliases: true)

data/lib/shakapacker/dev_server.rb

@@ -1,16 +1,50 @@
+# Development server status and configuration
+#
+# Provides methods to query the status and configuration of the webpack-dev-server
+# or rspack-dev-server. This includes checking if the server is running, accessing
+# its host/port, and querying features like HMR (Hot Module Replacement).
+#
+# The dev server runs during development to provide live reloading and hot module
+# replacement. In production, the dev server is not used.
+#
+# @example Checking dev server status
+#   dev_server = Shakapacker.dev_server
+#   dev_server.running?
+#   #=> true
+#   dev_server.host_with_port
+#   #=> "localhost:3035"
+#   dev_server.hmr?
+#   #=> true
+#
+# @see Shakapacker::DevServerRunner
 class Shakapacker::DevServer
+  # Default environment variable prefix for dev server settings
   DEFAULT_ENV_PREFIX = "SHAKAPACKER_DEV_SERVER".freeze
 
   # Configure dev server connection timeout (in seconds), default: 0.1
-  # Shakapacker.dev_server.connect_timeout = 1
+  # @example
+  #   Shakapacker::DevServer.connect_timeout = 1
+  # @return [Float] the connection timeout in seconds
   cattr_accessor(:connect_timeout) { 0.1 }
 
+  # The Shakapacker configuration
+  # @return [Shakapacker::Configuration] the configuration
   attr_reader :config
 
+  # Creates a new dev server instance
+  #
+  # @param config [Shakapacker::Configuration] the Shakapacker configuration
+  # @return [Shakapacker::DevServer] the new dev server instance
   def initialize(config)
     @config = config
   end
 
+  # Returns whether the dev server is currently running
+  #
+  # Checks by attempting to open a TCP connection to the configured host and port.
+  # Returns false if the connection fails or if dev server is not configured.
+  #
+  # @return [Boolean] true if the dev server is running
   def running?
     if config.dev_server.present?
       Socket.tcp(host, port, connect_timeout: connect_timeout).close
@@ -22,14 +56,30 @@ class Shakapacker::DevServer
     false
   end
 
+  # Returns the dev server host
+  #
+  # Can be overridden via SHAKAPACKER_DEV_SERVER_HOST environment variable.
+  #
+  # @return [String] the host (e.g., "localhost", "0.0.0.0")
   def host
     fetch(:host)
   end
 
+  # Returns the dev server port
+  #
+  # Can be overridden via SHAKAPACKER_DEV_SERVER_PORT environment variable.
+  #
+  # @return [Integer] the port number (typically 3035)
   def port
     fetch(:port)
   end
 
+  # Returns the server type (http or https)
+  #
+  # Can be overridden via SHAKAPACKER_DEV_SERVER_SERVER environment variable.
+  # Validates that the value is "http" or "https", falling back to "http" if invalid.
+  #
+  # @return [String] "http" or "https"
   def server
     server_value = fetch(:server)
     server_type = server_value.is_a?(Hash) ? server_value[:type] : server_value
@@ -49,24 +99,55 @@ class Shakapacker::DevServer
     "http"
   end
 
+  # Returns the protocol for the dev server
+  #
+  # This is an alias that returns "https" if server is "https", otherwise "http".
+  #
+  # @return [String] "http" or "https"
   def protocol
     return "https" if server == "https"
 
     "http"
   end
 
+  # Returns the host and port as a single string
+  #
+  # @return [String] the host:port combination (e.g., "localhost:3035")
+  # @example
+  #   dev_server.host_with_port
+  #   #=> "localhost:3035"
   def host_with_port
     "#{host}:#{port}"
   end
 
+  # Returns whether pretty output is enabled
+  #
+  # When true, the dev server produces prettier, more readable output.
+  # Can be overridden via SHAKAPACKER_DEV_SERVER_PRETTY environment variable.
+  #
+  # @return [Boolean] true if pretty output is enabled
   def pretty?
     fetch(:pretty)
   end
 
+  # Returns whether Hot Module Replacement (HMR) is enabled
+  #
+  # When true, the dev server updates modules in the browser without a full
+  # page reload, preserving application state.
+  # Can be overridden via SHAKAPACKER_DEV_SERVER_HMR environment variable.
+  #
+  # @return [Boolean] true if HMR is enabled
   def hmr?
     fetch(:hmr)
   end
 
+  # Returns whether CSS inlining is enabled
+  #
+  # When true, CSS is injected inline via JavaScript instead of being loaded
+  # as separate stylesheet files. This enables HMR for CSS.
+  # Can be overridden via SHAKAPACKER_DEV_SERVER_INLINE_CSS environment variable.
+  #
+  # @return [Boolean] true if CSS should be inlined
   def inline_css?
     case fetch(:inline_css)
     when false, "false"
@@ -76,6 +157,12 @@ class Shakapacker::DevServer
     end
   end
 
+  # Returns the environment variable prefix for dev server settings
+  #
+  # Environment variables for dev server settings use this prefix (default: "SHAKAPACKER_DEV_SERVER").
+  # For example, SHAKAPACKER_DEV_SERVER_PORT sets the port.
+  #
+  # @return [String] the env var prefix (typically "SHAKAPACKER_DEV_SERVER")
   def env_prefix
     config.dev_server.fetch(:env_prefix, DEFAULT_ENV_PREFIX)
   end

data/lib/shakapacker/dev_server_runner.rb

@@ -18,6 +18,8 @@ module Shakapacker
         exit(0)
       end
 
+      Shakapacker.ensure_node_env!
+
       # Check for --build flag
       build_index = argv.index("--build")
       if build_index
@@ -65,6 +67,8 @@ module Shakapacker
     end
 
     def self.run_with_build_config(argv, build_config)
+      Shakapacker.ensure_node_env!
+
       # Apply build config environment variables
       build_config[:environment].each do |key, value|
         ENV[key] = value.to_s

data/lib/shakapacker/doctor.rb

@@ -391,7 +391,7 @@ module Shakapacker
         expected_binstubs = {
           "bin/shakapacker" => "Main Shakapacker binstub",
           "bin/shakapacker-dev-server" => "Development server binstub",
-          "bin/export-bundler-config" => "Config export binstub"
+          "bin/shakapacker-config" => "Config export binstub"
         }
 
         expected_binstubs.each do |path, description|
@@ -914,7 +914,7 @@ module Shakapacker
             return unless doctor.config.config_path.exist?
 
             puts "\nConfiguration values for '#{doctor.config.env}' environment:"
-            config_data = doctor.config.send(:data)
+            config_data = doctor.config.data
 
             if config_data.any?
               print_config_data(config_data)
@@ -1013,7 +1013,7 @@ module Shakapacker
             binstubs = [
               "bin/shakapacker",
               "bin/shakapacker-dev-server",
-              "bin/export-bundler-config"
+              "bin/shakapacker-config"
             ]
 
             existing_binstubs = binstubs.select { |b| doctor.root_path.join(b).exist? }
@@ -1171,10 +1171,10 @@ module Shakapacker
             puts "  #{package_manager_install_command(package_manager)}"
             puts ""
             puts "For debugging configuration issues, export your webpack/rspack config:"
-            puts "  bin/export-bundler-config --doctor"
+            puts "  bin/shakapacker-config --doctor"
             puts "  (Exports annotated YAML configs for dev and production - best for troubleshooting)"
             puts ""
-            puts "  See 'bin/export-bundler-config --help' for more options"
+            puts "  See 'bin/shakapacker-config --help' for more options"
           end
 
           def package_manager_install_command(manager)