Update CHANGELOG and release notes of v15.0.0

Author: AbanoubGhadban

CHANGELOG.md

@@ -15,6 +15,13 @@ If you think ShakaCode can help your project, [click here](https://meetings.hubs
 Please follow the recommendations outlined at [keepachangelog.com](http://keepachangelog.com/). Please use the existing headings and styling as a guide, and add a link for the version diff at the bottom of the file. Also, please update the `Unreleased` link to compare to the latest release version.
 
 ## Versions
+### [Unreleased]
+#### Added
+- Configuration option `generated_component_packs_loading_strategy` to control how generated component packs are loaded. It supports `sync`, `async`, and `defer` strategies. [PR 1707](https://github.com/shakacode/react_on_rails/pull/1707) by [judahmeek](https://github.com/judahmeek).
+
+### Removed (Breaking Changes)
+- Removed `defer_generated_component_packs` configuration option. You can use `generated_component_packs_loading_strategy` instead. [PR 1707](https://github.com/shakacode/react_on_rails/pull/1707) by [judahmeek](https://github.com/judahmeek).
+
 ### [15.0.0-alpha.2] - 2025-03-07
 Changes since the last non-beta release.
 

docs/release-notes/15.0.0.md

@@ -17,13 +17,24 @@ Major improvements to component and store hydration:
 - Can use `async` scripts in the page with no fear of race condition
 - No need to use `defer` anymore
 
+### Enhanced Script Loading Strategies
+- New configuration option `generated_component_packs_loading_strategy` replaces `defer_generated_component_packs`
+- Supports three loading strategies:
+  - `:async` - Loads scripts asynchronously (default for Shakapacker ≥ 8.2.0)
+  - `:defer` - Defers script execution until after page load (Doesn't work good with Streamed HTML as it will wait for the full page load before hydrating the components)
+  - `:sync` - Loads scripts synchronously (default for Shakapacker < 8.2.0) (Better to upgrade to Shakapacker 8.2.0 and use `:async` strategy)
+- Improves page performance by optimizing how component packs are loaded
+
 ## Breaking Changes
 
 ### Component Hydration Changes
-- The `defer_generated_component_packs` and `force_load` configurations now default to `false` and `true` respectively. This means components will hydrate early without waiting for the full page load. This improves performance by eliminating unnecessary delays in hydration.
+- The `defer_generated_component_packs` configuration has been removed. Use `generated_component_packs_loading_strategy` instead.
+- The `generated_component_packs_loading_strategy` defaults to `:async` for Shakapacker ≥ 8.2.0 and `:sync` for Shakapacker < 8.2.0.
+- The `force_load` configuration now defaults to `true`.
+- The new default values of `generated_component_packs_loading_strategy: :async` and `force_load: true` work together to optimize component hydration. Components now hydrate as soon as their code and server-rendered HTML are available, without waiting for the full page to load. This parallel processing significantly improves time-to-interactive by eliminating the traditional waterfall of waiting for page load before beginning hydration (It's critical for streamed HTML).
   - The previous need for deferring scripts to prevent race conditions has been eliminated due to improved hydration handling. Making scripts not defer is critical to execute the hydration scripts early before the page is fully loaded.
   - The `force_load` configuration make `react-on-rails` hydrate components immediately as soon as their server-rendered HTML reaches the client, without waiting for the full page load.
-  - If you want to keep the previous behavior, you can set `defer_generated_component_packs: true` or `force_load: false` in your `config/initializers/react_on_rails.rb` file.
+  - If you want to keep the previous behavior, you can set `generated_component_packs_loading_strategy: :defer` or `force_load: false` in your `config/initializers/react_on_rails.rb` file.
   - If we want to keep the original behavior of `force_load` for only one or more components, you can set `force_load: false` in the `react_component` helper or `force_load` configuration.
   - Redux store support `force_load` option now and it uses `config.force_load` value as the default value. Which means that the redux store will hydrate immediately as soon as its server-side data reaches the client. You can override this behavior for individual redux stores by setting `force_load: false` in the `redux_store` helper.
 
@@ -39,6 +50,11 @@ Major improvements to component and store hydration:
   // Code expecting all components to be hydrated
   ```
 
+### Script Loading Strategy Migration
+- If you were previously using `defer_generated_component_packs: true`, use `generated_component_packs_loading_strategy: :defer` instead
+- If you were previously using `defer_generated_component_packs: false`, use `generated_component_packs_loading_strategy: :sync` instead
+- For optimal performance with Shakapacker ≥ 8.2.0, consider using `generated_component_packs_loading_strategy: :async`
+
 ## Store Dependencies for Components
 
 When using Redux stores with multiple components, you need to explicitly declare store dependencies to optimize hydration. Here's how:
@@ -65,12 +81,12 @@ Explicitly declare store dependencies for each component:
 ```erb
 <% redux_store("SimpleStore", props: @app_props_server_render, defer: true) %>
 <%= react_component('ReduxApp', {}, {
-  prerender: true
-  <!-- No need to specify store_dependencies - it automatically depends on SimpleStore -->
+prerender: true
+<!-- No need to specify store_dependencies - it automatically depends on SimpleStore -->
 }) %>
 <%= react_component('ComponentWithNoStore', {}, {
-  prerender: true,
-  store_dependencies: [] <!-- Explicitly declare no store dependencies -->
+prerender: true,
+store_dependencies: [] <!-- Explicitly declare no store dependencies -->
 }) %>
 <%= redux_store_hydration_data %>
 ```