shakapacker 9.6.0.beta.0 → 9.6.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16a87e8e339c085afc34f5f70af6fee7aa534590949f02faa1863d9c5e7f9f7d
-  data.tar.gz: 19d1f859e00dc29bfe4c593ba1b4a1e5b64c6347fc1b56a2cbabcc8c8020205b
+  metadata.gz: a5240d4875989d1257b2c24656db7b29c5d052a9c99e22b9203565bf615aaf43
+  data.tar.gz: 855e3c61ff9169c2f4a34cc864d80f41299e48fd2530fb0def09e5bd9e07651f
 SHA512:
-  metadata.gz: f4286284b7cbbec5324ce2ad26c6d6892cfcecae96e31c7324ff0a533f332301b4008e7083592b3b4b639be131758ab6fa5bc81ed46ac0903f2370f20a05fae0
-  data.tar.gz: e4e6bfdd5837dabfd9f5d031e5a1d905ca88b6c1d50b1f3d440fb3f3c6a23d0abbec1d8839a769536af52d67eed5657ec602786c824dd57156f1678026ec300e
+  metadata.gz: 719593b91e0dd86f68db334fe533a76e05ebf7862e04162039b066182bc52642e4c200d0394e6f3cbfaea8a8600d5340d20d9a5cd54bd389c40e4d4ff8c1f055
+  data.tar.gz: 80f22641a2e9cba2ab9a8ccda6095133e636165185914b8ae1b6f7a85f1b860834913dc4a697db7d1785f001420e47aefad34584389c0221dc7eb7e0f9778957

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

@@ -3,31 +3,19 @@ name: Claude Code Review
 on:
   pull_request:
     types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
 
 jobs:
   claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   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'
-
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
+      pull-requests: write
+      issues: write
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
@@ -36,9 +24,21 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request with a focus on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Security implications
+            - Performance considerations
+
+            Note: The PR branch is already checked out in the current working directory.
+
+            Use `gh pr comment` for top-level feedback.
+            Use `mcp__github_inline_comment__create_inline_comment` to highlight specific code issues.
+            Only post GitHub comments - don't submit review text as messages.
 
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

data/.github/workflows/claude.yml

@@ -24,6 +24,8 @@ jobs:
       issues: read
       id-token: write
       actions: read # Required for Claude to read CI results on PRs
+      checks: read
+      statuses: read
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -34,11 +36,14 @@ jobs:
         id: claude
         uses: anthropics/claude-code-action@v1
         with:
+          github_token: ${{ github.token }}
           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
+            checks: read
+            statuses: read
 
           # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
           # prompt: 'Update the pull request description to include a summary of changes.'

data/CHANGELOG.md

@@ -11,8 +11,31 @@
 
 Changes since the last non-beta release.
 
