shakapacker 9.1.0 → 9.2.0

data/docs/troubleshooting.md

@@ -17,12 +17,72 @@
 
 4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-shakapacker`
 
-5. ChatGPT and other AI tools can consume this output file. Change the NODE_ENV per your needs. Then upload the file to your favorite AI tool.
+5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/export-bundler-config` utility to export your complete resolved configuration. This is especially helpful for:
+
+   - **Migrations**: Comparing configurations before and after migrating between webpack and rspack, or between different Shakapacker versions
+   - **Debugging**: Inspecting the exact configuration webpack/rspack is using, including all merged settings
+   - **AI Analysis**: Uploading the exported config to ChatGPT or other AI tools for troubleshooting
+
+   **Installation**: The utility is installed when you run `rake shakapacker:binstubs` or can be used directly via `rake shakapacker:export_bundler_config`.
+
+   **RECOMMENDED - Quick troubleshooting:**
+
+   ```bash
+   # Install the binstub (one-time setup)
+   rake shakapacker:binstubs
+
+   # Export EVERYTHING for troubleshooting (dev + prod, annotated YAML)
+   bin/export-bundler-config --doctor
+   # Creates: webpack-development-client.yaml, webpack-development-server.yaml,
+   #          webpack-production-client.yaml, webpack-production-server.yaml
+   ```
+
+   **Other usage examples:**
+
+   ```bash
+   # Save current environment configs with auto-generated names
+   bin/export-bundler-config --save
+   # Creates: webpack-development-client.yaml, webpack-development-server.yaml
+
+   # Save to specific directory
+   bin/export-bundler-config --save --save-dir=./debug-configs
+
+   # Export only client config for production
+   bin/export-bundler-config --save --env=production --client-only
+   # Creates: webpack-production-client.yaml
+
+   # Compare development vs production configs
+   bin/export-bundler-config --save --save-dir=./configs
+   diff configs/webpack-development-client.yaml configs/webpack-production-client.yaml
+
+   # View config in terminal (no files created)
+   bin/export-bundler-config
+
+   # Export without inline documentation annotations
+   bin/export-bundler-config --save --no-annotate
+
+   # Export in JSON format for programmatic analysis
+   bin/export-bundler-config --save --format=json
    ```
+
+   **Config files are automatically named:** `{bundler}-{env}-{type}.{ext}`
+
+   - Examples: `webpack-development-client.yaml`, `rspack-production-server.yaml`
+   - YAML format includes inline documentation explaining each config key
+   - Separate files for client and server bundles (cleaner than combined)
+
+   See `bin/export-bundler-config --help` for all available options.
+
+6. Generate webpack stats for build analysis (useful for bundle size optimization):
+
+   ```bash
    NODE_ENV=development bin/shakapacker --profile --json > /tmp/webpack-stats.json
    ```
 
+   ChatGPT and other AI tools can consume this output file. Change the NODE_ENV per your needs.
+
 ## Incorrect peer dependencies
+
 Shakapacker uses peer dependencies to make it easier to manage what versions are being used for your app, which is especially
 useful for patching security vulnerabilities. However, not all package managers will actually enforce these versions - notably,
 Yarn will omit a warning rather than erroring if you forget to update a peer dependency:
@@ -32,6 +92,7 @@ warning " > shakapacker@6.1.1" has incorrect peer dependency "compression-webpac
 ```
 
 This omission resulted in an error in the browser:
+
 ```
 Failed to load resource: net::ERR_CONTENT_DECODING_FAILED
 ```
@@ -40,6 +101,40 @@ The error was caused by an old version of the peer dependency `webpack-compressi
 
 So, be sure to investigate warnings from `yarn install`!
 
+## NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+
+If you see this error during deployment (especially on Heroku with a staging environment):
+
+```
+NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+  from shakapacker/configuration.rb:XXX:in 'load'
+```
+
+This happens when deploying to a custom Rails environment (like `staging`) that isn't explicitly defined in your `config/shakapacker.yml` file.
+
+**Solution:** This was fixed in Shakapacker v9.1.1+. Upgrade to the latest version:
+
+```ruby
+# Gemfile
+gem 'shakapacker', '~> 9.1'
+```
+
+After upgrading, Shakapacker will automatically fall back to sensible defaults when your environment isn't defined:
+
+1. First tries your environment (e.g., `staging`)
+2. Falls back to `production` configuration
+
+**Alternative:** If you can't upgrade immediately, explicitly add your environment to `config/shakapacker.yml`:
+
+```yaml
+staging:
+  <<: *default
+  compile: false
+  cache_manifest: true
+```
+
+See the [deployment guide](./deployment.md#custom-rails-environments-eg-staging) for more details.
+
 ## ENOENT: no such file or directory - node-sass
 
 If you get the error `ENOENT: no such file or directory - node-sass` on deploy with
@@ -54,7 +149,7 @@ thing, like Heroku.
 
 However, if you get this on local development, or not during a deploy then you
 may need to rebuild `node-sass`. It's a bit of a weird error; basically, it
-can't find the `node-sass` binary.  An easy solution is to create a postinstall
+can't find the `node-sass` binary. An easy solution is to create a postinstall
 hook to ensure `node-sass` is rebuilt whenever new modules are installed.
 
 In `package.json`:
@@ -67,19 +162,18 @@ In `package.json`:
 
 ## Can't find hello_react.js in manifest.json
 
-* If you get this error `Can't find hello_react.js in manifest.json`
-when loading a view in the browser it's because webpack is still compiling packs.
-Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
-however since this file is generated after packs are compiled by webpack. So,
-if you load a view in browser whilst webpack is compiling you will get this error.
-Therefore, make sure webpack
-(i.e `./bin/shakapacker-dev-server`) is running and has
-completed the compilation successfully before loading a view.
-
+- If you get this error `Can't find hello_react.js in manifest.json`
+  when loading a view in the browser it's because webpack is still compiling packs.
+  Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
+  however since this file is generated after packs are compiled by webpack. So,
+  if you load a view in browser whilst webpack is compiling you will get this error.
+  Therefore, make sure webpack
+  (i.e `./bin/shakapacker-dev-server`) is running and has
+  completed the compilation successfully before loading a view.
 
 ## throw er; // Unhandled 'error' event
 
-* If you get this error while trying to use Elm, try rebuilding Elm. You can do
+- If you get this error while trying to use Elm, try rebuilding Elm. You can do
   so with a postinstall hook in your `package.json`:
 
 ```json
@@ -90,9 +184,9 @@ completed the compilation successfully before loading a view.
 
 ## webpack or webpack-dev-server not found
 
-* This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
+- This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
 
-* If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
+- If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
 
 ```bash
 bundle config --delete bin
@@ -137,6 +231,7 @@ chmod +x $HOME/your_rails_app/node_modules/.bin/elm-make
 ```
 
 ## Rake assets:precompile fails. ExecJS::RuntimeError
+
 This error occurs because you are trying to minify by `terser` a pack that's already been minified by Shakapacker. To avoid this conflict and prevent appearing of `ExecJS::RuntimeError` error, you will need to disable uglifier from Rails config:
 
 ```ruby
@@ -152,10 +247,11 @@ Rails.application.config.assets.js_compressor = Uglifier.new(harmony: true)
 ### Angular: WARNING in ./node_modules/@angular/core/esm5/core.js, Critical dependency: the request of a dependency is an expression
 
 To silent these warnings, please update `config/webpack/webpack.config.js`:
+
 ```js
-const webpack = require('webpack')
-const { resolve } = require('path')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { resolve } = require("path")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
@@ -192,6 +288,7 @@ Thus ProvidePlugin manages build-time dependencies to global symbols whereas the
 **You don't need to assign dependencies on `window`.**
 
 For instance, with [jQuery](https://jquery.com/):
+
 ```diff
 // app/javascript/entrypoints/application.js
 
@@ -200,19 +297,20 @@ For instance, with [jQuery](https://jquery.com/):
 ```
 
 Instead do:
+
 ```js
 // config/webpack/webpack.config.js
 
-const webpack = require('webpack')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
     new webpack.ProvidePlugin({
-      $: 'jquery',
-      jQuery: 'jquery',
+      $: "jquery",
+      jQuery: "jquery"
     })
-  ],
+  ]
 })
 ```
 
@@ -225,7 +323,7 @@ application is using your staging `config.asset_host` host when using
 
 This can be fixed by setting the environment variable `SHAKAPACKER_ASSET_HOST` to
 an empty string where your assets are compiled. On Heroku this is done under
-*Settings* -> *Config Vars*.
+_Settings_ -> _Config Vars_.
 
 This way shakapacker won't hard-code the CDN host into the manifest file used by
 `javascript_pack_tag`, but instead fetch the CDN host at runtime, resolving the
@@ -243,6 +341,7 @@ In order to generate the storage path, we rely on the filename that's [provided
 This usually works out of the box. There's a potential problem however, if you use the [context setting](https://webpack.js.org/configuration/entry-context/#context) in your webpack config. By default this is set to current Node working directory/project root.
 
 If you were to override it like:
+
 ```
 {
   context: path.resolve(__dirname, '../../app/javascript')
@@ -252,12 +351,14 @@ If you were to override it like:
 Then the filename available in the rule generator will be relative to that directory.
 
 This means for example:
+
 - a static asset from `node_modules` folder could end up being referenced with path of `../../node_modules/some_module/static_file.jpg` rather than simply `node_modules/some_module/static_file.jpg`.
 - a static asset in one of the `additional_paths`, example `app/assets/images/image.jpg`, would end up being referenced with path of `../assets/images/image.jpg`.
 
 Those paths are later passed to [output path generation in the rule](https://github.com/shakacode/shakapacker/blob/e52b335dbabfb934fe7d3076a8322b97d5ef3470/package/rules/file.js#L25-L26), where we would end up with a path like `static/../../node_modules/some_module/static_file.jpg`, resulting in the file being output in a location two directories above the desired path.
 
 You can avoid this by:
+
 - not using overridden `context` in your webpack config, if there's no good reason for it.
 - using custom Webpack config to modify the static file rule, following a similar process as outlined in the [Webpack Configuration](https://github.com/shakacode/shakapacker/blob/main/README.md#webpack-configuration) section of the readme.
 

data/lib/install/bin/export-bundler-config

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// Minimal shim - all logic is in the TypeScript module
+const { run } = require('shakapacker/configExporter')
+
+run(process.argv.slice(2))
+  .then((exitCode) => process.exit(exitCode))
+  .catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })

data/lib/install/bin/shakapacker

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ENV["RAILS_ENV"] ||= "development"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 ENV["APP_ROOT"] ||= File.expand_path("..", __dir__)
 
 require "bundler/setup"

data/lib/install/bin/shakapacker-dev-server

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ENV["RAILS_ENV"] ||= "development"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 
 require "bundler/setup"
 require "shakapacker"

data/lib/shakapacker/bundler_switcher.rb

@@ -241,6 +241,13 @@ module Shakapacker
             raise "Failed to install prod dependencies"
           end
         end
+
+        # Run a full install to ensure optional dependencies (like native bindings) are properly resolved
+        # This is especially important for packages like @rspack/core that use platform-specific native modules
+        unless package_json.manager.install
+          puts "❌ Failed to run full install to resolve optional dependencies"
+          raise "Failed to run full install"
+        end
       end
 
       def get_package_json

data/lib/shakapacker/configuration.rb

@@ -255,7 +255,21 @@ class Shakapacker::Configuration
       rescue ArgumentError
         YAML.load_file(config_path.to_s)
       end
-      symbolized_config = config[env].deep_symbolize_keys
+
+      # Try to find environment-specific configuration with fallback
+      # Fallback order: requested env → production
+      if config[env]
+        env_config = config[env]
+      elsif config["production"]
+        log_fallback(env, "production")
+        env_config = config["production"]
+      else
+        # No suitable configuration found - rely on bundled defaults
+        log_fallback(env, "none (will use bundled defaults)")
+        env_config = nil
+      end
+
+      symbolized_config = env_config&.deep_symbolize_keys || {}
 
       return symbolized_config
     rescue Errno::ENOENT => e
@@ -280,7 +294,10 @@ class Shakapacker::Configuration
         rescue ArgumentError
           YAML.load_file(path)
         end
-        HashWithIndifferentAccess.new(config[env] || config[Shakapacker::DEFAULT_ENV])
+        # Load defaults from bundled shakapacker.yml (always has all environments)
+        # Note: This differs from load() which reads user's config and may be missing environments
+        # Fallback to production ensures staging and other custom envs get production-like defaults
+        HashWithIndifferentAccess.new(config[env] || config["production"])
       end
     end
 
@@ -289,4 +306,13 @@ class Shakapacker::Configuration
 
       path
     end
+
+    def log_fallback(requested_env, fallback_env)
+      return unless Shakapacker.logger
+
+      Shakapacker.logger.info(
+        "Shakapacker environment '#{requested_env}' not found in #{config_path}, " \
+        "falling back to '#{fallback_env}'"
+      )
+    end
 end

data/lib/shakapacker/doctor.rb

@@ -327,6 +327,11 @@ module Shakapacker
         unless binstub_path.exist?
           @warnings << "Shakapacker binstub not found at bin/shakapacker. Run 'rails shakapacker:binstubs' to create it."
         end
+
+        export_config_binstub = root_path.join("bin/export-bundler-config")
+        unless export_config_binstub.exist?
+          @warnings << "Config export binstub not found at bin/export-bundler-config. Run 'rails shakapacker:binstubs' to create it."
+        end
       end
 
       def check_javascript_transpiler_dependencies
@@ -830,6 +835,11 @@ module Shakapacker
             if binstub_path.exist?
               puts "✓ Shakapacker binstub found"
             end
+
+            export_config_binstub = doctor.root_path.join("bin/export-bundler-config")
+            if export_config_binstub.exist?
+              puts "✓ Config export binstub found"
+            end
           end
 
           def print_info_messages
@@ -873,6 +883,12 @@ module Shakapacker
             package_manager = doctor.send(:package_manager)
             puts "To fix missing dependencies, run:"
             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 "  (Exports annotated YAML configs for dev and production - best for troubleshooting)"
+            puts ""
+            puts "  See 'bin/export-bundler-config --help' for more options"
           end
 
           def package_manager_install_command(manager)

data/lib/shakapacker/rspack_runner.rb

@@ -6,7 +6,7 @@ module Shakapacker
   class RspackRunner < Shakapacker::Runner
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
       new(argv).run
     end
 

data/lib/shakapacker/runner.rb

@@ -24,7 +24,7 @@ module Shakapacker
     ].freeze
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
 
       # Create a single runner instance to avoid loading configuration twice.
       # We extend it with the appropriate build command based on the bundler type.

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.1.0".freeze
+  VERSION = "9.2.0".freeze
 end

