shakapacker 9.1.0 → 9.3.0.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f96f94846c3ee598308246c0098532ba6248fded2b0d3b3aba786e03f7fcfb9
-  data.tar.gz: 85d79f4ff3ad8a6e6383e5e30a0f834fa8400ea31588b839ca6dae13b8f77f9f
+  metadata.gz: 673dbe7651111125cf2c4c408e128be24f73475825910473ced26eba32929f6e
+  data.tar.gz: 83af8568e4d40e9859483ee4d71d7164facb0c5c2131880912e0aa42143aa427
 SHA512:
-  metadata.gz: 102139fc016e4eb974e0f9b8888355f64723cc78281c13c7c4688e4f3f8c563f8436fd042838593c7356108212b48b7d298cbd9c4b6a86331a92557120750577
-  data.tar.gz: 7cde64aa9e306826463966f1092c365dc7bc8e1d7447c04995408b25d21e1ddac27af2fa998d075afeb6d4c4f04bae83c88e99d89eec150455c862135ed74168
+  metadata.gz: 302f3c9f98e999524573103dbaf5ecdfc048f5c780a293ddcf1bfb0409a3779e83b0176070a2c7563f74be56a3c118e23812ba8065c048d1eb9fb9765d00a272
+  data.tar.gz: ff0f655f57a37baee93a04147b9e2d0e50fd0f2607c2413bac46a420275a0e40c302d41a1a3d4d38e35a0e1d70b525c60ecbc0a742c634c22b202b36d3422fd5

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,24 +1,21 @@
 ---
 name: Bug report
 about: Create a report for a crash or unexpected behavior.
-title: ''
+title: ""
 labels: bug
