shakapacker 9.3.0.beta.7 → 9.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d74b7ba9b6d6c78f1909339be00ce6d88a6d3f8e8cd64ada499992c3bf6691f
-  data.tar.gz: f51ffe665f554536b8defcf139399eb6f6630c61f427a4be9c88aebf14404b25
+  metadata.gz: 1e94cd0b57c81506b9cab0fb54cc6a876276c3f3331686cf921fa4485442ab99
+  data.tar.gz: 292b0623b5241014524f9227ed2a1009752de53e8db610344567f761c7b8b4bc
 SHA512:
-  metadata.gz: 7fa1c2252b25cc3e265e6375561e0be38d1656604e6bf873eb1d6b25d41478bc48c530e8bcac3a05f6d09f7569f988a65cb52609564c87ea35f657bda3baed27
-  data.tar.gz: a322b6a94de55f7f8da67d54778e6f455726d4778576e5ff689e2874d68f58b8613260d683d93e019d48d44eeeb9a46a7094be12cb7dbaea76824e688350994a
+  metadata.gz: 6dd27e8501b86f06fbefd6f71a2a3ceb9c975dd28f140251ab03cf6bd972b631db35666e9c05bdf434bf2ac13c1568f57bd73a7841efb38befb541f2d0cfaeb1
+  data.tar.gz: 623358b9543ddcad7586a68e03aba4848151d4490a298c39320a395cb4aa450783a91f4c21d53b491868600d57e054f3f52bcb72eb244f25ebc0e8cb20ff1738

data/CHANGELOG.md

@@ -11,132 +11,69 @@
 
 Changes since the last non-beta release.
 
-### Added
+### Fixed
 