data/lib/shakapacker/webpack_runner.rb

@@ -6,7 +6,7 @@ module Shakapacker
   class WebpackRunner < Shakapacker::Runner
     def self.run(argv)
       $stdout.sync = true
-      ENV["NODE_ENV"] ||= (ENV["RAILS_ENV"] == "production") ? "production" : "development"
+      Shakapacker.ensure_node_env!
       new(argv).run
     end
 

data/lib/shakapacker.rb

@@ -7,6 +7,9 @@ module Shakapacker
   extend self
 
   DEFAULT_ENV = "development".freeze
+  # Environments that use their RAILS_ENV value for NODE_ENV
+  # All other environments (production, staging, etc.) use "production" for webpack optimizations
+  DEV_TEST_ENVS = %w[development test].freeze
 
   def instance=(instance)
     @instance = instance
@@ -24,6 +27,13 @@ module Shakapacker
     ENV["NODE_ENV"] = original
   end
 
+  # Set NODE_ENV based on RAILS_ENV if not already set
+  # - development/test environments use their RAILS_ENV value
+  # - all other environments (production, staging, etc.) use "production" for webpack optimizations
+  def ensure_node_env!
+    ENV["NODE_ENV"] ||= DEV_TEST_ENVS.include?(ENV["RAILS_ENV"]) ? ENV["RAILS_ENV"] : "production"
+  end
+
   def ensure_log_goes_to_stdout
     old_logger = Shakapacker.logger
     Shakapacker.logger = Logger.new(STDOUT)

