Refactor bundler detection and improve documentation

Code quality improvements:

1. **Extract bundler detection to shared utility**
   - Created config/webpack/bundlerUtils.js with getBundler(), isRspack(), getCssExtractPlugin()
   - Eliminates duplication across clientWebpackConfig.js and serverWebpackConfig.js
   - Provides single source of truth for bundler selection

2. **Improve error messages**
   - serverWebpackConfig.js now provides actionable error message with specific
     file paths and configuration to check when server-bundle entry is missing

3. **Enhance documentation**
   - Added "Verifying Patches" section to patches/README.md with concrete steps
   - Improved Sass modern API comments explaining why it's needed
   - Added common troubleshooting scenarios for patch application

All changes tested with both Webpack and Rspack bundlers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

config/webpack/bundlerUtils.js

@@ -0,0 +1,44 @@
+/**
+ * Bundler utilities for automatic Webpack/Rspack detection.
+ *
+ * Shakapacker 9.1+ supports both Webpack and Rspack as bundlers.
+ * The bundler is selected via config/shakapacker.yml:
+ *   assets_bundler: webpack  # or 'rspack'
+ */
+
+const { config } = require('shakapacker');
+
+/**
+ * Gets the appropriate bundler module based on shakapacker.yml configuration.
+ *
+ * @returns {Object} Either webpack or @rspack/core module
+ */
+const getBundler = () => {
+  return config.assets_bundler === 'rspack'
+    ? require('@rspack/core')
+    : require('webpack');
+};
+
+/**
+ * Checks if the current bundler is Rspack.
+ *
+ * @returns {boolean} True if using Rspack, false if using Webpack
+ */
+const isRspack = () => config.assets_bundler === 'rspack';
+
+/**
+ * Gets the appropriate CSS extraction plugin for the current bundler.
+ *
+ * @returns {Object} Either mini-css-extract-plugin (Webpack) or CssExtractRspackPlugin (Rspack)
+ */
+const getCssExtractPlugin = () => {
+  return isRspack()
+    ? getBundler().CssExtractRspackPlugin
+    : require('mini-css-extract-plugin');
+};
+
+module.exports = {
+  getBundler,
+  isRspack,
+  getCssExtractPlugin,
+};

config/webpack/clientWebpackConfig.js

@@ -1,15 +1,11 @@
 // The source code including full typescript support is available at:
 // https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh/blob/master/config/webpack/clientWebpackConfig.js
 
-const { config } = require('shakapacker');
 const commonWebpackConfig = require('./commonWebpackConfig');
-
-// Auto-detect bundler from shakapacker config and load the appropriate library
-const bundler = config.assets_bundler === 'rspack'
-  ? require('@rspack/core')
-  : require('webpack');
+const { getBundler } = require('./bundlerUtils');
 
 const configureClient = () => {
+  const bundler = getBundler();
   const clientConfig = commonWebpackConfig();
 
   clientConfig.plugins.push(

config/webpack/commonWebpackConfig.js

@@ -83,11 +83,15 @@ const commonWebpackConfig = () => {
         scssRule.use[sassLoaderIndex] = {
           loader: sassLoader,
           options: {
+            // Use modern API for better performance and to support sass-resources-loader
+            // The modern API uses the Sass JavaScript API instead of the legacy Node API
             api: 'modern'
           }
         };
       } else {
         sassLoader.options = sassLoader.options || {};
+        // Use modern API for better performance and to support sass-resources-loader
+        // The modern API uses the Sass JavaScript API instead of the legacy Node API
         sassLoader.options.api = 'modern';
       }
     }

config/webpack/serverWebpackConfig.js

@@ -4,12 +4,7 @@
 const path = require('path');
 const { config } = require('shakapacker');
 const commonWebpackConfig = require('./commonWebpackConfig');
-
-// Auto-detect bundler from shakapacker config and load the appropriate library
-// This allows the same config to work with both Webpack and Rspack
-const bundler = config.assets_bundler === 'rspack'
-  ? require('@rspack/core')
-  : require('webpack');
+const { getBundler } = require('./bundlerUtils');
 
 /**
  * Generates the server-side rendering (SSR) bundle configuration.
@@ -28,6 +23,8 @@ const bundler = config.assets_bundler === 'rspack'
  * @returns {Object} Webpack/Rspack configuration object for server bundle
  */
 const configureServer = () => {
+  const bundler = getBundler();
+
   // We need to use "merge" because the clientConfigObject, EVEN after running
   // toWebpackConfig() is a mutable GLOBAL. Thus any changes, like modifying the
   // entry value will result in changing the client config!
@@ -41,7 +38,9 @@ const configureServer = () => {
 
   if (!serverEntry['server-bundle']) {
     throw new Error(
-      "Create a pack with the file name 'server-bundle.js' containing all the server rendering files",
+      "Server bundle entry 'server-bundle' not found. " +
+      "Check that client/app/packs/server-bundle.js exists and is configured in shakapacker.yml. " +
+      "Verify nested_entries is set correctly and the file is in the source_entry_path.",
     );
   }
 

patches/README.md

@@ -31,6 +31,23 @@ import * as Json from "@glennsl/rescript-json-combinators/src/Json.bs.js";
 
 **TODO**: Check if patch is still needed when upgrading `@glennsl/rescript-json-combinators`
 
+## Verifying Patches
+
+After running `yarn install`, verify the patch was applied correctly:
+
+```bash
+# Run ReScript build - should succeed without errors
+yarn res:build
+
+# Expected output: Compiled successfully
+# If you see errors about missing .bs.js files, the patch wasn't applied
+```
+
+**Common issues**:
+- **Patch not applied**: Check that `postinstall` script ran (look for patch-package output during install)
+- **Build fails**: Run `yarn install --force` to reapply patches
+- **Wrong ReScript version**: Ensure ReScript version matches the patched package expectations
+
 ## How Patches Work
 
 1. **Creation**: When you modify a package in `node_modules/`, run: