Add test coverage and improve documentation

Test Coverage:
- Added unit tests for bundlerUtils.js (6 tests, all passing)
- Added RSpec integration test for bundler switching
- Verified both Webpack and Rspack can build successfully

Documentation Improvements:
- Enhanced SWC config comments explaining why classic React runtime is used
- Improved serverWebpackConfig error message to show:
  * Expected file path with actual config values
  * Current source_path and source_entry_path
  * Step-by-step verification checklist

All tests passing (14 total: 4 test suites, 14 tests).

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

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

Author: justin808

client/__tests__/webpack/bundlerUtils.spec.js

@@ -0,0 +1,107 @@
+/**
+ * Unit tests for bundlerUtils.js
+ * Tests bundler auto-detection and helper functions
+ *
+ * Note: These tests verify the bundler selection logic without actually
+ * loading Rspack (which requires Node.js globals not available in jsdom).
+ */
+
+// Mock the bundler packages to avoid loading them
+jest.mock('webpack', () => ({
+  ProvidePlugin: class MockProvidePlugin {},
+  optimize: { LimitChunkCountPlugin: class MockLimitChunkCount {} },
+}));
+
+jest.mock('@rspack/core', () => ({
+  ProvidePlugin: class MockRspackProvidePlugin {},
+  CssExtractRspackPlugin: class MockCssExtractRspackPlugin {},
+  optimize: { LimitChunkCountPlugin: class MockRspackLimitChunkCount {} },
+}));
+
+jest.mock('mini-css-extract-plugin', () => class MiniCssExtractPlugin {});
+
+describe('bundlerUtils', () => {
+  let mockConfig;
+
+  beforeEach(() => {
+    // Reset module cache
+    jest.resetModules();
+
+    // Create fresh mock config
+    mockConfig = { assets_bundler: 'webpack' };
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getBundler()', () => {
+    it('returns webpack when assets_bundler is webpack', () => {
+      mockConfig.assets_bundler = 'webpack';
+      jest.doMock('shakapacker', () => ({ config: mockConfig }));
+      const utils = require('../../../config/webpack/bundlerUtils');
+
+      const bundler = utils.getBundler();
+
+      expect(bundler).toBeDefined();
+      expect(bundler.ProvidePlugin).toBeDefined();
+      expect(bundler.ProvidePlugin.name).toBe('MockProvidePlugin');
+    });
+
+    it('returns rspack when assets_bundler is rspack', () => {
+      mockConfig.assets_bundler = 'rspack';
+      jest.doMock('shakapacker', () => ({ config: mockConfig }));
+      const utils = require('../../../config/webpack/bundlerUtils');
+
+      const bundler = utils.getBundler();
+
+      expect(bundler).toBeDefined();
+      // Rspack has CssExtractRspackPlugin
+      expect(bundler.CssExtractRspackPlugin).toBeDefined();
+      expect(bundler.CssExtractRspackPlugin.name).toBe('MockCssExtractRspackPlugin');
+    });
+  });
+
+  describe('isRspack()', () => {
+    it('returns false when assets_bundler is webpack', () => {
+      mockConfig.assets_bundler = 'webpack';
+      jest.doMock('shakapacker', () => ({ config: mockConfig }));
+      const utils = require('../../../config/webpack/bundlerUtils');
+
+      expect(utils.isRspack()).toBe(false);
+    });
+
+    it('returns true when assets_bundler is rspack', () => {
+      mockConfig.assets_bundler = 'rspack';
+      jest.doMock('shakapacker', () => ({ config: mockConfig }));
+      const utils = require('../../../config/webpack/bundlerUtils');
+
+      expect(utils.isRspack()).toBe(true);
+    });
+  });
+
+  describe('getCssExtractPlugin()', () => {
+    it('returns mini-css-extract-plugin when using webpack', () => {
+      mockConfig.assets_bundler = 'webpack';
+      jest.doMock('shakapacker', () => ({ config: mockConfig }));
+      const utils = require('../../../config/webpack/bundlerUtils');
+
+      const plugin = utils.getCssExtractPlugin();
+
+      expect(plugin).toBeDefined();
+      expect(plugin.name).toBe('MiniCssExtractPlugin');
+    });
+
+    it('returns CssExtractRspackPlugin when using rspack', () => {
+      mockConfig.assets_bundler = 'rspack';
+      jest.doMock('shakapacker', () => ({ config: mockConfig }));
+      const utils = require('../../../config/webpack/bundlerUtils');
+
+      const plugin = utils.getCssExtractPlugin();
+
+      expect(plugin).toBeDefined();
+      // Rspack plugin class name
+      expect(plugin.name).toBe('MockCssExtractRspackPlugin');
+    });
+  });
+});

config/swc.config.js

@@ -10,7 +10,11 @@ const customConfig = {
       loose: false,
       transform: {
         react: {
-          // Use classic runtime for better SSR compatibility with React on Rails
+          // Use classic runtime for SSR compatibility with React on Rails
+          // This ensures React is explicitly imported in each component file, which
+          // provides better compatibility with server-side rendering in Rails.
+          // Note: React 19 supports automatic runtime with SSR, but classic runtime
+          // is more explicit and avoids potential issues with different React versions.
           runtime: 'classic',
           // Enable React Fast Refresh in development
           refresh: env.isDevelopment && env.runningWebpackDevServer,

config/webpack/serverWebpackConfig.js

@@ -37,10 +37,19 @@ const configureServer = () => {
   };
 
   if (!serverEntry['server-bundle']) {
+    const sourcePath = config.source_path || 'client/app';
+    const entryPath = config.source_entry_path || 'packs';
+    const fullPath = `${sourcePath}/${entryPath}/server-bundle.js`;
+
     throw new Error(
-      "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.",
+      `Server bundle entry 'server-bundle' not found.\n` +
+      `Expected file: ${fullPath}\n` +
+      `Current source_path: ${config.source_path}\n` +
+      `Current source_entry_path: ${config.source_entry_path}\n` +
+      `Verify:\n` +
+      `1. The server-bundle.js file exists at the expected location\n` +
+      `2. nested_entries is configured correctly in shakapacker.yml\n` +
+      `3. The file is properly exported from your entry point`,
     );
   }
 

spec/webpack/bundler_switching_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'yaml'
+
+RSpec.describe 'Bundler Switching', type: :feature do
+  let(:shakapacker_config_path) { Rails.root.join('config', 'shakapacker.yml') }
+  let(:original_config) { YAML.load_file(shakapacker_config_path) }
+
+  after do
+    # Restore original config after each test
+    File.write(shakapacker_config_path, YAML.dump(original_config))
+  end
+
+  describe 'switching between webpack and rspack' do
+    it 'successfully builds with webpack' do
+      # Set bundler to webpack
+      config = original_config
+      config['default']['assets_bundler'] = 'webpack'
+      File.write(shakapacker_config_path, YAML.dump(config))
+
+      # Run build
+      output = `NODE_ENV=test RAILS_ENV=test bin/shakapacker 2>&1`
+
+      expect($CHILD_STATUS.success?).to be true
+      expect(output).to include('webpack')
+      expect(output).to include('compiled successfully')
+    end
+
+    it 'successfully builds with rspack' do
+      # Set bundler to rspack
+      config = original_config
+      config['default']['assets_bundler'] = 'rspack'
+      File.write(shakapacker_config_path, YAML.dump(config))
+
+      # Run build
+      output = `NODE_ENV=test RAILS_ENV=test bin/shakapacker 2>&1`
+
+      expect($CHILD_STATUS.success?).to be true
+      expect(output).to include('Rspack')
+      expect(output).to include('compiled successfully')
+    end
+
+    it 'produces functional bundles with both bundlers' do
+      bundlers = %w[webpack rspack]
+
+      bundlers.each do |bundler|
+        # Set bundler
+        config = original_config
+        config['default']['assets_bundler'] = bundler
+        File.write(shakapacker_config_path, YAML.dump(config))
+
+        # Build
+        `NODE_ENV=test RAILS_ENV=test bin/shakapacker 2>&1`
+        expect($CHILD_STATUS.success?).to be true
+
+        # Verify manifest exists
+        manifest_path = Rails.root.join('public', 'packs-test', 'manifest.json')
+        expect(File.exist?(manifest_path)).to be true
+
+        # Verify server bundle exists
+        server_bundle_path = Rails.root.join('ssr-generated', 'server-bundle.js')
+        expect(File.exist?(server_bundle_path)).to be true
+      end
+    end
+  end
+end