Improve error message when manifest is empty (bundler still building) #871
Description
Problem
When the dev server is starting up and hasn't finished its initial compilation, the manifest file is empty ({}). If a user loads a page during this time, they see a confusing error message listing many possible causes:
Shakapacker can't find social_home.js in manifest.json. Possible causes:
1. You forgot to install javascript packages...
2. Your app has code with a non-standard extension...
3. You have set compile: false...
...
Your manifest contains:
{}
The actual cause (#4 - bundler hasn't finished running) is buried in a list of 7 possibilities, and the empty {} manifest is a strong signal that the bundler is simply still building.
Suggested Solution
Detect when the manifest is empty and show a clearer, more actionable error message:
# In Shakapacker::Manifest
def handle_missing_entry(name, pack_type)
manifest_data = data
bundler_name = config.assets_bundler || "webpack"
# Detect if the manifest is empty - bundler hasn't finished initial build
if manifest_data.empty?
raise MissingEntryError, <<~MSG
#{"━" * 80}
⏳ #{bundler_name.upcase} IS STILL BUILDING
The manifest is empty, which means #{bundler_name} hasn't finished its
initial compilation yet. This typically happens when:
1. You just started the dev server and it's still compiling
2. The dev server crashed during startup
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}
#{"━" * 80}
MSG
end
# Fall through to existing error handling for non-empty manifests
raise MissingEntryError, missing_file_from_manifest_error(full_pack_name(name, pack_type[:type]))
endBenefits
- Immediate clarity - Users instantly know the bundler is still building
- Actionable - Clear next steps (wait, check terminal, look for errors)
- No false positives - Only triggers when manifest is truly empty
- Backward compatible - Falls through to existing error for other cases
Workaround
Until this is implemented, users can add this to config/initializers/shakapacker.rb:
module Shakapacker
module ManifestStillBuildingError
def handle_missing_entry(name, pack_type)
if data.empty?
bundler_name = config.assets_bundler || "webpack"
raise MissingEntryError, "#{bundler_name} is still building. Wait and refresh."
end
super
end
end
Manifest.prepend ManifestStillBuildingError
end