-assignees: ''
-
+assignees: ""
 ---
 
 _Notice: A bug is a crash or incorrect behavior. If you have a debugging or troubleshooting question, please open a discussion on the [Discussions Tab](https://github.com/shakacode/shakapacker/discussions). Otherwise, remove this line and fill out the following sections._
 
 ## Expected behavior:
 
-
 ## Actual behavior:
 
-
 ## Small, reproducible repo:
 
-
 ## Setup environment:
-- Ruby version: 
-- Rails version: 
-- Shakapacker version: 
+
+- Ruby version:
+- Rails version:
+- Shakapacker version:

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,21 +1,19 @@
 ---
 name: Feature request
 about: Create a request for new functionality
-title: ''
+title: ""
 labels: enhancement
-assignees: ''
-
+assignees: ""
 ---
 
 _Notice: A feature request describes a suggested improvement. If you have a debugging or troubleshooting question, please open a discussion on the [Discussions Tab](https://github.com/shakacode/shakapacker/discussions). Otherwise, remove this line and fill out the following sections._
 
 ## Desired behavior:
 
-
 ## Actual behavior:
 
-
 ## Setup environment:
-- Ruby version: 
-- Rails version: 
-- Shakapacker version: 
+
+- Ruby version:
+- Rails version:
+- Shakapacker version:

data/.github/workflows/claude-code-review.yml

@@ -17,14 +17,14 @@ jobs:
     #   github.event.pull_request.user.login == 'external-contributor' ||
     #   github.event.pull_request.user.login == 'new-developer' ||
     #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-    
+
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: read
       issues: read
       id-token: write
-    
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -43,12 +43,11 @@ jobs:
             - Performance considerations
             - Security concerns
             - Test coverage
-            
+
             Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
 
             Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-          
+
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
           claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
-

data/.github/workflows/claude.yml

@@ -35,7 +35,7 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          
+
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
@@ -47,4 +47,3 @@ jobs:
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
           # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
-

data/.github/workflows/dummy.yml

@@ -3,7 +3,7 @@ name: Dummy specs
 on:
   push:
     branches:
-      - 'main'
+      - "main"
   pull_request:
 
 concurrency:
@@ -21,10 +21,10 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: "20"
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          ruby-version: "3.2"
           rubygems: latest
       - name: Install dependencies
         run: |
@@ -32,7 +32,7 @@ jobs:
           yarn install --frozen-lockfile --production=false
           npm install -g yalc
           cd spec/dummy && npm install
-      
+
       - name: Build TypeScript
         run: yarn build
 

data/.github/workflows/generator.yml

@@ -3,7 +3,7 @@ name: Generator specs
 on:
   push:
     branches:
-      - 'main'
+      - "main"
   pull_request:
 
 concurrency:
@@ -18,7 +18,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        ruby: ['2.7', '3.0', '3.1', '3.2', '3.3', '3.4']
+        ruby: ["2.7", "3.0", "3.1", "3.2", "3.3", "3.4"]
         gemfile:
           - gemfiles/Gemfile-rails.7.0.x
           - gemfiles/Gemfile-rails.7.1.x
@@ -28,17 +28,17 @@ jobs:
           # upcomming Rails versions, maybe before a release.
           #- gemfiles/Gemfile-rails-edge
         exclude:
-          - ruby: '2.7'
+          - ruby: "2.7"
             gemfile: gemfiles/Gemfile-rails.7.2.x
-          - ruby: '2.7'
+          - ruby: "2.7"
             gemfile: gemfiles/Gemfile-rails.8.0.x
-          - ruby: '3.0'
+          - ruby: "3.0"
             gemfile: gemfiles/Gemfile-rails.7.2.x
-          - ruby: '3.0'
+          - ruby: "3.0"
             gemfile: gemfiles/Gemfile-rails.8.0.x
-          - ruby: '3.1'
+          - ruby: "3.1"
             gemfile: gemfiles/Gemfile-rails.8.0.x
-          - ruby: '3.4'
+          - ruby: "3.4"
             gemfile: gemfiles/Gemfile-rails.7.0.x
 
     env:
@@ -57,7 +57,7 @@ jobs:
         with:
           node-version: 20.x
           cache: yarn
-      
+
       - name: Install Node dependencies
         run: yarn install --frozen-lockfile --production=false
 

data/.github/workflows/node.yml

@@ -3,7 +3,7 @@ name: Node based checks
 on:
   push:
     branches:
-      - 'main'
+      - "main"
   pull_request:
 
 concurrency:
@@ -31,6 +31,15 @@ jobs:
       - name: Node eslint
         run: yarn lint
 
+      - name: Prettier format check
+        run: yarn prettier --check .
+
+      - name: Detect dead code
+        run: yarn knip
+
+      - name: Detect dead code in production
+        run: yarn knip:production
+
   type-check:
     name: TypeScript Type Checking
     runs-on: ubuntu-latest
@@ -54,7 +63,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node: [18.x, 20.x, 22.x]
+        node: [20.x, 22.x]
 
     runs-on: ${{ matrix.os }}
 

data/.github/workflows/ruby.yml

@@ -3,7 +3,7 @@ name: Ruby based checks
 on:
   push:
     branches:
-      - 'main'
+      - "main"
   pull_request:
 
 concurrency:
@@ -23,7 +23,7 @@ jobs:
         run: rm -f Gemfile.lock
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.4'
+          ruby-version: "3.4"
           rubygems: latest
           bundler-cache: true
 
@@ -36,7 +36,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        ruby: ['2.7', '3.0', '3.1', '3.2', '3.3', '3.4']
+        ruby: ["2.7", "3.0", "3.1", "3.2", "3.3", "3.4"]
         gemfile:
           - gemfiles/Gemfile-rails.6.0.x
           - gemfiles/Gemfile-rails.6.1.x
@@ -48,29 +48,29 @@ jobs:
           # upcomming Rails versions, maybe before a release.
           #- gemfiles/Gemfile-rails-edge
         exclude:
-          - ruby: '2.7'
+          - ruby: "2.7"
             gemfile: gemfiles/Gemfile-rails.7.2.x
-          - ruby: '2.7'
+          - ruby: "2.7"
             gemfile: gemfiles/Gemfile-rails.8.0.x
-          - ruby: '3.0'
+          - ruby: "3.0"
             gemfile: gemfiles/Gemfile-rails.7.2.x
-          - ruby: '3.0'
+          - ruby: "3.0"
             gemfile: gemfiles/Gemfile-rails.8.0.x
-          - ruby: '3.1'
+          - ruby: "3.1"
             gemfile: gemfiles/Gemfile-rails.6.0.x
-          - ruby: '3.1'
+          - ruby: "3.1"
             gemfile: gemfiles/Gemfile-rails.8.0.x
-          - ruby: '3.2'
+          - ruby: "3.2"
             gemfile: gemfiles/Gemfile-rails.6.0.x
-          - ruby: '3.3'
+          - ruby: "3.3"
             gemfile: gemfiles/Gemfile-rails.6.0.x
-          - ruby: '3.3'
+          - ruby: "3.3"
             gemfile: gemfiles/Gemfile-rails.6.1.x
-          - ruby: '3.4'
+          - ruby: "3.4"
             gemfile: gemfiles/Gemfile-rails.6.0.x
-          - ruby: '3.4'
+          - ruby: "3.4"
             gemfile: gemfiles/Gemfile-rails.6.1.x
-          - ruby: '3.4'
+          - ruby: "3.4"
             gemfile: gemfiles/Gemfile-rails.7.0.x
 
     env:
@@ -85,7 +85,7 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           rubygems: latest
           bundler-cache: true
-      
+
       - uses: actions/setup-node@v4
         with:
           node-version: 20.x

data/.github/workflows/test-bundlers.yml

@@ -19,15 +19,15 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          ruby-version: "3.2"
           bundler-cache: true
           working-directory: spec/dummy
 
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'yarn'
+          node-version: "20"
+          cache: "yarn"
           cache-dependency-path: spec/dummy/yarn.lock
 
       - name: Install yalc
@@ -72,15 +72,15 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          ruby-version: "3.2"
           bundler-cache: true
           working-directory: spec/dummy
 
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'yarn'
+          node-version: "20"
+          cache: "yarn"
           cache-dependency-path: spec/dummy/yarn.lock
 
       - name: Install yalc
@@ -125,15 +125,15 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          ruby-version: "3.2"
           bundler-cache: true
           working-directory: spec/dummy
 
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'yarn'
+          node-version: "20"
+          cache: "yarn"
           cache-dependency-path: spec/dummy/yarn.lock
 
       - name: Install yalc

data/.gitignore

@@ -5,6 +5,7 @@
 node_modules
 .byebug_history
 /spec/test_app/tmp
+/test/tmp
 yarn-debug.log*
 yarn-error.log*
 .yarn-integrity
@@ -16,6 +17,12 @@ gemfiles/*.lock
 .yalc
 yalc.lock
 
+# npm pack tarballs
+*.tgz
+
+# Config exporter output directory
+shakapacker-config-exports/
+
 # TypeScript generated files
 package/**/*.d.ts
 package/**/*.d.ts.map

data/CHANGELOG.md

@@ -11,7 +11,54 @@
 
 Changes since the last non-beta release.
 
-_No unreleased changes._
+### Changed
+
+- Allow ESLint v9 and migrated to flat config format. [PR #677](https://github.com/shakacode/shakapacker/pull/677) 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.
+
+## [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:
+    - **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
+  - **Output formats:** YAML (with optional inline documentation), JSON, or Node.js inspect
+  - **Smart features:**
+    - Environment isolation ensures dev/prod configs are truly different
+    - Auto-detects bundler from `shakapacker.yml`
+    - Pretty-prints functions (up to 50 lines)
+    - 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`
+  - 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))
+
+### Fixed
+
+- Fixed NoMethodError when custom environment (e.g., staging) is not defined in shakapacker.yml. [PR #669](https://github.com/shakacode/shakapacker/pull/669) by [justin808](https://github.com/justin808).
+  - When deploying to environments like Heroku staging with `RAILS_ENV=staging`, shakapacker would crash with `undefined method 'deep_symbolize_keys' for nil:NilClass`
+  - **Configuration fallback:** Now properly falls back to production environment configuration (appropriate for staging)
+  - **NODE_ENV handling:** `bin/shakapacker` now automatically sets `NODE_ENV=production` for custom environments (staging, etc.)
+    - Previously: `RAILS_ENV=staging` would set `NODE_ENV=development`, breaking webpack optimizations
+    - Now: `RAILS_ENV` in `[development, test]` uses that value for `NODE_ENV`, everything else uses `production`
+  - Logs informational message when falling back to help with debugging
+  - This ensures shakapacker works with any Rails environment even if not explicitly defined in shakapacker.yml
+  - Fixes [#663](https://github.com/shakacode/shakapacker/issues/663)
 
 ## [v9.1.0] - October 8, 2025
 
@@ -85,7 +132,6 @@ See the [v9 Upgrade Guide](https://github.com/shakacode/shakapacker/blob/main/do
 ### ⚠️ Breaking Changes
 
 1. **SWC is now the default JavaScript transpiler instead of Babel** ([PR 603](https://github.com/shakacode/shakapacker/pull/603) by [justin808](https://github.com/justin808))
-
    - Babel dependencies are no longer included as peer dependencies
    - Improves compilation speed by 20x
    - **Migration for existing projects:**
@@ -102,7 +148,6 @@ See the [v9 Upgrade Guide](https://github.com/shakacode/shakapacker/blob/main/do
        ```
 
 2. **CSS Modules now use named exports by default** ([PR 599](https://github.com/shakacode/shakapacker/pull/599))
-
    - **JavaScript:** Use named imports: `import { className } from './styles.module.css'`
    - **TypeScript:** Use namespace imports: `import * as styles from './styles.module.css'`
    - To keep the old behavior with default imports, see [CSS Modules Export Mode documentation](./docs/css-modules-export-mode.md) for configuration instructions
@@ -368,7 +413,6 @@ See the [v8 Upgrade Guide](https://github.com/shakacode/shakapacker/blob/main/do
 
 - Set `source_entry_path` to `packs` and `nested_entries` to `true` in`shakapacker.yml` [PR 284](https://github.com/shakacode/shakapacker/pull/284) by [ahangarha](https://github.com/ahangarha).
 - Dev server configuration is modified to follow [webpack recommended configurations](https://webpack.js.org/configuration/dev-server/) for dev server. [PR276](https://github.com/shakacode/shakapacker/pull/276) by [ahangarha](https://github.com/ahangarha):
-
   - Deprecated `https` entry is removed from the default configuration file, allowing to set `server` or `https` as per the project requirements. For more detail, check webpack documentation. The `https` entry can be effective only if there is no `server` entry in the config file.
   - `allowed_hosts` is now set to `auto` instead of `all` by default.
 
@@ -636,6 +680,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.0.0...main
+[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
 [v8.4.0]: https://github.com/shakacode/shakapacker/compare/v8.3.0...v8.4.0
 [v8.3.0]: https://github.com/shakacode/shakapacker/compare/v8.2.0...v8.3.0

data/CLAUDE.md

@@ -1,29 +1,34 @@
 # Shakapacker Project Guidelines
 
 ## Critical Requirements
+
 - **ALWAYS end all files with a trailing newline character.** This is required by the project's linting rules.
 - **ALWAYS use `bundle exec` prefix when running Ruby commands** (rubocop, rspec, rake, etc.)
 - **ALWAYS run `bundle exec rubocop` before committing Ruby changes**
 - **ALWAYS run `yarn lint` before committing JavaScript changes**
 
 ## Testing
+
 - Run corresponding RSpec tests when changing source files
 - For example, when changing `lib/shakapacker/foo.rb`, run `spec/shakapacker/foo_spec.rb`
 - Run the full test suite with `bundle exec rspec` before pushing
 
 ## Code Style
+
 - Follow existing code conventions in the file you're editing
 - Use the project's existing patterns and utilities
 - No unnecessary comments unless requested
 - Keep changes focused and minimal - avoid extraneous diffs
 
 ## Git Workflow
+
 - Create feature branches for all changes
 - Never push directly to main branch
 - Create small, focused PRs that are easy to review
 - Always create a PR immediately after pushing changes
 
 ## Shakapacker-Specific
+
 - This gem supports both webpack and rspack configurations
 - Test changes with both bundlers when modifying core functionality
-- Be aware of the dual package.json/Gemfile dependency management
+- Be aware of the dual package.json/Gemfile dependency management

data/CONTRIBUTING.md

@@ -72,7 +72,6 @@ yarn lint --cache
 
 1. Install [Yarn](https://classic.yarnpkg.com/)
 2. To test your changes on a Rails test project do the following steps:
-
    - For Ruby gem, update `Gemfile` and point the `shakapacker` to the locally developing Shakapacker project:
      ```ruby
      gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"

data/Gemfile.lock

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

data/README.md

@@ -70,6 +70,7 @@ Read the [full review here](https://clutch.co/profile/shakacode#reviews?sort_by=
 - [Concepts](#concepts)
 - [Usage](#usage)
   - [Configuration and Code](#configuration-and-code)
+    - [Configuration Guide](./docs/configuration.md)
   - [View Helpers](#view-helpers)
     - [View Helpers `javascript_pack_tag` and `stylesheet_pack_tag`](#view-helpers-javascript_pack_tag-and-stylesheet_pack_tag)
     - [View Helpers `append_javascript_pack_tag`, `prepend_javascript_pack_tag` and `append_stylesheet_pack_tag`](#view-helper-append_javascript_pack_tag-prepend_javascript_pack_tag-and-append_stylesheet_pack_tag)
@@ -314,6 +315,8 @@ 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)**
+
 You will need your file system to correspond to the setup of your `config/shakapacker.yml` file.
 
 Suppose you have the following configuration:
@@ -348,13 +351,20 @@ public/packs                # webpack output
 
 Webpack intelligently includes only necessary files. In this example, the file `packs/application.js` would reference `../src/my_component.js`
 
-`nested_entries` allows you to have webpack entry points nested in subdirectories. This defaults to true as of shakapacker v7. With `nested_entries: false`, you can have your entire `source_path` used for your source (using the `source_entry_path: /`) and you place files at the top level that you want as entry points. `nested_entries: true` allows you to have entries that are in subdirectories. This is useful if you have entries that are generated, so you can have a `generated` subdirectory and easily separate generated files from the rest of your codebase.
+The `nested_entries` option allows webpack entry points in subdirectories (defaults to `true`). See the [Configuration Guide](./docs/configuration.md#nested_entries) for details.
+
+The `useContentHash` option enables content-based cache busting. It's disabled by default (except in production) to speed up development builds. See the [Configuration Guide](./docs/configuration.md#usecontenthash) for details.
+
+#### Precompile Hook
 
-To enable/disable the usage of contentHash in any node environment (specified using the `NODE_ENV` environment variable), add/modify `useContentHash` with a boolean value in `config/shakapacker.yml`. This feature is disabled for all environments except production by default. You may not disable the content hash for a `NODE_ENV` of production as that would break the browser caching of assets. Notice that despite the possibility of enabling this option for the development environment, [it is not recommended](https://webpack.js.org/guides/build-performance/#avoid-production-specific-tooling).
+Shakapacker supports running custom commands before compilation via the `precompile_hook` configuration option.
+
+For configuration details, see [precompile_hook in the Configuration Guide](./docs/configuration.md#precompile_hook).
+For complete usage guide, see the [Precompile Hook Guide](./docs/precompile_hook.md).
 
 #### Setting custom config path
 
-You can use the environment variable `SHAKAPACKER_CONFIG` to enforce a particular path to the config file rather than the default `config/shakapacker.yml`.
+You can use the `SHAKAPACKER_CONFIG` environment variable to specify a custom config file path. See [Environment Variables in the Configuration Guide](./docs/configuration.md#environment-variables) for this and other configuration options.
 
 ### View Helpers
 
@@ -583,11 +593,7 @@ Shakapacker ships with two different strategies that are used to determine wheth
 - `digest` - This strategy calculates SHA1 digest of files in your watched paths (see below). The calculated digest is then stored in a temp file. To check whether the assets need to be recompiled, Shakapacker calculates the SHA1 of the watched files and compares it with the one stored. If the digests are equal, no recompilation occurs. If the digests are different or the temp file is missing, files are recompiled.
 - `mtime` - This strategy looks at the last "modified at" timestamps of both files AND directories in your watched paths. The timestamp of the most recent file or directory is then compared with the timestamp of `manifest.json` file generated. If the manifest file timestamp is newer than one of the most recently modified files or directories in the watched paths, no recompilation occurs. If the manifest file is older, files are recompiled.
 
-The `mtime` strategy is generally faster than the `digest` one, but it requires stable timestamps, this makes it perfect for a development environment, such as needing to rebuild bundles for tests, or if you're not changing frontend assets much.
-
-In production or CI environments, the `digest` strategy is more suitable, unless you are using incremental builds or caching and can guarantee that the timestamps will not change after e.g. cache restore. However, many production or CI environments will explicitly compile assets, so `compile: false` is more appropriate. Otherwise, you'll waste time either checking file timestamps or computing digests.
-
-You can control what strategy is used by the `compiler_strategy` option in `shakapacker.yml` config file. By default `mtime` strategy is used in development environment, `digest` is used elsewhere.
+The `compiler_strategy` option determines how Shakapacker checks if assets need recompilation (`mtime` for development, `digest` for production). See the [Configuration Guide](./docs/configuration.md#compiler_strategy) for detailed comparison and recommendations.
 
 > [!NOTE]
 >
@@ -767,6 +773,27 @@ Please note that if you want opt-in to use esbuild-loader, you can skip [React](
 
 To switch between Babel, SWC, or esbuild, or to configure environment-specific transpiler settings, see the [Transpiler Migration Guide](./docs/transpiler-migration.md).
 
+### Debugging Configuration
+
+Shakapacker provides a powerful utility to export and analyze your webpack/rspack configuration:
+
+```bash
+# Export all configs for troubleshooting (recommended)
+bin/export-bundler-config --doctor
+
+# Or via rake task
+bundle exec rake shakapacker:export_bundler_config -- --doctor
+```
+
+This exports development and production configurations for both client and server bundles to `shakapacker-config-exports/` directory in annotated YAML format. Perfect for:
+
+- Debugging configuration issues
+- Comparing webpack vs rspack configs (works with `rake shakapacker:switch_bundler`)
+- Understanding differences between development and production
+- Analyzing client vs server bundle configurations
+
+For more options and usage examples, see the [Troubleshooting Guide](./docs/troubleshooting.md#exporting-webpack--rspack-configuration).
+
 ### Integrations
 
 Shakapacker out of the box supports JS and static assets (fonts, images etc.) compilation. To enable support for CoffeeScript or TypeScript install relevant packages:
@@ -1220,12 +1247,6 @@ The following companies support our Open Source projects, and ShakaCode uses the
     <img alt="BrowserStack" src="https://user-images.githubusercontent.com/4244251/184881129-e1edf4b7-3ae1-4ea8-9e6d-3595cf01609e.png" height="55px">
   </picture>
 </a>
-<a href="https://railsautoscale.com">
-  <img src="https://user-images.githubusercontent.com/4244251/184881144-95c2c25c-9879-4069-864d-4e67d6ed39d2.png" alt="Rails Autoscale" height="55px">
-</a>
 <a href="https://www.honeybadger.io">
   <img src="https://user-images.githubusercontent.com/4244251/184881133-79ee9c3c-8165-4852-958e-31687b9536f4.png" alt="Honeybadger" height="55px">
 </a>
-<a href="https://reviewable.io">
-  <img src="https://user-images.githubusercontent.com/20628911/230848305-c94510a4-82d7-468f-bf9f-eeb81d3f2ce0.png" alt="Reviewable" height="55px">
-</a>