Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 3, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0b20b6a
Update CHANGELOG with detailed migration instructions for breaking ch…
AbanoubGhadban Sep 3, 2025
2e4d5e5
Replace performance comparison link with an image in release notes fo…
AbanoubGhadban Sep 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 20 additions & 5 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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).
Expand Down
20 changes: 17 additions & 3 deletions docs/guides/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Comment on lines +223 to +228
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix broken relative link path.

From docs/guides/configuration.md, docs/release-notes/15.0.0.md resolves to docs/guides/docs/.... Use a root-relative or parent-relative path.

-  # See [15.0.0 Release Notes](docs/release-notes/15.0.0.md) for more details.
+  # See [15.0.0 Release Notes](/docs/release-notes/15.0.0.md) for more details.
+  # (If viewing on GitHub, ../release-notes/15.0.0.md also works.)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# 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
# 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.
# (If viewing on GitHub, ../release-notes/15.0.0.md also works.)
# config.defer_generated_component_packs = false
🤖 Prompt for AI Agents 
In docs/guides/configuration.md around lines 223 to 228, the relative link
"docs/release-notes/15.0.0.md" incorrectly resolves to docs/guides/docs/...;
update the link to use either a root-relative path
(/docs/release-notes/15.0.0.md) or a parent-relative path
(../release-notes/15.0.0.md) so it correctly points to the release notes, and
verify the link renders correctly.

# 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
Expand Down
4 changes: 2 additions & 2 deletions docs/release-notes/15.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)).
Copy link
Collaborator Author

@AbanoubGhadban AbanoubGhadban Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was a markdown format error and was fixed

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

Expand Down Expand Up @@ -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:_

Expand Down
Loading