data/lib/tasks/shakapacker/export_bundler_config.rake

@@ -0,0 +1,72 @@
+namespace :shakapacker do
+  desc <<~DESC
+    Export webpack or rspack configuration for debugging and analysis
+
+    Exports your resolved webpack/rspack configuration in human-readable formats.
+    Use this to debug configuration issues, compare environments, or analyze
+    client vs server bundle differences.
+
+    Usage:
+      rails shakapacker:export_bundler_config [OPTIONS]
+      rake shakapacker:export_bundler_config -- [OPTIONS]
+
+    Quick Start (Recommended):
+      rails shakapacker:export_bundler_config --doctor
+
+    This exports all configs (dev + prod, client + server) to shakapacker-config-exports/
+    directory in annotated YAML format - perfect for troubleshooting.
+
+    Common Options:
+      --doctor              Export everything for troubleshooting (recommended)
+      --save                Save current environment configs to files
+      --save-dir=<dir>      Custom output directory (requires --save)
+      --env=development|production|test    Specify environment
+      --client-only         Export only client config
+      --server-only         Export only server config
+      --format=yaml|json|inspect           Output format
+      --help, -h            Show detailed help
+
+    Examples:
+      # Export all configs for troubleshooting
+      rails shakapacker:export_bundler_config --doctor
+
+      # Save production client config
+      rails shakapacker:export_bundler_config --save --env=production --client-only
+
+      # View development config in terminal
+      rails shakapacker:export_bundler_config
+
+      # Show detailed help
+      rails shakapacker:export_bundler_config --help
+
+    Note: When using 'rake', you must use '--' to separate rake options from task arguments.
+          Example: rake shakapacker:export_bundler_config -- --doctor
+
+    The task automatically falls back to the gem version if bin/export-bundler-config
+    binstub is not installed. To install all binstubs, run: rails shakapacker:binstubs
+  DESC
+  task :export_bundler_config do
+    # Try to use the binstub if it exists, otherwise use the gem's version
+    bin_path = Rails.root.join("bin/export-bundler-config")
+
+    unless File.exist?(bin_path)
+      # Binstub not installed, use the gem's version directly
+      gem_bin_path = File.expand_path("../../install/bin/export-bundler-config", __dir__)
+
+      $stderr.puts "Note: bin/export-bundler-config binstub not found."
+      $stderr.puts "Using gem version directly. To install the binstub, run: rake shakapacker:binstubs"
+      $stderr.puts ""
+
+      Dir.chdir(Rails.root) do
+        exec("node", gem_bin_path, *ARGV[1..])
+      end
+    else
+      # Pass through command-line arguments after the task name
+      # Use exec to replace the rake process with the export script
+      # This ensures proper exit codes and signal handling
+      Dir.chdir(Rails.root) do
+        exec(bin_path.to_s, *ARGV[1..])
+      end
+    end
+  end
+end