-- **`--help=verbose` flag support** to display all available webpack/rspack bundler options. [PR #763](https://github.com/shakacode/shakapacker/pull/763) by [justin808](https://github.com/justin808).
-  - Run `bin/shakapacker --help=verbose` to see complete bundler documentation
-  - Shows all webpack CLI options when using webpack
-  - Useful for discovering advanced bundler configuration options
-- **Support for arbitrary output names in build configurations**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808).
-  - `outputs` array now accepts any custom names (e.g., `client-modern`, `client-legacy`, `server-bundle`)
-  - Previously limited to only `client`, `server`, and `all`
-  - Enables better organization of multi-config webpack builds
-- **Enhanced error reporting in config exporter**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808).
-  - Shows detailed environment variable state when config functions fail
-  - Provides actionable suggestions based on error patterns (e.g., missing NODE_ENV)
-  - Improved formatting with clear sections for easier debugging
-- **Config count validation for build outputs**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808).
-  - Validates webpack/rspack config array length matches `outputs` array
-  - Clear error messages when mismatch detected
-  - Suggests fixes with example configuration
-- **HTTP 103 Early Hints support** for faster asset loading. [PR #722](https://github.com/shakacode/shakapacker/pull/722) by [justin808](https://github.com/justin808). Fixes [#721](https://github.com/shakacode/shakapacker/issues/721).
-  - **Automatic sending**: Early hints are sent automatically when `early_hints: enabled: true` in `shakapacker.yml`
-  - **Per-page configuration**: Configure hints per-controller/action with `preload`/`prefetch`/`none` options
-  - **Hero image/video preloading**: Use Rails' built-in `preload_link_tag` (automatically sends early hints)
-  - **Zero-config upgrade**: No changes to layouts or views needed - just enable the config!
-  - Works seamlessly with existing `append_javascript_pack_tag` / `append_stylesheet_pack_tag` pattern
-  - Automatically discovers packs from queues populated by views/partials
-  - New `configure_pack_early_hints` class method for controller-level configuration
-  - New `skip_send_pack_early_hints` helper to opt-out for specific controllers (e.g., JSON APIs)
-  - Optional manual control: `configure_early_hints` can be called in controllers or views
-  - Added `early_hints:` option to `javascript_pack_tag` for per-tag control
-  - New `early_hints` configuration in `shakapacker.yml` with per-environment settings (`enabled: false` by default)
-  - Requires Rails 5.2+ and HTTP/2-capable server (e.g., Puma 5+)
-  - Browser support: All modern browsers (Chrome/Edge/Firefox 103+, Safari 16.4+)
-  - Gracefully degrades if not supported
-  - **Performance note**: May improve or hurt page load performance depending on content - careful testing advised
-  - See [Early Hints Guide](docs/early_hints.md) for detailed usage and advanced patterns
-
-## [v9.3.0-beta.5] - October 18, 2025
+- **Enhanced error handling for better security and debugging**. [PR #786](https://github.com/shakacode/shakapacker/pull/786) by [justin808](https://github.com/justin808).
+  - Path validation now properly reports permission errors instead of silently handling them
+  - Module loading errors now include original error context for easier troubleshooting
+  - Improved security by only catching ENOENT errors in path resolution, rethrowing permission and access errors
+  - Better type safety with custom ErrorWithCause interface and optional chaining for error.code checks
+- **Improved type safety and error handling in configExporter module**. [PR #778](https://github.com/shakacode/shakapacker/pull/778) by [justin808](https://github.com/justin808). Resolves [#707](https://github.com/shakacode/shakapacker/issues/707).
+  - Enhanced type safety across configFile, buildValidator, and yamlSerializer modules
+  - Improved error message preservation for webpack/rspack build failures
+  - Fixed edge cases in YAML serialization (empty arrays, malformed objects)
+  - More robust constructor name detection for object serialization
+  - Better handling of Symbol, BigInt, and edge case types
+- **Default template no longer triggers production warning**. [PR #774](https://github.com/shakacode/shakapacker/pull/774) by [justin808](https://github.com/justin808). Fixes [#703](https://github.com/shakacode/shakapacker/issues/703).
+  - Changed default `useContentHash` to `true` in `shakapacker.yml` template
+  - Eliminates confusing warning about `useContentHash: false` not being allowed in production
+  - Development environment now explicitly sets `useContentHash: false` for faster builds
+  - Production no longer needs explicit override since it inherits the correct default
+
+## [v9.3.0] - October 28, 2025
 
 ### Added
 
-- **New `precompile_hook` configuration option** to run custom commands during asset precompilation. [PR #678](https://github.com/shakacode/shakapacker/pull/678) by [justin808](https://github.com/justin808).
-  - Allows executing custom scripts or tasks during the precompile process
-  - Configure in `shakapacker.yml` with `precompile_hook: "command to run"`
-- **New `assets_bundler_config_path` configuration option** for custom bundler config locations. [PR #710](https://github.com/shakacode/shakapacker/pull/710) by [justin808](https://github.com/justin808).
-  - Allows specifying a custom path for webpack/rspack configuration files
-  - Useful for complex project structures or shared configurations
-- **YAML output format support for `bin/export-bundler-config`**. [PR #704](https://github.com/shakacode/shakapacker/pull/704) by [justin808](https://github.com/justin808).
-  - New `--format yaml` option exports bundler configuration as YAML
-  - Easier to read than JSON for debugging and documentation
-- **Custom help messages for `bin/shakapacker` commands**. [PR #702](https://github.com/shakacode/shakapacker/pull/702) by [justin808](https://github.com/justin808).
-  - Improved help output for better command discoverability
-  - Clear usage examples and option descriptions
-- **HMR client config export in doctor mode**. [PR #701](https://github.com/shakacode/shakapacker/pull/701) by [justin808](https://github.com/justin808).
-  - `bin/export-bundler-config --doctor` now includes HMR client configuration
-  - Helps debug Hot Module Replacement issues
-- **Build timing logs** for webpack and rspack. [PR #706](https://github.com/shakacode/shakapacker/pull/706) by [justin808](https://github.com/justin808).
-  - Shows duration of build operations
-  - Helps identify performance bottlenecks
-- **Named build configurations with `--build` flag**. [PR #728](https://github.com/shakacode/shakapacker/pull/728) by [justin808](https://github.com/justin808).
-  - Allows specifying custom build configurations: `bin/shakapacker --build=production` or `bin/shakapacker --build=test`
-  - Useful for creating specialized build configurations for different deployment environments
-- **Build validation in `bin/export-bundler-config`**. [PR #717](https://github.com/shakacode/shakapacker/pull/717) by [justin808](https://github.com/justin808).
-  - Validates webpack/rspack configuration before export to catch errors early
-  - Provides clear error messages for configuration issues
-- **Backward compatibility for rspack config in `config/webpack/`**. [PR #734](https://github.com/shakacode/shakapacker/pull/734) by [justin808](https://github.com/justin808).
-  - Rspack configurations can now be placed in `config/webpack/` directory for easier migration
-  - Maintains compatibility with existing project structures
-- Added Knip for detecting dead code to CI. [PR #675](https://github.com/shakacode/shakapacker/pull/675) by [justin808](https://github.com/justin808).
+- **HTTP 103 Early Hints support** for faster asset loading. [PR #722](https://github.com/shakacode/shakapacker/pull/722) by [justin808](https://github.com/justin808). Automatically sends early hints when `early_hints: enabled: true` in `shakapacker.yml`. Works with `append_javascript_pack_tag`/`append_stylesheet_pack_tag`, supports per-controller/action configuration, and includes helpers like `configure_pack_early_hints` and `skip_send_pack_early_hints`. Requires Rails 5.2+ and HTTP/2-capable server. See [Early Hints Guide](docs/early_hints.md).
+- **`--help=verbose` flag** to display all available webpack/rspack bundler options. [PR #763](https://github.com/shakacode/shakapacker/pull/763) by [justin808](https://github.com/justin808). Run `bin/shakapacker --help=verbose` to see complete bundler documentation.
+- **Support for arbitrary output names in build configurations**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808). The `outputs` array now accepts any custom names (e.g., `client-modern`, `client-legacy`, `server-bundle`) instead of being limited to only `client`, `server`, and `all`.
+- **Enhanced error reporting in config exporter**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808). Shows detailed environment variable state when config functions fail and provides actionable suggestions based on error patterns.
+- **Config count validation for build outputs**. [PR #752](https://github.com/shakacode/shakapacker/pull/752) by [justin808](https://github.com/justin808). Validates webpack/rspack config array length matches `outputs` array with clear error messages and suggested fixes.
+- **`precompile_hook` configuration option** to run custom commands during asset precompilation. [PR #678](https://github.com/shakacode/shakapacker/pull/678) by [justin808](https://github.com/justin808). Configure in `shakapacker.yml` with `precompile_hook: "command to run"`.
+- **`assets_bundler_config_path` configuration option** for custom bundler config locations. [PR #710](https://github.com/shakacode/shakapacker/pull/710) by [justin808](https://github.com/justin808). Allows specifying a custom path for webpack/rspack configuration files.
+- **YAML output format support for `bin/shakapacker-config`** (formerly `bin/export-bundler-config`). [PR #704](https://github.com/shakacode/shakapacker/pull/704) by [justin808](https://github.com/justin808). New `--format yaml` option exports bundler configuration as YAML.
+- **Plugin names displayed in YAML config export**. [PR #750](https://github.com/shakacode/shakapacker/pull/750) by [justin808](https://github.com/justin808). Shows plugin constructor names in exported configuration to help identify which plugins are active.
+- **Custom help messages for `bin/shakapacker` commands**. [PR #702](https://github.com/shakacode/shakapacker/pull/702) by [justin808](https://github.com/justin808). Improved help output for better command discoverability with clear usage examples.
+- **HMR client config export in doctor mode**. [PR #701](https://github.com/shakacode/shakapacker/pull/701) by [justin808](https://github.com/justin808). `bin/shakapacker-config --doctor` now includes HMR client configuration to help debug Hot Module Replacement issues.
+- **Build timing logs** for webpack and rspack. [PR #706](https://github.com/shakacode/shakapacker/pull/706) by [justin808](https://github.com/justin808). Shows duration of build operations to help identify performance bottlenecks.
+- **Named build configurations with `--build` flag**. [PR #728](https://github.com/shakacode/shakapacker/pull/728) by [justin808](https://github.com/justin808). Allows specifying custom build configurations like `bin/shakapacker --build=production` or `bin/shakapacker --build=test`.
+- **Build validation in `bin/shakapacker-config`**. [PR #717](https://github.com/shakacode/shakapacker/pull/717) by [justin808](https://github.com/justin808). Validates webpack/rspack configuration before export to catch errors early.
+- **Backward compatibility for rspack config in `config/webpack/`**. [PR #734](https://github.com/shakacode/shakapacker/pull/734) by [justin808](https://github.com/justin808). Rspack configurations can now be placed in `config/webpack/` directory for easier migration.
+- **Merge option for WebpackAssetsManifestPlugin**. [PR #760](https://github.com/shakacode/shakapacker/pull/760) by [justin808](https://github.com/justin808). Adds `merge` option to control manifest merging behavior, useful for multi-compiler setups.
+- Support for esbuild-loader v5. [PR #758](https://github.com/shakacode/shakapacker/pull/758) by [justin808](https://github.com/justin808).
 
 ### Changed
 
-- **Migrated to ESLint v9 with flat config format**. [PR #677](https://github.com/shakacode/shakapacker/pull/677) by [justin808](https://github.com/justin808).
-  - Updated all ESLint plugins to latest versions
-  - Uses new flat config format for better maintainability
-- **Replaced custom argument parser with yargs**. [PR #692](https://github.com/shakacode/shakapacker/pull/692) by [justin808](https://github.com/justin808).
-  - More robust command-line argument parsing
-  - Better error messages and help output
-- Replaced `require` with `import` in package/index.ts. [PR #674](https://github.com/shakacode/shakapacker/pull/674) by [justin808](https://github.com/justin808).
+- **Generated `swc.config.js` now uses single quotes and trailing commas**. [PR #755](https://github.com/shakacode/shakapacker/pull/755) by [justin808](https://github.com/justin808). Consistent code style in generated configuration files.
 - Updated @rspack dependencies to 1.5.8. [PR #700](https://github.com/shakacode/shakapacker/pull/700) by [justin808](https://github.com/justin808).
 
 ### Improved
 
-- **Enhanced rspack migration documentation** with real-world lessons. [PR #713](https://github.com/shakacode/shakapacker/pull/713) by [justin808](https://github.com/justin808).
-  - Added practical migration guidance based on actual project experiences
-  - Common pitfalls and solutions documented
-- **Consolidated duplicate configuration documentation**. [PR #714](https://github.com/shakacode/shakapacker/pull/714) by [justin808](https://github.com/justin808).
-  - Removed redundant documentation
-  - Single source of truth for configuration options
-- **Improved error messages** to suggest `assets_bundler_config_path`. [PR #712](https://github.com/shakacode/shakapacker/pull/712) by [justin808](https://github.com/justin808).
-  - More helpful error messages when bundler config is not found
-  - Suggests using `assets_bundler_config_path` for custom locations
-- **Improved doctor command output** clarity and accuracy. [PR #682](https://github.com/shakacode/shakapacker/pull/682) by [justin808](https://github.com/justin808).
-  - Better formatting and organization of diagnostic information
-  - More actionable recommendations
-- **Documented `content_for` pattern to prevent FOUC** with `stylesheet_pack_tag`. [PR #737](https://github.com/shakacode/shakapacker/pull/737) by [justin808](https://github.com/justin808).
-  - Added documentation on using `content_for` to prevent Flash of Unstyled Content
-  - Best practice patterns for managing stylesheet loading order
-- **Improved upgrade documentation** to clarify dual Gemfile and package.json updates. [PR #731](https://github.com/shakacode/shakapacker/pull/731) by [justin808](https://github.com/justin808).
-  - Clearer instructions for upgrading both Ruby gem and NPM package
-  - Helps prevent version mismatch issues
-- Formatted all markdown files with prettier. [PR #673](https://github.com/shakacode/shakapacker/pull/673) by [justin808](https://github.com/justin808).
+- **Improved error messages** to suggest `assets_bundler_config_path`. [PR #712](https://github.com/shakacode/shakapacker/pull/712) by [justin808](https://github.com/justin808). More helpful error messages when bundler config is not found, suggesting use of `assets_bundler_config_path` for custom locations.
+- **Improved doctor command output** clarity and accuracy. [PR #682](https://github.com/shakacode/shakapacker/pull/682) by [justin808](https://github.com/justin808). Better formatting and organization of diagnostic information with more actionable recommendations.
 
 ### Fixed
 
-- Fixed rspack native bindings installation issue when switching bundlers. [PR #672](https://github.com/shakacode/shakapacker/pull/672) by [justin808](https://github.com/justin808).
-  - Running `rake shakapacker:switch_bundler rspack -- --install-deps` now properly installs platform-specific native bindings
-  - Fixes "Cannot find native binding" error when switching to rspack
-- Fixed Rails constant error when using custom environments like staging. [PR #681](https://github.com/shakacode/shakapacker/pull/681) by [justin808](https://github.com/justin808).
-  - `RAILS_ENV=staging` no longer causes "uninitialized constant Shakapacker::Instance::Rails" error
-  - Shakapacker now works in non-Rails contexts (like standalone runner)
-- Fixed TypeScript type definitions to export proper types instead of `any`. [PR #684](https://github.com/shakacode/shakapacker/pull/684) by [justin808](https://github.com/justin808).
-  - Previously `package/index.d.ts` was exporting all types as `any`, breaking IDE autocomplete
-  - Now properly exports typed interfaces for `WebpackConfig`, `RspackConfig`, etc.
-- Fixed integrity config handling and sass-loader version check. [PR #688](https://github.com/shakacode/shakapacker/pull/688) by [justin808](https://github.com/justin808).
-  - Properly handles subresource integrity configuration
-  - Correctly detects sass-loader version for conditional logic
-- Prevented index.d.ts confusion in build process. [PR #698](https://github.com/shakacode/shakapacker/pull/698) by [justin808](https://github.com/justin808).
-  - TypeScript declaration files no longer interfere with build output
-- Fixed yarn.lock formatting changes in Conductor setup. [PR #683](https://github.com/shakacode/shakapacker/pull/683) by [justin808](https://github.com/justin808).
+- Fixed Rails constant error when using custom environments like staging. [PR #681](https://github.com/shakacode/shakapacker/pull/681) by [justin808](https://github.com/justin808). `RAILS_ENV=staging` no longer causes "uninitialized constant Shakapacker::Instance::Rails" error. Shakapacker now works in non-Rails contexts.
+- Fixed TypeScript type definitions to export proper types instead of `any`. [PR #684](https://github.com/shakacode/shakapacker/pull/684) by [justin808](https://github.com/justin808). Previously `package/index.d.ts` was exporting all types as `any`, breaking IDE autocomplete. Now properly exports typed interfaces.
+- Fixed integrity config handling and sass-loader version check. [PR #688](https://github.com/shakacode/shakapacker/pull/688) by [justin808](https://github.com/justin808). Properly handles subresource integrity configuration and correctly detects sass-loader version for conditional logic.
 
 ## [v9.2.0] - October 9, 2025
 
 ### Added
 
 - **New config export utility for debugging webpack/rspack configurations** [PR #647](https://github.com/shakacode/shakapacker/pull/647) by [justin808](https://github.com/justin808).
-  - Adds `bin/export-bundler-config` utility with three modes:
+  - Adds `bin/shakapacker-config` utility (originally named `bin/export-bundler-config`, renamed in PR #728) with three modes:
     - **Doctor mode** (`--doctor`): Exports all configs (dev + prod, client + server) to `shakapacker-config-exports/` directory - best for troubleshooting
     - **Save mode** (`--save`): Export current environment configs to files
     - **Stdout mode** (default): View configs in terminal
@@ -148,7 +85,7 @@ Changes since the last non-beta release.
     - Validates bundler value and output paths
     - Sanitizes filenames to prevent path traversal
     - Helpful `.gitignore` suggestions
-  - **Usage:** `bin/export-bundler-config --doctor` or `bundle exec rake shakapacker:export_bundler_config`
+  - **Usage:** `bin/shakapacker-config --doctor` or `bundle exec rake shakapacker:export_bundler_config`
   - Works seamlessly with `rake shakapacker:switch_bundler` for comparing webpack vs rspack configs
   - Lays groundwork for future config diff feature (tracked in [#667](https://github.com/shakacode/shakapacker/issues/667))
 
@@ -783,8 +720,8 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0-beta.5...main
-[v9.3.0-beta.5]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0-beta.5
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0...main
+[v9.3.0]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0
 [v9.2.0]: https://github.com/shakacode/shakapacker/compare/v9.1.0...v9.2.0
 [v9.1.0]: https://github.com/shakacode/shakapacker/compare/v9.0.0...v9.1.0
 [v9.0.0]: https://github.com/shakacode/shakapacker/compare/v8.4.0...v9.0.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.7)
+    shakapacker (9.3.0)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/README.md

@@ -85,6 +85,7 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
     - [Automatic Webpack Code Building](#automatic-webpack-code-building)
     - [Compiler strategies](#compiler-strategies)
     - [Common Development Commands](#common-development-commands)
+  - [API Documentation](#api-documentation)
   - [Webpack Configuration](#webpack-configuration)
   - [Babel configuration](#babel-configuration)
   - [SWC configuration](#swc-configuration)
@@ -316,7 +317,15 @@ At its core, Shakapacker's essential function is to:
 
 ### Configuration and Code
 
-**📖 For a comprehensive guide to all configuration options, see [Configuration Guide](./docs/configuration.md)**
+**📖 For a comprehensive guide to all configuration options, see the [Configuration Guide](./docs/configuration.md)**
+
+This includes documentation for:
+
+- All `config/shakapacker.yml` options (including `assets_bundler_config_path`)
+- Environment-specific configuration
+- Development server settings
+- Build configurations (`config/shakapacker-builds.yml`)
+- Best practices and common patterns
 
 You will need your file system to correspond to the setup of your `config/shakapacker.yml` file.
 
@@ -664,6 +673,48 @@ end
 
 **Note:** Don't forget to prefix `ruby` when running these binstubs on Windows
 
+### API Documentation
+
+Shakapacker's Ruby API is documented using RDoc comments. You can generate the API documentation locally using either RDoc or YARD:
+
+#### Using RDoc (Standard Ruby Documentation)
+
+```bash
+# Generate documentation in the doc/ directory
+rdoc lib/
+
+# View the generated documentation
+open doc/index.html
+```
+
+#### Using YARD (Enhanced Documentation)
+
+YARD provides better formatting and supports additional tags used in the codebase:
+
+```bash
+# Install YARD if you don't have it
+gem install yard
+
+# Generate documentation
+yard doc
+
+# View the generated documentation
+open doc/index.html
+
+# Or start a local documentation server
+yard server
+```
+
+The API documentation covers:
+
+- **Shakapacker** - Main module with configuration, compilation, and manifest access
+- **Shakapacker::Configuration** - All configuration options from `shakapacker.yml`
+- **Shakapacker::Manifest** - Asset lookup methods used by view helpers
+- **Shakapacker::DevServer** - Development server status and configuration
+- **Shakapacker::Instance** - Instance management and lifecycle
+
+For the most up-to-date API reference, generate the documentation from the source code as shown above.
+
 ### Webpack Configuration
 
 First, you don't _need_ to use Shakapacker's webpack configuration. However, the `shakapacker` NPM package provides convenient access to configuration code that reads the `config/shakapacker.yml` file which the view helpers also use. If you have your customized webpack configuration, at the minimum, you must ensure:
@@ -801,7 +852,7 @@ Shakapacker provides a powerful utility to export and analyze your webpack/rspac
 
 ```bash
 # Export all configs for troubleshooting (recommended)
-bin/export-bundler-config --doctor
+bin/shakapacker-config --doctor
 
 # Or via rake task
 bundle exec rake shakapacker:export_bundler_config -- --doctor

data/docs/configuration.md

@@ -4,6 +4,7 @@ This guide covers all configuration options available in `config/shakapacker.yml
 
 ## Table of Contents
 
+- [Quick Reference](#quick-reference)
 - [Basic Configuration](#basic-configuration)
 - [Source Configuration](#source-configuration)
 - [Output Configuration](#output-configuration)
@@ -16,6 +17,33 @@ This guide covers all configuration options available in `config/shakapacker.yml
 - [Environment-Specific Configuration](#environment-specific-configuration)
 - [Build Configurations (config/shakapacker-builds.yml)](#build-configurations-configshakapacker-buildsyml)
 
+## Quick Reference
+
+Common configuration options with their defaults:
+
+| Option                         | Type    | Default                                 | Description                                                |
+| ------------------------------ | ------- | --------------------------------------- | ---------------------------------------------------------- |
+| `assets_bundler`               | string  | `"webpack"`                             | Bundler to use: `"webpack"` or `"rspack"`                  |
+| `assets_bundler_config_path`   | string  | `"config/webpack"` or `"config/rspack"` | Directory containing bundler config files                  |
+| `javascript_transpiler`        | string  | `"swc"` or `"babel"`                    | Transpiler: `"swc"`, `"babel"`, or `"esbuild"`             |
+| `source_path`                  | string  | `"app/javascript"`                      | Root directory for JavaScript source files                 |
+| `source_entry_path`            | string  | `"packs"`                               | Subdirectory within `source_path` for entry points         |
+| `nested_entries`               | boolean | `true`                                  | Discover entry points in subdirectories                    |
+| `public_output_path`           | string  | `"packs"`                               | Subdirectory within `public_root_path` for compiled assets |
+| `private_output_path`          | string  | `nil`                                   | Directory for private server-side bundles (e.g., SSR)      |
+| `compile`                      | boolean | env-specific                            | Compile assets on-demand when requests are made            |
+| `cache_manifest`               | boolean | `false` (dev), `true` (prod)            | Cache manifest.json in memory                              |
+| `compiler_strategy`            | string  | `"mtime"` (dev), `"digest"` (prod)      | How to determine if recompilation is needed                |
+| `useContentHash`               | boolean | `false` (dev), `true` (prod)            | Include content hashes in asset filenames                  |
+| `webpack_compile_output`       | boolean | `true`                                  | Show webpack/rspack compilation output                     |
+| `shakapacker_precompile`       | boolean | `true`                                  | Include in `rails assets:precompile`                       |
+| `ensure_consistent_versioning` | boolean | `true`                                  | Enforce gem/npm version matching                           |
+| `dev_server.host`              | string  | `"localhost"`                           | Development server host                                    |
+| `dev_server.port`              | number  | `3035`                                  | Development server port                                    |
+| `dev_server.hmr`               | boolean | `false`                                 | Enable Hot Module Replacement                              |
+
+For detailed explanations, examples, and additional options, see the sections below.
+
 ## Basic Configuration
 
 ### `assets_bundler`

data/docs/rspack_migration_guide.md

@@ -11,7 +11,9 @@
   - [Server-Side Rendering (SSR) Considerations](#server-side-rendering-ssr-considerations)
 - [Key Differences from Webpack](#key-differences-from-webpack)
 - [Migration Steps](#migration-steps)
+- [Build Verification](#build-verification)
 - [Configuration Best Practices](#configuration-best-practices)
+- [Common Migration Issues](#common-migration-issues)
 - [Common Issues and Solutions](#common-issues-and-solutions)
 - [Performance Tips](#performance-tips)
 - [Debugging Configuration](#debugging-configuration)
@@ -312,6 +314,73 @@ bin/shakapacker --mode production
 - [ ] Deploy to staging
 - [ ] Monitor performance improvements
 
+## Build Verification
+
+After completing your migration, verify that everything works correctly:
+
+### Basic Build Verification
+
+```bash
+# Clean previous build artifacts
+rm -rf public/packs public/packs-test
+
+# Test development build
+bin/shakapacker
+
+# Test production build
+RAILS_ENV=production bin/shakapacker
+
+# Verify assets were generated
+ls -la public/packs/
+```
+
+### SSR Build Verification
+
+If your application uses Server-Side Rendering, perform these additional checks:
+
+```bash
+# 1. Verify server bundle was created
+ls -la public/packs/*-server-bundle.js
+
+# 2. Test SSR rendering in Rails console
+bundle exec rails console
+# In console:
+ReactOnRails::ServerRenderingPool.reset_pool
+# Then visit a page that uses SSR and check for errors
+
+# 3. Run full test suite (watch for SSR-related failures)
+bundle exec rspec
+
+# 4. Check for CSS extraction issues in SSR
+# Look for "Cannot read properties of undefined" errors in tests
+# or intermittent test failures related to styling
+```
+
+### Common Verification Issues
+
+**Silent SSR failures**: If your SSR pages render without errors but components appear unstyled or with missing data, check:
+
+- Server bundle is being generated correctly
+- CSS extraction is disabled for server bundle (see [Common Migration Issues](#common-migration-issues))
+- React runtime configuration is compatible with your SSR framework
+
+**Error patterns to watch for**:
+
+- `Cannot read properties of undefined (reading 'className')` - CSS Modules configuration issue
+- `Invalid call to renderToString` - React runtime compatibility issue
+- `Module not found: Can't resolve './Module.bs.js'` - File extension resolution issue
+- Intermittent/flaky tests - CSS extraction leaking into server bundle
+
+### Testing Strategy for SSR
+
+For applications with SSR, follow this verification order:
+
+1. Test client-only pages first (verify basic Rspack build works)
+2. Test SSR pages without CSS modules (verify SSR configuration)
+3. Test SSR pages with CSS modules (verify CSS extraction + SSR work together)
+4. Run full test suite multiple times to catch flaky tests
+5. Test in production mode (some issues only appear with minification)
+
 ## Configuration Best Practices
 
 ### Configuration Organization
@@ -390,6 +459,173 @@ When upgrading to Shakapacker 9 with Rspack:
 4. **Check Node version compatibility**: Verify your Node version meets all dependency requirements
 5. **Don't make empty commits**: If CI fails but local passes, investigate the root cause - don't try to "trigger CI re-run" with empty commits
 
+## Common Migration Issues
+
+This section highlights the most critical configuration issues that cause build failures during webpack-to-Rspack migration. These issues are especially important for applications using Server-Side Rendering (SSR), CSS Modules, or non-standard file extensions.
+
+### 1. SWC React Runtime for SSR (CRITICAL for React on Rails)
+
+**Problem**: React on Rails SSR detection expects specific function signatures that may not work with SWC's automatic React runtime.
+
+**Symptoms**:
+
+- Error: `Invalid call to renderToString. Possibly you have a renderFunction...`
+- SSR pages fail to render or render without React hydration
+
+**Solution**: Configure SWC to use classic React runtime instead of automatic:
+
+```javascript
+// config/swc.config.js
+const customConfig = {
+  options: {
+    jsc: {
+      transform: {
+        react: {
+          runtime: "classic", // Use 'classic' instead of 'automatic' for SSR
+          refresh: env.isDevelopment && env.runningWebpackDevServer
+        }
+      }
+    }
+  }
+}
+```
+
+**Why this matters**: The automatic runtime changes how React imports work (`import { jsx as _jsx }` vs `import React`), which breaks React on Rails' SSR function detection logic. This is a silent failure that only manifests at runtime.
+
+**Implementation checklist for SSR users**:
+
+- [ ] Locate your SWC configuration file (typically `config/swc.config.js`)
+- [ ] Change `runtime: 'automatic'` to `runtime: 'classic'`
+- [ ] Test SSR rendering in development and production modes
+- [ ] Verify React hydration works correctly on client side
+- [ ] Run full test suite to catch any related issues
+
+### 2. CSS Modules Configuration for Server Bundles (CRITICAL for SSR + CSS Modules)
+
+**Problem**: When configuring server bundles, you must preserve Shakapacker 9's CSS Modules settings (`namedExport: true`) while adding SSR-specific settings. Simply setting `exportOnlyLocals: true` will override the base configuration and break CSS imports.
+
+**Symptoms**:
+
+- Error: `export 'default' (imported as 'css') was not found`
+- CSS classes return undefined in SSR
+- Client-side CSS works but SSR fails
+- Intermittent/flaky test failures
+
+**Solution**: Use spread operator to merge CSS Modules options instead of replacing them:
+
+```javascript
+// config/webpack/serverWebpackConfig.js
+if (cssLoader && cssLoader.options && cssLoader.options.modules) {
+  // ✅ CORRECT - Preserves namedExport and other settings
+  cssLoader.options.modules = {
+    ...cssLoader.options.modules,
+    exportOnlyLocals: true
+  }
+
+  // ❌ INCORRECT - Overwrites all settings
+  // cssLoader.options.modules.exportOnlyLocals = true
+}
+```
+
+**Why this matters**: Shakapacker 9 changed the default CSS Modules configuration to use named exports. If you only set `exportOnlyLocals: true` without preserving the base config, you'll lose the `namedExport: true` setting, causing import/export mismatches between client and server bundles.
+
+**Related configuration**: You must also filter out CSS extraction loaders in server bundles:
+
+```javascript
+// config/webpack/serverWebpackConfig.js
+rule.use = rule.use.filter((item) => {
+  let testValue
+  if (typeof item === "string") {
+    testValue = item
+  } else if (typeof item.loader === "string") {
+    testValue = item.loader
+  }
+  // Handle both Webpack and Rspack CSS extract loaders
+  return !(
+    testValue?.match(/mini-css-extract-plugin/) ||
+    testValue?.includes("cssExtractLoader") || // Rspack uses this path
+    testValue === "style-loader"
+  )
+})
+```
+
+**Implementation checklist for SSR + CSS Modules users**:
+
+- [ ] Update server bundle config to use spread operator for CSS Modules options
+- [ ] Ensure CSS extraction loaders are filtered for both webpack and Rspack paths
+- [ ] Test SSR pages with CSS Modules imports
+- [ ] Verify CSS classes are defined (not undefined) during SSR
+- [ ] Run tests multiple times to catch flaky failures
+
+### 3. ReScript File Resolution (CRITICAL for ReScript users)
+
+**Problem**: Rspack requires explicit configuration to resolve `.bs.js` extensions (ReScript compiled output), while webpack handled this automatically.
+
+**Symptoms**:
+
+- Error: `Module not found: Can't resolve './Module.bs.js'`
+- ReScript modules fail to import
+- Build fails with missing module errors
+
+**Solution**: Add `.bs.js` to resolve extensions:
+
+```javascript
+// config/webpack/webpack.config.js (works for both webpack and rspack)
+const commonOptions = {
+  resolve: {
+    extensions: [".css", ".ts", ".tsx", ".bs.js"] // Add .bs.js for ReScript
+  }
+}
+
+module.exports = merge({}, baseConfig, commonOptions)
+```
+
+**Why this matters**: ReScript compiles `.res` source files to `.bs.js` JavaScript files. If your bundler can't resolve these extensions, all ReScript imports will fail, even though the compiled files exist.
+
+**Additional consideration - Missing compiled files**: Some ReScript npm packages ship only `.res` source files without compiled `.bs.js` files. If you encounter this, use `patch-package` to fix the dependency's `bsconfig.json` (see detailed solution in [Common Issues and Solutions](#issue-rescript-dependencies-missing-compiled-files)).
+
+**Implementation checklist for ReScript users**:
+
+- [ ] Add `.bs.js` to resolve extensions in webpack/rspack config
+- [ ] Verify all ReScript modules can be imported
+- [ ] Check if any ReScript dependencies are missing compiled files
+- [ ] If needed, patch broken dependencies with `patch-package`
+- [ ] Test build with all ReScript code paths
+
+### 4. Build Verification Steps (IMPORTANT for all migrations)
+
+**Problem**: The migration documentation lacked practical verification procedures, leaving developers without guidance on testing SSR functionality or identifying configuration errors.
+
+**Solution**: Follow the comprehensive verification steps in the [Build Verification](#build-verification) section above, which includes:
+
+- Basic build verification commands
+- SSR-specific testing procedures
+- Error pattern identification
+- Testing strategy for SSR applications
+
+**Why this matters**: Silent SSR failures and configuration issues often only manifest in specific scenarios (production mode, certain page types, race conditions in tests). Without systematic verification, these issues may slip into production.
+
+**Implementation checklist for all users**:
+
+- [ ] Clean build artifacts before testing
+- [ ] Test both development and production builds
+- [ ] Verify generated assets in `public/packs/`
+- [ ] For SSR: verify server bundle generation
+- [ ] For SSR: test rendering in Rails console
+- [ ] Run full test suite multiple times
+- [ ] Check for error patterns listed in Build Verification
+
+### Configuration Differences: webpack vs Rspack Summary
+
+Quick reference for the key differences that cause migration issues:
+
+| Area                       | Webpack                   | Rspack                              | Migration Action                            |
+| -------------------------- | ------------------------- | ----------------------------------- | ------------------------------------------- |
+| CSS Extraction Loader Path | `mini-css-extract-plugin` | `cssExtractLoader.js`               | Filter both paths in SSR config             |
+| React Runtime (SSR)        | Works with both           | Classic required for React on Rails | Use `runtime: 'classic'`                    |
+| ReScript Extensions        | Auto-resolves `.bs.js`    | Requires explicit config            | Add to `resolve.extensions`                 |
+| CSS Modules Default        | `namedExport: true` (v9+) | Same                                | Preserve with spread operator in SSR config |
+
 ## Common Issues and Solutions
 
 ### Issue: CSS Modules Returning Undefined (CRITICAL)
@@ -601,13 +837,13 @@ To compare your webpack and rspack configurations during migration:
 
 ```bash
 # Export webpack configs before switching
-bin/export-bundler-config --doctor
+bin/shakapacker-config --doctor
 
 # Switch to rspack
 rails shakapacker:switch_bundler rspack --install-deps
 
 # Export rspack configs to compare
-bin/export-bundler-config --doctor
+bin/shakapacker-config --doctor
 
 # Compare the files in shakapacker-config-exports/
 diff shakapacker-config-exports/webpack-production-client.yaml \