Fix incorrect defer_generated_component_packs = false migration guidance

[justin808]

Summary

Follow-up to #4432 / #4419; found by post-merge audit.

The 17.0.0 migration guidance for the removed config.defer_generated_component_packs option was wrong in several docs. It told upgraders:

config.defer_generated_component_packs = false → config.generated_component_packs_loading_strategy = :sync

That mapping is incorrect and causes a performance regression if followed.

The defect

The removed shim was truthy-gated. In the old Configuration#validate_generated_component_packs_loading_strategy:

if defer_generated_component_packs
  ...
  self.generated_component_packs_loading_strategy ||= :defer
end

Only = true did anything (it set :defer). = false was a no-op — the whole block was skipped and the strategy fell through to the default. So false never meant :sync. Telling upgraders to set :sync forces synchronous (blocking) pack loading, which is slower than the default for most apps.

Correct behavior (verified against configuration.rb on main)

validate_generated_component_packs_loading_strategy sets the default when no strategy is configured:

• Shakapacker >= 8.2.0 (PackerUtils.supports_async_loading?): :async for Pro users, :defer for non-Pro.
• Older Shakapacker (strategy nil): :sync.

So the correct migration for defer_generated_component_packs = false is: just delete the line — the default loading strategy applies. Set :sync explicitly only if you specifically relied on synchronous loading. (= true → :defer remains correct and is unchanged.)

I also corrected the inaccurate "otherwise :defer" fallback phrasing so it matches the real default logic above.

Files fixed (source docs)

• CHANGELOG.md — the [Core] Drop deprecation-tombstone config attrs (generated_assets_dirs, skip_display_none, defer_generated_component_packs) during the 17.0.0 RC window #4419/Drop deprecation-tombstone config options for 17.0.0 (#4419) #4432 entry.
• docs/oss/upgrading/upgrading-react-on-rails.md
• docs/oss/configuration/configuration-deprecated.md
• docs/oss/configuration/README.md
• llms-full.txt — regenerated via node script/generate-llms-full.mjs (not hand-edited).

Out of scope (left unchanged): the frozen v16-era historical records that carry the same phrasing for the original deprecation — CHANGELOG.md:1107 and docs/oss/upgrading/release-notes/16.0.0.md:93. These document a shipped past release's deprecation notice, not the #4419/#4432 removal, so I left them to avoid rewriting release history.

Additional cleanup (approved in the same PR)

react_on_rails/rakelib/example_type.rb: removed the now-dead require_relative of .../react_on_rails/utils. #4418 relocated rails_version_less_than into a local Rake-only helper in this file, and the only remaining Utils reference is a comment — no functional ReactOnRails::Utils. call remains.

Codex Decision Log

• Verified ground truth first. Read validate_generated_component_packs_loading_strategy on main and traced the removed shim in git history (if defer_generated_component_packs … ||= :defer) to confirm the truthy gate before wording anything.
• false → delete the line, not → :sync. The no-op semantics mean deleting preserves prior behavior; forcing :sync would be a regression.
• Fallback phrasing corrected from ":async for Pro when Shakapacker supports it, otherwise :defer" to the accurate three-case default (:async Pro / :defer non-Pro on Shakapacker 8.2.0+, :sync on older).
• Kept the diff minimal. Reverted an unrelated pre-existing llms-full-pro.txt drift (about cached_static_rsc_component) that the generator surfaced but which is unrelated to this fix. Left frozen v16 historical release notes untouched.
• example_type.rb require confirmed dead by grep (Utils appears only in a comment) before removing.

Validation

• node script/generate-llms-full.mjs --validate → exit 0.
• grep -n "defer_generated_component_packs = false" llms-full.txt → corrected guidance ("delete the line", no blanket → :sync).
• Repo-wide grep confirms no remaining incorrect blanket false → :sync in any current-version source doc.
• bundle exec rubocop rakelib/example_type.rb → no offenses.
• Prettier (3.6.2) clean on all changed docs; lefthook pre-commit hooks all passed.

Confidence note

High confidence. The fix is documentation-only plus one dead-require removal, verified against the authoritative source (configuration.rb) and git history. No runtime behavior changes. llms-full validate passes and the diff is scoped to the intended files.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified upgrade guidance for deprecated configuration options, including the correct handling of removed defer_generated_component_packs settings.
  • Updated migration notes to explain when to delete old settings, when to use deferred loading, and when synchronous loading must be set explicitly.
  • Added clearer usage details for a static RSC component helper, including caching behavior, required options, and rendering diagnostics.
  • Improved explanation of worker restart timeout behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 54f60027-5225-4152-a65c-932c92892c70

📥 Commits

Reviewing files that changed from the base of the PR and between 92e563f and f3642cc.

📒 Files selected for processing (6)

• CHANGELOG.md
• docs/oss/configuration/README.md
• docs/oss/configuration/configuration-deprecated.md
• docs/oss/upgrading/upgrading-react-on-rails.md
• llms-full.txt
• react_on_rails/rakelib/example_type.rb

