Update CHANGELOG with detailed migration instructions for breaking changes in version 15.0.0 (#1759)

* Update CHANGELOG with detailed migration instructions for breaking changes in version 15.0.0

* Replace performance comparison link with an image in release notes for version 15.0.0

Author: AbanoubGhadban

CHANGELOG.md

@@ -24,21 +24,35 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 Changes since the last non-beta release.
 
 ### [15.0.0] - 2025-08-28
+
 See [Release Notes](docs/release-notes/15.0.0.md) for full details.
 
 ### Removed (Breaking Changes)
-- Deprecated `defer_generated_component_packs` configuration option. You should use `generated_component_packs_loading_strategy` instead. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-- The package is ESM-only now. Please see [Release Notes](docs/release-notes/15.0.0.md#esm-only-package) for more details.
-- `ReactOnRails.reactOnRailsPageLoaded` is now an async function
-- `force_load` configuration now defaults to `true`
-- `defer_generated_component_packs` configuration now defaults to `false`
+
+- Deprecated `defer_generated_component_packs` configuration option. You should use `generated_component_packs_loading_strategy` instead.
+  - Migration:
+    - `defer_generated_component_packs: true` → `generated_component_packs_loading_strategy: :defer`
+    - `defer_generated_component_packs: false` → `generated_component_packs_loading_strategy: :sync`
+    - For best performance, use `generated_component_packs_loading_strategy: :async`
+  - [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- The package is ESM-only now. Migration:
+  - If using `require('react-on-rails')`, upgrade to Node v20.19.0+ or change to `import`.
+  - For TypeScript errors, upgrade to TypeScript 5.8+ and set `module` to `nodenext`.
+- `ReactOnRails.reactOnRailsPageLoaded` is now an async function. Migration:
+  - Add `await` when calling this function: `await ReactOnRails.reactOnRailsPageLoaded()`.
+- `force_load` configuration now defaults to `true`. Migration:
+  - Set `force_load: false` in your config if you want the previous behavior.
+
+For detailed migration instructions, see the [15.0.0 Release Notes](docs/release-notes/15.0.0.md).
 
 #### Fixed
+
 - Enable support for ReactRefreshWebpackPlugin v0.6.0 by adding conditional logic regarding configuration. [PR 1748](https://github.com/shakacode/react_on_rails/pull/1748) by [judahmeek](https://github.com/judahmeek).
 - Replace RenderOptions.renderRequestId and use local trackers instead. This change should only be relevant to ReactOnRails Pro users. [PR 1745](https://github.com/shakacode/react_on_rails/pull/1745) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - Fixed invalid warnings about non-exact versions when using a pre-release version of React on Rails, as well as missing warnings when using different pre-release versions of the gem and the Node package. [PR 1742](https://github.com/shakacode/react_on_rails/pull/1742) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
 
 #### Improved
+
 - Ensured that the RSC payload is injected after the component's HTML markup to improve the performance of the RSC payload injection. [PR 1738](https://github.com/shakacode/react_on_rails/pull/1738) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - Improved RSC rendering flow by eliminating double rendering of server components and reducing the number of HTTP requests.
 - Updated communication protocol between Node Renderer and Rails to version 2.0.0 which supports the ability to upload multiple bundles at once.
@@ -50,6 +64,7 @@ See [Release Notes](docs/release-notes/15.0.0.md) for full details.
     - Include a stack trace when clicked
 
 #### Added
+
 - Configuration option `generated_component_packs_loading_strategy` to control how generated component packs are loaded. It supports `sync`, `async`, and `defer` strategies. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - Support for returning React component from async render-function. [PR 1720](https://github.com/shakacode/react_on_rails/pull/1720) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - React Server Components Support (Pro Feature) [PR 1644](https://github.com/shakacode/react_on_rails/pull/1644) by [AbanoubGhadban](https://github.com/AbanoubGhadban).

docs/guides/configuration.md

@@ -213,9 +213,23 @@ ReactOnRails.configure do |config|
   # config.server_bundle_js_file for the filename.
   config.make_generated_server_bundle_the_entrypoint = false
 
-  # Default is false
-  # Set this to true to have `defer: true` added to your `append_javascript_pack` calls for generated entrypoints.
-  config.defer_generated_component_packs = false
+  # Configuration for how generated component packs are loaded.
+  # Options: :sync, :async, :defer
+  # - :sync (default for Shakapacker < 8.2.0): Loads scripts synchronously
+  # - :async (default for Shakapacker ≥ 8.2.0): Loads scripts asynchronously for better performance
+  # - :defer: Defers script execution until after page load
+  config.generated_component_packs_loading_strategy = :async
+
+  # DEPRECATED: Use `generated_component_packs_loading_strategy` instead.
+  # Migration: `defer_generated_component_packs: true` → `generated_component_packs_loading_strategy: :defer`
+  # Migration: `defer_generated_component_packs: false` → `generated_component_packs_loading_strategy: :sync`
+  # See [15.0.0 Release Notes](docs/release-notes/15.0.0.md) for more details.
+  # config.defer_generated_component_packs = false
+
+  # Default is true
+  # When true, components hydrate immediately as soon as their server-rendered HTML reaches the client,
+  # without waiting for the full page load. This improves time-to-interactive performance.
+  config.force_load = true
 
   ################################################################################
   # I18N OPTIONS

docs/release-notes/15.0.0.md

@@ -1,6 +1,6 @@
 # React on Rails 15.0.0 Release Notes
 
-Also see the [Changelog for 15.0.0]([url](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md#1500---2025-08-28)).
+Also see the [Changelog for 15.0.0](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md#1500---2025-08-28).
 
 ## Major Features
 
@@ -32,7 +32,7 @@ This optimization is particularly impactful for:
 
 _Performance improvement visualization:_
 
-[Performance comparison showing early hydration improvement](https://drive.google.com/file/d/1rArLh8EX1dKBWksZ1Ypbj4_K1B5Fn7dq/view)
+![Performance comparison showing early hydration improvement](../assets/early-hydration-performance-comparison.jpg)
 
 _The image above demonstrates the dramatic performance improvement:_