shakapacker 9.3.0.beta.6 → 9.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b7929f32b14b49a2fde4893b66809a37147796c685be9161c12631369105624
-  data.tar.gz: 2601ae85b072d8286700558a5d92f424d6e5989f7e4d990caf2b57c939b1962c
+  metadata.gz: 1e94cd0b57c81506b9cab0fb54cc6a876276c3f3331686cf921fa4485442ab99
+  data.tar.gz: 292b0623b5241014524f9227ed2a1009752de53e8db610344567f761c7b8b4bc
 SHA512:
-  metadata.gz: 9459cd0ec016ad83df86dec2ae879be51d1dc0dbd74fa9047b401ea0c0cb5d264438e43445487974d94bb4c82db5d5116ed9b3f5c3219e0d1f74cea65c7b46bc
-  data.tar.gz: 2f77e883a93ff0c80a2f22871d53646b16d94e1ffa648af78f167b699431cd026e8e9c5707a3379d57fd22e588ad7e526673afb324f4997cff5924bb5f2dceef
+  metadata.gz: 6dd27e8501b86f06fbefd6f71a2a3ceb9c975dd28f140251ab03cf6bd972b631db35666e9c05bdf434bf2ac13c1568f57bd73a7841efb38befb541f2d0cfaeb1
+  data.tar.gz: 623358b9543ddcad7586a68e03aba4848151d4490a298c39320a395cb4aa450783a91f4c21d53b491868600d57e054f3f52bcb72eb244f25ebc0e8cb20ff1738

data/CHANGELOG.md

@@ -11,128 +11,69 @@
 
 Changes since the last non-beta release.
 
-### Added
+### Fixed
 
-- **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
@@ -144,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))
 
@@ -779,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/ESLINT_TECHNICAL_DEBT.md

@@ -6,7 +6,7 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 
 **As of 2025-10-14**: All TypeScript files in `package/` directory are temporarily excluded from linting via the ignore pattern `package/**/*.ts` in `eslint.config.js`. This allows the project to adopt ESLint configuration without requiring immediate fixes to all existing issues.
 
-**Latest Update**: Fixed all `no-param-reassign` violations by refactoring to create new objects instead of mutating parameters (7 violations resolved).
+**Latest Update**: Auto-fixed 28 style violations in `package/configExporter/cli.ts` including unnecessary type assertions, string concatenation to template literals, and object destructuring (reduced from 77 to 49 errors).
 
 ## Current Linting Status
 
@@ -24,7 +24,7 @@ This document tracks the ESLint errors currently suppressed in the codebase and
   - Style/convention issues: ~49 (30%)
 
 **Target**: Reduce suppressed errors by 50% within Q1 2025
-**Last Updated**: 2025-10-15
+**Last Updated**: 2025-10-18
 
 ## Priority Matrix
 
@@ -115,6 +115,12 @@ This document tracks the ESLint errors currently suppressed in the codebase and
 - ✅ **Fixed `class-methods-use-this`** - Converted FileWriter methods to static methods
 - ✅ **Fixed `no-nested-ternary`** - Refactored to if-else statements for better readability
 - ✅ **Fixed `no-param-reassign`** - Refactored `applyDefaults` to return new objects instead of mutating parameters
+- ✅ **Auto-fixed style violations in cli.ts** (2025-10-18):
+  - Removed unnecessary type assertions (`@typescript-eslint/no-unnecessary-type-assertion`)
+  - Used object destructuring (`prefer-destructuring`)
+  - Converted string concatenation to template literals (`prefer-template`)
+  - Removed unused eslint-disable directives
+  - Fixed `no-else-return` violations
 
 🔧 Could still fix (low risk):
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.3.0.beta.6)
+    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`