💤 Files with no reviewable changes (1)

• react_on_rails/rakelib/example_type.rb

---

Walkthrough

Documentation-only changes correct migration guidance for the removed defer_generated_component_packs config option across CHANGELOG.md, three docs files, and llms-full.txt, clarifying false was a no-op. Also adds RSC helper docs and a timeout clarification in llms-full.txt, plus an unrelated require path change in a rakelib file.

Changes

Deprecation migration doc corrections

Layer / File(s)	Summary
Changelog wording update CHANGELOG.md	Rewords Breaking Changes entry to clarify defer_generated_component_packs = false was truthy-gated and a no-op.
Configuration reference doc corrections docs/oss/configuration/README.md, docs/oss/configuration/configuration-deprecated.md	Replaces false → :sync mapping guidance with instructions to delete the line or explicitly set :sync.
Upgrade guide correction docs/oss/upgrading/upgrading-react-on-rails.md	Removes the false mapping bullet, documents default loading strategy behavior across Pro/non-Pro and Shakapacker versions.
llms-full.txt aggregated doc updates llms-full.txt	Applies same migration corrections in multiple sections, clarifies gracefulWorkerRestartTimeout, and adds documentation for a new cached_static_rsc_component helper.

Rakelib Require Change

Layer / File(s)	Summary
Update task_helpers require react_on_rails/rakelib/example_type.rb	Changes the require from a computed react_on_rails/utils path to a local task_helpers require.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• shakacode/react_on_rails#4432: Both PRs update the same migration/deprecation documentation for config.defer_generated_component_packs behavior.

Suggested labels: ready-for-hosted-ci

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main doc fix: correcting migration guidance for defer_generated_component_packs = false.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg/4419-fix-defer-migration-guidance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR corrects migration docs for the removed generated component pack defer option. The main changes are:

• Updated current v17 migration guidance for defer_generated_component_packs = false.
• Clarified the default loading strategy by Pro and Shakapacker support.
• Regenerated llms-full.txt from the current docs.
• Removed an unused rake-only ReactOnRails::Utils require.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.
• The docs now match the current default strategy behavior.
• The removed rake require does not leave a remaining runtime dependency in the changed file.

Important Files Changed

Filename	Overview
CHANGELOG.md	Corrects the v17 changelog guidance so defer_generated_component_packs = false maps to deleting the line instead of forcing :sync.
docs/oss/configuration/README.md	Updates the configuration example comment for the removed defer_generated_component_packs option.
docs/oss/configuration/configuration-deprecated.md	Expands the deprecated configuration guidance with the old truthy-gated behavior and current defaults.
docs/oss/upgrading/upgrading-react-on-rails.md	Updates the upgrade guide to preserve old false behavior by deleting the removed option.
llms-full.txt	Regenerates the combined LLM documentation to include the corrected migration text and existing source-doc updates.
react_on_rails/rakelib/example_type.rb	Removes a no-longer-used ReactOnRails::Utils require from the rake example type helper.

_{Reviews (1): Last reviewed commit: "Fix incorrect defer_generated_component_..." | Re-trigger Greptile}

[claude]

Review

This is a well-scoped documentation-accuracy fix. It corrects four current-version docs (CHANGELOG.md, upgrading-react-on-rails.md, configuration-deprecated.md, configuration/README.md) plus the regenerated llms-full.txt, and removes one now-dead require_relative in example_type.rb. I checked the corrected guidance against Configuration#validate_generated_component_packs_loading_strategy on main — the new default-strategy description (:async Pro / :defer non-Pro on Shakapacker >= 8.2.0, :sync otherwise) matches the code exactly, and the dead-require removal is safe (Utils only appears in a comment in that file now).

Finding

• CHANGELOG.md:1120 and docs/oss/upgrading/release-notes/16.0.0.md:93 — the same incorrect defer_generated_component_packs: false -> generated_component_packs_loading_strategy: :sync mapping this PR fixes elsewhere still stands in the v16.0.0 changelog entry and its linked release notes. CHANGELOG.md:1070 explicitly points readers to release-notes/16.0.0.md as 'the complete migration guide' for that version, so this isn't inert historical prose — it's live, reachable guidance. Since the removed shim was truthy-gated from the start (per this PR's own root-cause analysis), the same wrong mapping was very likely wrong back in v16.0.0 too, and anyone upgrading through v16 today will still be steered into the same performance regression this PR is trying to eliminate elsewhere. Worth at least a corrective note, if not applying the same fix there. (Left as an inline comment on CHANGELOG.md:30 since GitHub won't let me anchor a comment on the unchanged line 1120 directly.)

Minor / optional

• docs/oss/configuration/configuration-deprecated.md — the unchanged 'New:' code sample right after the fix (config.generated_component_packs_loading_strategy = :defer # or :sync) now sits awkwardly next to the corrected text explaining that false should just be deleted rather than mapped to :sync. Not introduced by this PR, but worth a look while in the area.

No security or performance concerns — this is docs-only plus a dead-code removal.