shakapacker 9.3.0.beta.7 → 9.3.1

data/CHANGELOG.md

@@ -9,134 +9,78 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Extended manifest merging for multiple client configurations to all environments. [PR #800](https://github.com/shakacode/shakapacker/pull/800) by [Judahmeek](https://github.com/Judahmeek).
+
 Changes since the last non-beta release.
 
 ### Added
 
-- **`--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
+- **Support for `css_modules_export_mode` configuration option**. [PR #817](https://github.com/shakacode/shakapacker/pull/817) by [justin808](https://github.com/justin808). Adds `css_modules_export_mode` setting in `shakapacker.yml` to control CSS Modules export style. Set to `"named"` (default, v9+ behavior with true named exports) or `"default"` (v8 behavior with default export object). Allows teams to opt into v8-style exports for easier migration from v8 or when using TypeScript with strict type checking.
+- **`Configuration#data` public API method** with enhanced documentation and safety. [PR #820](https://github.com/shakacode/shakapacker/pull/820) by [justin808](https://github.com/justin808). The `Configuration#data` method is now part of the public Ruby API, providing stable access to raw configuration data. Returns a frozen hash with symbolized keys to prevent accidental mutations. Includes comprehensive test coverage and detailed RDoc documentation.
+- **Support for `javascript_transpiler: 'none'`** for completely custom webpack configurations. [PR #799](https://github.com/shakacode/shakapacker/pull/799) by [justin808](https://github.com/justin808). Allows users with custom webpack configs to skip Shakapacker's transpiler setup and validation by setting `javascript_transpiler: 'none'` in `shakapacker.yml`. Useful when managing transpilation entirely outside of Shakapacker's defaults.
+
+## [v9.3.0] - November 2, 2025
+
+### Fixed
+
+- **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
+- 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.
 
 ### 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).
-
-### 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).
+- **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.
 
 ## [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 +92,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 +727,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/CLAUDE.md

@@ -29,16 +29,12 @@
 
 ## Changelog
 
-- **Update CHANGELOG.md for user-visible changes only**
-- User-visible changes include: new features, bug fixes, breaking changes, deprecations, performance improvements
-- **Do NOT add changelog entries for**: linting fixes, code formatting, internal refactoring, test updates, documentation fixes
-- Non-user-visible changes don't need changelog entries even if they modify code
-- **Format requirements**:
-  - Always link to the PR: `[PR #123](https://github.com/shakacode/shakapacker/pull/123)`
-  - Always link to the author: `by [username](https://github.com/username)`
-  - Keep formatting consistent with existing entries
-  - When releasing a version, update the version diff links at the bottom of CHANGELOG.md
-  - **For breaking changes**: Use bold formatting and link to migration documentation (e.g., `**Breaking**: Description. See [Migration Guide](docs/vX_upgrade.md)`)
+- **Update CHANGELOG.md for user-visible changes only** (features, bug fixes, breaking changes, deprecations, performance improvements)
+- **Do NOT add entries for**: linting, formatting, refactoring, tests, or documentation fixes
+- **Format**: `[PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username)` (Shakapacker uses `#` in PR links)
+- **Use `/update-changelog` command** for guided changelog updates with automatic formatting
+- **Version management**: Run `bundle exec rake update_changelog` after releases to update version headers
+- **Examples**: Run `grep -A 3 "^### " CHANGELOG.md | head -30` to see real formatting examples
 
 ## Shakapacker-Specific
 

data/CONTRIBUTING.md

@@ -103,11 +103,36 @@ Shakapacker uses optional peer dependencies (via `peerDependenciesMeta`) for max
 - **No installation warnings** - Package managers won't warn about missing optional dependencies
 - **Version constraints still apply** - When a package is installed, version compatibility is enforced
 
+### TypeScript Declaration Files and Optional Dependencies
+
+When importing types from optional peer dependencies, we use `@ts-expect-error` directives:
+
+```typescript
+// @ts-expect-error: webpack is an optional peer dependency (using type-only import)
+import type { Configuration } from "webpack"
+```
+
+**Important behavior:**
+
+- **In development** (webpack installed): TypeScript doesn't error, but `@ts-expect-error` expects one → TypeScript compilation will fail
+- **In production** (webpack not installed): TypeScript errors on import, `@ts-expect-error` suppresses it → TypeScript compilation succeeds
+
+This is counterintuitive but correct. Our CI validates both scenarios to ensure the behavior works as expected.
+
+**Example scenario:**
+
+If webpack were changed from optional to required in `package.json`:
+
+- Development builds would fail with: `error TS2578: Unused '@ts-expect-error' directive`
+- This surfaces the dependency change immediately, preventing accidental breakage
+- The build failure prompts developers to remove the `@ts-expect-error` directive
+
 ### When modifying dependencies:
 
 1. Add new peer dependencies to both `peerDependencies` and `peerDependenciesMeta` (marking as optional)
 2. Keep version ranges synchronized between `devDependencies` and `peerDependencies`
 3. Test with multiple package managers: `npm`, `yarn`, and `pnpm`
+4. If adding type-only imports from optional dependencies, use the `@ts-expect-error` pattern shown above
 
 ### Testing peer dependency changes:
 
@@ -223,6 +248,8 @@ The project uses Yarn in CI workflows for the following reasons:
 - `.github/workflows/ruby.yml` - Ruby test suite across Ruby/Rails versions
 - `.github/workflows/node.yml` - Node.js test suite across Node versions
 - `.github/workflows/generator.yml` - Generator installation tests
+- `.github/workflows/dummy.yml` - Dummy app integration tests
+- `.github/workflows/eslint-validation.yml` - ESLint configuration validation
 
 All workflows use:
 
@@ -239,6 +266,36 @@ And install dependencies with:
 yarn install
 ```
 
+### CI Optimization: Path Filtering
+
+To reduce CI costs and execution time, workflows use **path filtering** to run only when relevant files change:
+
+- **Ruby workflow** - Only runs when Ruby files, gemspecs, Gemfile, or RuboCop config changes
+- **Node workflow** - Only runs when JS/TS files, package.json, or Node config changes
+- **Generator specs** - Only runs when generator-related files change
+- **Dummy specs** - Only runs when dummy app or lib files change
+- **Test bundlers** - Only runs when code affecting bundler integration changes
+
+This means documentation-only PRs (e.g., only changing `README.md`) will skip all test workflows entirely.
+
+**Important:** The full test suite always runs on pushes to the `main` branch to ensure the main branch is always thoroughly tested.
+
+### Manual Workflow Execution
+
+All workflows can be triggered manually via the GitHub Actions UI using the "Run workflow" button. This is useful for:
+
+- Re-running tests after a temporary CI failure
+- Testing workflows on specific branches without creating a PR
+- Running full test suites on PRs that would normally skip certain workflows
+
+### Conditional Linting
+
+The Node workflow includes conditional execution of actionlint (GitHub Actions linter):
+
+- Only downloads and runs when `.github/workflows/*` files change
+- Saves time by skipping on most PRs
+- Includes caching for faster execution when needed
+
 ### Testing with Other Package Managers
 
 While CI uses Yarn, the gem supports all major package managers (npm, yarn, pnpm, bun). Generator specs test against all package managers to ensure compatibility.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.7)
+    shakapacker (9.3.1)
       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)
+  - [Ruby API Reference](#ruby-api-reference)
   - [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,56 @@ end
 
 **Note:** Don't forget to prefix `ruby` when running these binstubs on Windows
 
+### Ruby API Reference
+
+**📚 For comprehensive Ruby API documentation, see the [API Reference Guide](./docs/api-reference.md).**
+
+This guide covers:
+
+- **Main Shakapacker Module** - Configuration, compilation, and manifest access
+- **Configuration API** - Accessing `config/shakapacker.yml` settings programmatically
+- **View Helpers** - Complete reference for all Rails helpers
+- **Manifest API** - Asset lookup and resolution methods
+- **Dev Server API** - Development server status and management
+- **Advanced Usage** - Multiple instances, testing, custom configurations
+
+#### Quick Examples
+
+```ruby
+# Access configuration
+Shakapacker.config.source_path
+# => #<Pathname:/app/app/javascript>
+
+# Get raw configuration hash
+Shakapacker.config.data
+# => { "source_path" => "app/javascript", ... }
+
+# Look up compiled assets
+Shakapacker.manifest.lookup("application.js")
+# => "/packs/application-abc123.js"
+
+# Check dev server status
+Shakapacker.dev_server.running?
+# => true
+```
+
+#### Generating Full API Documentation
+
+For complete API documentation with all methods and parameters:
+
+```bash
+# Using YARD (recommended - better formatting)
+gem install yard
+yard doc
+yard server  # Browse at http://localhost:8808
+
+# Using RDoc (standard Ruby documentation)
+rdoc lib/
+open doc/index.html
+```
+
+The generated documentation includes all public and private methods with detailed descriptions.
+
 ### 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:
@@ -673,6 +732,21 @@ First, you don't _need_ to use Shakapacker's webpack configuration. However, the
 
 The webpack configuration used by Shakapacker lives in `config/webpack/webpack.config.js`; this makes it easy to customize the configuration beyond what's available in `config/shakapacker.yml` by giving you complete control of the final configuration. By default, this file exports the result of `generateWebpackConfig` which handles generating a webpack configuration based on `config/shakapacker.yml`.
 
+#### Using a Completely Custom Webpack Configuration
+
+If you're providing a completely custom webpack configuration without using `generateWebpackConfig()`, you should set `javascript_transpiler: 'none'` in your `config/shakapacker.yml` to skip Shakapacker's transpiler validation and dependency checks:
+
+```yml
+# config/shakapacker.yml
+default: &default
+  javascript_transpiler: "none" # Skip Shakapacker's transpiler setup
+  # ... other config
+```
+
+This is useful when you're managing your own transpiler configuration entirely outside of Shakapacker's defaults.
+
+**Note:** Only use `javascript_transpiler: 'none'` if you're providing a completely custom webpack configuration without using `generateWebpackConfig()`. If you're using Shakapacker's webpack generation (which is the common case), use one of the supported transpilers (`'babel'`, `'swc'`, or `'esbuild'`) instead.
+
 The easiest way to modify this config is to pass your desired customizations to `generateWebpackConfig` which will use [webpack-merge](https://github.com/survivejs/webpack-merge) to merge them with the configuration generated from `config/shakapacker.yml`:
 
 ```js
@@ -767,7 +841,7 @@ fileRule.type = "asset"
 
 ### Babel configuration
 
-By default, you will find the Shakapacker preset in your `package.json`. Note, you need to use the new NPM package name, `shakapacker`.
+If you choose to use Babel instead of the default SWC transpiler, you will need to configure it in your `package.json`:
 
 ```json
 "babel": {
@@ -777,19 +851,21 @@ By default, you will find the Shakapacker preset in your `package.json`. Note, y
 },
 ```
 
-Optionally, you can change your Babel configuration by removing these lines in your `package.json` and adding [a Babel configuration file](https://babeljs.io/docs/en/config-files) to your project. For an example of customization based on the original, see [Customizing Babel Config](./docs/customizing_babel_config.md).
+You can also change your Babel configuration by removing these lines in your `package.json` and adding [a Babel configuration file](https://babeljs.io/docs/en/config-files) to your project. For an example of customization based on the original, see [Customizing Babel Config](./docs/customizing_babel_config.md).
 
 ### SWC configuration
 
-You can try out experimental integration with the SWC loader. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
+SWC is the recommended JavaScript transpiler in Shakapacker v9+ (20x faster than Babel). New installations use SWC by default via the installation template. You can read more at [SWC usage docs](./docs/using_swc_loader.md).
+
+**Note on defaults**: The installation template explicitly sets `javascript_transpiler: "swc"` for new projects. However, for backward compatibility, webpack's runtime default (when no explicit config exists) remains `"babel"`. Rspack always defaults to `"swc"`.
 
-Please note that if you want opt-in to use SWC, you can skip [React](#react) integration instructions as it is supported out of the box.
+Please note that SWC supports [React](#react) integration out of the box - no additional configuration needed.
 
 ### esbuild loader configuration
 
-You can try out experimental integration with the esbuild-loader. You can read more at [esbuild-loader usage docs](./docs/using_esbuild_loader.md).
+You can use esbuild as an alternative JavaScript transpiler. You can read more at [esbuild-loader usage docs](./docs/using_esbuild_loader.md).
 
-Please note that if you want opt-in to use esbuild-loader, you can skip [React](#react) integration instructions as it is supported out of the box.
+Please note that esbuild supports [React](#react) integration out of the box - no additional configuration needed.
 
 ### Switching between transpilers
 
@@ -801,7 +877,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