+### Security
+
+- Removed default `Access-Control-Allow-Origin: *` header from dev server configuration. This header allowed any website to access dev server resources. **If your setup runs webpack-dev-server on a different port from your Rails server, uncomment the `headers` section in `config/shakapacker.yml` to restore cross-origin asset loading.** [PR #936](https://github.com/shakacode/shakapacker/pull/936) by [justin808](https://github.com/justin808). Fixes [#935](https://github.com/shakacode/shakapacker/issues/935).
+
+### Added
+
+- **Added `SKIP=true` installer mode to preserve existing files**. [PR #926](https://github.com/shakacode/shakapacker/pull/926) by [justin808](https://github.com/justin808). Running `rails shakapacker:install SKIP=true` now skips conflicting files instead of overwriting them. This is useful for CI/CD pipelines and automated setups where you want to install only missing files without touching existing configuration.
+- **Export bundler utility functions for Webpack/Rspack compatibility**. [PR #922](https://github.com/shakacode/shakapacker/pull/922) by [justin808](https://github.com/justin808). New utility functions that make it easier to write bundler-agnostic configuration code: `isRspack`, `isWebpack`, `getBundler()`, `getCssExtractPlugin()`, `getCssExtractPluginLoader()`, `getDefinePlugin()`, `getEnvironmentPlugin()`, and `getProvidePlugin()`. Users no longer need to write conditional logic to handle differences between Webpack and Rspack.
+
+  ```javascript
+  // Before: manual conditional logic
+  const { config } = require("shakapacker")
+  const CssPlugin =
+    config.assets_bundler === "rspack"
+      ? require("@rspack/core").CssExtractRspackPlugin
+      : require("mini-css-extract-plugin")
+
+  // After: use bundler utilities
+  const { getCssExtractPlugin } = require("shakapacker")
+  const CssPlugin = getCssExtractPlugin()
+  ```
+
 ### Changed
 
+- Allow `compression-webpack-plugin` v12. [PR #937](https://github.com/shakacode/shakapacker/pull/937) by [G-Rath](https://github.com/G-Rath).
 - **BREAKING: sass-loader now defaults to modern Sass API**. [PR #879](https://github.com/shakacode/shakapacker/pull/879) by [justin808](https://github.com/justin808). The sass-loader configuration now uses `api: "modern"` instead of the deprecated legacy API. This improves compatibility with plugins like sass-resources-loader that require the modern API. If you experience issues after upgrading, you can revert to the legacy API by customizing your webpack config:
 
   ```javascript
@@ -36,9 +59,16 @@ Changes since the last non-beta release.
 
 ### Fixed
 
+- **Fixed hidden dotfiles and dot-directories being treated as entrypoints**. [PR #915](https://github.com/shakacode/shakapacker/pull/915) by [justin808](https://github.com/justin808). Entry discovery now ignores files and directories whose names start with `.` when traversing `source_entry_path`, preventing unintended bundles from being created. Closes [#853](https://github.com/shakacode/shakapacker/issues/853).
 - **Fixed orphaned webpack/rspack processes when foreman receives SIGTERM**. [PR #888](https://github.com/shakacode/shakapacker/pull/888) by [jordan-brough](https://github.com/jordan-brough). When running under foreman, sending SIGTERM to foreman (e.g. `kill <pid>`) would kill the Ruby shakapacker process but leave the webpack/rspack child process running as an orphan. DevServerRunner now uses `exec` to replace the Ruby process entirely, and Runner uses `spawn` with SIGTERM forwarding to ensure the child process is properly terminated.
+- **Fixed missing-environment fallback to use production instead of development**. [PR #894](https://github.com/shakacode/shakapacker/pull/894) by [justin808](https://github.com/justin808). When a Rails environment (e.g., staging) is not defined in `shakapacker.yml`, Shakapacker now falls back to the `production` configuration instead of `development`. This ensures unknown environments get production-optimized webpack/rspack builds by default.
 - **Fixed installer writing wrong shakapacker version in package.json**. [PR #899](https://github.com/shakacode/shakapacker/pull/899) by [justin808](https://github.com/justin808). The `shakapacker:install` generator now keeps the `package.json` dependency value in sync with the exact version or path that was requested, instead of relying on the post-install value which could differ.
+- **Fixed installer not updating `shakapacker.yml` when selecting a non-default transpiler**. [PR #895](https://github.com/shakacode/shakapacker/pull/895) by [codex-rs](https://github.com/apps/codex-rs). Installing with `JAVASCRIPT_TRANSPILER=babel` (or `esbuild`) now correctly updates `config/shakapacker.yml` to match the selected transpiler instead of leaving it set to `swc`. Previously, a quote mismatch in the `gsub_file` call meant the config was never actually updated, and the condition also excluded `JAVASCRIPT_TRANSPILER=babel` from the update entirely. Additionally, `JAVASCRIPT_TRANSPILER=babel` no longer installs SWC packages.
+- **Fixed ENOENT crash on clean builds when using `webpack-assets-manifest` v6 with `merge: true`**. [PR #931](https://github.com/shakacode/shakapacker/pull/931) by [justin808](https://github.com/justin808). Seeds an empty `{}` manifest file before instantiating the plugin, so the merge read succeeds on first build rather than throwing an unhandled ENOENT.
+- **Improved error message when manifest is empty or missing**. [PR #872](https://github.com/shakacode/shakapacker/pull/872) by [justin808](https://github.com/justin808). When the bundler is still compiling (empty manifest) or hasn't run yet (missing manifest file), users now see clear, actionable error messages instead of the generic 7-point checklist.
 - **Fixed NODE_ENV=test causing DefinePlugin warnings**. [PR #870](https://github.com/shakacode/shakapacker/pull/870) by [justin808](https://github.com/justin808). When RAILS_ENV=test, Shakapacker now sets NODE_ENV=development instead of NODE_ENV=test. This prevents webpack/rspack DefinePlugin conflicts since these bundlers only recognize "development" and "production" as valid NODE_ENV values.
+- **Fixed `--json` flag output being corrupted by log messages**. [PR #869](https://github.com/shakacode/shakapacker/pull/869) by [justin808](https://github.com/justin808). When `--json` is in the command arguments, `[Shakapacker]` log messages are now written to stderr instead of stdout, keeping stdout clean for valid JSON output. This allows `bin/shakapacker --profile --json` to be piped to tools like `webpack-bundle-analyzer`. Normal (non-JSON) usage is unchanged. Resolves [#868](https://github.com/shakacode/shakapacker/issues/868).
+- **Require explicit truthy values for `SKIP` and `FORCE` installer env vars**. [PR #926](https://github.com/shakacode/shakapacker/pull/926) by [justin808](https://github.com/justin808). Previously, any set value (including `"false"` or `"0"`) would activate skip/force mode. Now only explicit truthy values (`true`, `1`, `yes`, case-insensitive) are recognized. This behavior change may require CI/scripts that relied on `FORCE=<any non-empty value>` to switch to `FORCE=true`.
 
 ### Documentation
 

data/CLAUDE.md

@@ -40,6 +40,14 @@
 - **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
 
+## Open Source Maintainability
+
+- **Prefer removing complexity over adding configuration.** If a default causes problems, consider removing the default rather than adding an option to disable it.
+- **Every config option is maintenance surface.** Prefer convention over configuration. Don't add options for <10% of users — let them customize via existing extension points (e.g., custom webpack config).
+- **"No is temporary, yes is forever."** Adding a feature creates a permanent maintenance obligation. Reject features that solve one user's niche problem but add complexity for everyone.
+- **Security-safe defaults over convenient defaults.** Don't ship permissive defaults (e.g., `Access-Control-Allow-Origin: *`) just for convenience — make users opt in to less-secure configurations.
+- **Don't refactor adjacent code in feature PRs.** Keep PRs focused. If you spot something to clean up, do it in a separate PR.
+
 ## Shakapacker-Specific
 
 - This gem supports both webpack and rspack configurations

data/README.md

@@ -166,7 +166,7 @@ Then run the following to install Shakapacker:
 bundle exec rake shakapacker:install
 ```
 
-Before initiating the installation process, ensure you have committed all the changes. While installing Shakapacker, there might be some conflict between the existing file content and what Shakapacker tries to copy. You can either approve all the prompts for overriding these files or use the `FORCE=true` environment variable before the installation command to force the override without any prompt.
+Before initiating the installation process, ensure you have committed all changes. During install, Shakapacker may encounter conflicts with existing files. You can approve prompts interactively, use `FORCE=true` to overwrite without prompting, or use `SKIP=true` to preserve existing files and only create missing ones. Accepted truthy values are `true`, `1`, and `yes` (case-insensitive). If both are set, `FORCE` takes precedence.
 
 Shakapacker uses the [`package_json`](https://github.com/shakacode/package_json) gem to handle updating the `package.json` and interacting with the underlying package manager of choice for managing dependencies and running commands; the package manager is managed using the [`packageManager`](https://nodejs.org/api/packages.html#packagemanager) property in the `package.json`, otherwise falling back to the value of `PACKAGE_JSON_FALLBACK_MANAGER` if set or otherwise `npm`.
 

data/docs/configuration.md

@@ -362,9 +362,11 @@ dev_server:
     #   pathname: '/ws'
     #   port: 8080
 
-  # Headers for CORS
-  headers:
-    "Access-Control-Allow-Origin": "*"
+  # Custom headers for dev server responses
+  # Uncomment to enable CORS (e.g., when webpack-dev-server runs on a different
+  # port than your Rails server and the browser blocks cross-origin asset requests):
+  # headers:
+  #   "Access-Control-Allow-Origin": "*"
 
   # Static file serving
   static:

data/docs/precompile_hook.md

@@ -35,13 +35,13 @@ before launching long-running processes instead of using `precompile_hook`.
 
 ### Comparison
 
-| Aspect | `precompile_hook` | Explicit setup in `bin/dev` |
-|--------|-------------------|-------------------------------|
-| Best for | Default/consistent pre-build tasks | Custom multi-step dev boot flows |
-| Runs when | Immediately before compilation starts | Wherever you place it in startup script |
-| Production integration | Automatic via `assets:precompile` | Requires explicit production wiring |
-| Process manager complexity | Lower | Higher (you own orchestration) |
-| Debugging | Centralized hook command | Fully explicit command-by-command flow |
+| Aspect                     | `precompile_hook`                     | Explicit setup in `bin/dev`             |
+| -------------------------- | ------------------------------------- | --------------------------------------- |
+| Best for                   | Default/consistent pre-build tasks    | Custom multi-step dev boot flows        |
+| Runs when                  | Immediately before compilation starts | Wherever you place it in startup script |
+| Production integration     | Automatic via `assets:precompile`     | Requires explicit production wiring     |
+| Process manager complexity | Lower                                 | Higher (you own orchestration)          |
+| Debugging                  | Centralized hook command              | Fully explicit command-by-command flow  |
 
 ### `shakapacker_precompile` Interaction
 

data/eslint.config.js

@@ -233,6 +233,7 @@ module.exports = [
     // Remaining utils files that need type safety improvements
     // These use dynamic requires and helper functions that return `any`
     files: [
+      "package/utils/bundlerUtils.ts",
       "package/utils/inliningCss.ts",
       "package/utils/errorCodes.ts",
       "package/utils/errorHelpers.ts",

data/lib/install/binstubs.rb

@@ -1,6 +1,10 @@
-force_option = ENV["FORCE"] ? { force: true } : {}
+require "shakapacker/install/env"
+
+# template.rb sets @conflict_option first during normal install flow.
+# ||= keeps binstubs runnable standalone (e.g., rake shakapacker:binstubs).
+@conflict_option ||= Shakapacker::Install::Env.conflict_option
 
 say "Copying binstubs"
-directory "#{__dir__}/bin", "bin", force_option
+directory "#{__dir__}/bin", "bin", @conflict_option
 
 chmod "bin", 0755 & ~File.umask, verbose: false

data/lib/install/config/shakapacker.yml

@@ -161,8 +161,10 @@ development:
     allowed_hosts: "auto"
     # Shows progress and colorizes output of bin/shakapacker[-dev-server]
     pretty: true
-    headers:
-      "Access-Control-Allow-Origin": "*"
+    # Uncomment to enable CORS (e.g., when webpack-dev-server runs on a different
+    # port than your Rails server and the browser blocks cross-origin asset requests):
+    # headers:
+    #   "Access-Control-Allow-Origin": "*"
     static:
       watch:
         ignored: "**/node_modules/**"

data/lib/install/template.rb

@@ -1,13 +1,14 @@
 require "shakapacker/utils/misc"
 require "shakapacker/utils/manager"
 require "shakapacker/utils/version_syntax_converter"
+require "shakapacker/install/env"
 require "package_json"
 require "yaml"
 require "json"
 
 # Install Shakapacker
 
-force_option = ENV["FORCE"] ? { force: true } : {}
+@conflict_option = Shakapacker::Install::Env.conflict_option
 
 # Initialize variables for use throughout the template
 # Using instance variable to avoid method definition issues in Rails templates
@@ -19,25 +20,33 @@ install_dir = File.expand_path(File.dirname(__FILE__))
 # - Otherwise install only the specified transpiler
 if ENV["USE_BABEL_PACKAGES"] == "true" || ENV["USE_BABEL_PACKAGES"] == "1"
   @transpiler_to_install = "babel"
+  @install_swc_compat_packages = true
   say "📦 Installing Babel packages (USE_BABEL_PACKAGES is set)", :yellow
   say "✨ Also installing SWC packages for default config compatibility", :green
 elsif ENV["JAVASCRIPT_TRANSPILER"]
   @transpiler_to_install = ENV["JAVASCRIPT_TRANSPILER"]
+  @install_swc_compat_packages = false
   say "📦 Installing #{@transpiler_to_install} packages", :blue
 else
   # Default to swc (matches the default in shakapacker.yml)
   @transpiler_to_install = "swc"
+  @install_swc_compat_packages = false
   say "✨ Installing SWC packages (20x faster than Babel)", :green
 end
 
 # Copy config file
-copy_file "#{install_dir}/config/shakapacker.yml", "config/shakapacker.yml", force_option
-
-# Update config if USE_BABEL_PACKAGES is set to ensure babel is used at runtime
-if @transpiler_to_install == "babel" && !ENV["JAVASCRIPT_TRANSPILER"]
-  # When USE_BABEL_PACKAGES is set, update the config to use babel
-  gsub_file "config/shakapacker.yml", "javascript_transpiler: 'swc'", "javascript_transpiler: 'babel'"
-  say "   📝 Updated config/shakapacker.yml to use Babel transpiler", :green
+shakapacker_config_preexisting = Rails.root.join("config/shakapacker.yml").exist?
+copy_file "#{install_dir}/config/shakapacker.yml", "config/shakapacker.yml", @conflict_option
+
+# Update config to match the selected transpiler
+# Skip modification only when SKIP mode preserved a pre-existing user file
+if Shakapacker::Install::Env.update_transpiler_config?(
+  transpiler_to_install: @transpiler_to_install,
+  conflict_option: @conflict_option,
+  config_preexisting: shakapacker_config_preexisting
+)
+  gsub_file "config/shakapacker.yml", 'javascript_transpiler: "swc"', "javascript_transpiler: \"#{@transpiler_to_install}\""
+  say "   📝 Updated config/shakapacker.yml to use #{@transpiler_to_install} transpiler", :green
 end
 
 # Detect TypeScript usage
@@ -53,7 +62,7 @@ source_config = "#{install_dir}/config/#{assets_bundler}/#{config_file}"
 dest_config = "config/#{assets_bundler}/#{config_file}"
 
 empty_directory "config/#{assets_bundler}"
-copy_file source_config, dest_config, force_option
+copy_file source_config, dest_config, @conflict_option
 
 if @use_typescript
   say "   ✨ Using TypeScript config for enhanced type safety", :green
@@ -223,22 +232,21 @@ Dir.chdir(Rails.root) do
   # Inline the logic here since methods can't be called before they're defined in Rails templates
 
   # Install transpiler-specific dependencies
-  # When USE_BABEL_PACKAGES is set, install both babel AND swc
-  # This ensures backward compatibility while supporting the default config
   if @transpiler_to_install == "babel"
     # Install babel packages
     babel_deps = PackageJson.read(install_dir).fetch("babel")
     peers = peers.merge(babel_deps)
 
-    # Also install SWC since that's what the default config uses
-    # This ensures the runtime works regardless of config
-    swc_deps = PackageJson.read(install_dir).fetch("swc")
-    peers = peers.merge(swc_deps)
+    # Also install SWC only when USE_BABEL_PACKAGES requested compatibility mode.
+    if @install_swc_compat_packages
+      swc_deps = PackageJson.read(install_dir).fetch("swc")
+      peers = peers.merge(swc_deps)
 
-    say "ℹ️  Installing both Babel and SWC packages for compatibility:", :blue
-    say "   - Babel packages are installed as requested via USE_BABEL_PACKAGES", :blue
-    say "   - SWC packages are also installed to ensure the default config works", :blue
-    say "   - Your actual transpiler will be determined by your shakapacker.yml configuration", :blue
+      say "ℹ️  Installing both Babel and SWC packages for compatibility:", :blue
+      say "   - Babel packages are installed as requested via USE_BABEL_PACKAGES", :blue
+      say "   - SWC packages are also installed to ensure the default config works", :blue
+      say "   - Your actual transpiler will be determined by your shakapacker.yml configuration", :blue
+    end
   elsif @transpiler_to_install == "swc"
     swc_deps = PackageJson.read(install_dir).fetch("swc")
     peers = peers.merge(swc_deps)

data/lib/shakapacker/env.rb

@@ -1,4 +1,6 @@
 class Shakapacker::Env
+  FALLBACK_ENV = "production".freeze
+
   delegate :config_path, :logger, to: :@instance
 
   def self.inquire(instance)
@@ -11,7 +13,7 @@ class Shakapacker::Env
 
   def inquire
     fallback_env_warning if config_path.exist? && !current
-    current || Shakapacker::DEFAULT_ENV.inquiry
+    current || FALLBACK_ENV.inquiry
   end
 
   private
@@ -20,7 +22,7 @@ class Shakapacker::Env
     end
 
     def fallback_env_warning
-      logger.info "RAILS_ENV=#{Rails.env} environment is not defined in #{config_path}, falling back to #{Shakapacker::DEFAULT_ENV} environment"
+      logger.info "RAILS_ENV=#{Rails.env} environment is not defined in #{config_path}, falling back to #{FALLBACK_ENV} environment"
     end
 
     def available_environments

data/lib/shakapacker/install/env.rb

@@ -0,0 +1,33 @@
+module Shakapacker
+  module Install
+    module Env
+      TRUTHY_VALUES = %w[true 1 yes].freeze
+
+      module_function
+
+      def truthy_env?(name)
+        TRUTHY_VALUES.include?(ENV[name].to_s.downcase)
+      end
+
+      def conflict_option
+        if truthy_env?("FORCE")
+          { force: true }
+        elsif truthy_env?("SKIP")
+          { skip: true }
+        else
+          {}
+        end
+      end
+
+      # Preserve existing shakapacker.yml when SKIP mode is active, but still
+      # update newly-copied files on fresh installs.
+      def update_transpiler_config?(transpiler_to_install:, conflict_option:, config_preexisting:)
+        return false if transpiler_to_install == "swc"
+        return true if conflict_option[:force]
+        return true unless conflict_option[:skip]
+
+        !config_preexisting
+      end
+    end
+  end
+end

data/lib/shakapacker/manifest.rb

@@ -33,6 +33,10 @@ class Shakapacker::Manifest
   # Raised when an asset cannot be found in the manifest
   class MissingEntryError < StandardError; end
 
+  # Holds the result of loading the manifest file, keeping data and
+  # file-existence state in a single atomic value.
+  LoadResult = Struct.new(:data, :manifest_existed, keyword_init: true)
+
   delegate :config, :compiler, :dev_server, to: :@instance
 
   # Creates a new manifest instance
@@ -50,7 +54,8 @@ class Shakapacker::Manifest
   #
   # @return [Hash] the loaded manifest data
   def refresh
-    @data = load
+    @load_result = load
+    @load_result.data
   end
 
   # Looks up an entry point with all its chunks (split code)
@@ -132,14 +137,19 @@ class Shakapacker::Manifest
       Shakapacker.logger.tagged("Shakapacker") { compiler.compile }
     end
 
-    def data
+    def load_result
       if config.cache_manifest?
-        @data ||= load
+        @load_result ||= load
       else
         refresh
+        @load_result
       end
     end
 
+    def data
+      load_result.data
+    end
+
     def find(name)
       return nil unless data[name.to_s].present?
 
@@ -155,14 +165,27 @@ class Shakapacker::Manifest
     end
 
     def handle_missing_entry(name, pack_type)
-      raise Shakapacker::Manifest::MissingEntryError, missing_file_from_manifest_error(full_pack_name(name, pack_type[:type]))
+      # @load_result is always set by the preceding data call (even in
+      # non-cached mode), so we read it directly to avoid a second file read.
+      result = @load_result
+
+      # An empty data hash covers both a 0-byte / whitespace-only manifest file
+      # and a missing manifest file. Either way the bundler has not produced
+      # usable output yet, so we show a targeted "unavailable" message.
+      if result.data.empty?
+        raise Shakapacker::Manifest::MissingEntryError, manifest_unavailable_error(result)
+      end
+
+      raise Shakapacker::Manifest::MissingEntryError, missing_file_from_manifest_error(full_pack_name(name, pack_type[:type]), result.data)
     end
 
     def load
       if config.manifest_path.exist?
-        JSON.parse config.manifest_path.read
+        contents = config.manifest_path.read
+        parsed = contents.strip.empty? ? {} : JSON.parse(contents)
+        LoadResult.new(data: parsed, manifest_existed: true)
       else
-        {}
+        LoadResult.new(data: {}, manifest_existed: false)
       end
     end
 
@@ -181,21 +204,59 @@ class Shakapacker::Manifest
       end
     end
 
-    def missing_file_from_manifest_error(bundle_name)
+    def missing_file_from_manifest_error(bundle_name, manifest_data)
       bundler_name = config.assets_bundler
-      <<-MSG
-Shakapacker can't find #{bundle_name} in #{config.manifest_path}. Possible causes:
-1. You forgot to install javascript packages or are running an incompatible javascript runtime version
-2. Your app has code with a non-standard extension (like a `.jsx` file) but the extension is not in the `extensions` config in `config/shakapacker.yml`
-3. You have set compile: false (see `config/shakapacker.yml`) for this environment
-   (unless you are using the `bin/shakapacker -w` or the `bin/shakapacker-dev-server`, in which case maybe you aren't running the dev server in the background?)
-4. Your #{bundler_name} has not yet FINISHED running to reflect updates.
-5. You have misconfigured Shakapacker's `config/shakapacker.yml` file.
-6. Your #{bundler_name} configuration is not creating a manifest with the expected structure.
-7. Ensure the 'assets_bundler' in config/shakapacker.yml is set correctly (currently: #{bundler_name}).
-
-Your manifest contains:
-#{JSON.pretty_generate(@data)}
+      <<~MSG
+        Shakapacker can't find #{bundle_name} in #{config.manifest_path}. Possible causes:
+        1. You forgot to install javascript packages or are running an incompatible javascript runtime version
+        2. Your app has code with a non-standard extension (like a `.jsx` file) but the extension is not in the `extensions` config in `config/shakapacker.yml`
+        3. You have set compile: false (see `config/shakapacker.yml`) for this environment
+           (unless you are using the `bin/shakapacker -w` or the `bin/shakapacker-dev-server`, in which case maybe you aren't running the dev server in the background?)
+        4. Your #{bundler_name} has not yet FINISHED running to reflect updates.
+        5. You have misconfigured Shakapacker's `config/shakapacker.yml` file.
+        6. Your #{bundler_name} configuration is not creating a manifest with the expected structure.
+        7. Ensure the 'assets_bundler' in config/shakapacker.yml is set correctly (currently: #{bundler_name}).
+
+        Your manifest contains:
+        #{JSON.pretty_generate(manifest_data)}
       MSG
     end
+
+    def manifest_unavailable_error(result)
+      bundler_name = config.assets_bundler
+
+      if result.manifest_existed
+        <<~MSG
+          Shakapacker manifest is empty. #{bundler_name} is likely still compiling.
+
+          This typically happens when:
+          1. You just started the dev server and it's still compiling
+          2. The dev server crashed during startup
+          3. #{bundler_name} compilation hasn't completed yet
+
+          What to do:
+          - Wait a few seconds and refresh the page
+          - Check your terminal for #{bundler_name} build progress
+          - Look for errors in the #{bundler_name} output
+
+          Manifest path: #{config.manifest_path}
+        MSG
+      else
+        <<~MSG
+          Shakapacker manifest file not found. #{bundler_name} has not yet built assets.
+
+          This typically happens when:
+          1. You haven't started the dev server yet
+          2. The compile process hasn't created the manifest file
+          3. The manifest_path configuration is incorrect
+
+          What to do:
+          - Start the dev server: bin/shakapacker-dev-server
+          - Or run a manual build: bin/shakapacker
+          - Verify manifest_path in config/shakapacker.yml
+
+          Expected manifest path: #{config.manifest_path}
+        MSG
+      end
+    end
 end