Add upgrade guide for v16.0.x to v16.1.1 #2130
Conversation
Adds comprehensive documentation for upgrading from React on Rails v16.0.x to v16.1.1: - New release notes file: docs/upgrading/release-notes/16.1.0.md - Step-by-step upgrade instructions - New features: doctor rake task, server bundle security options - Generator improvements with modern TypeScript patterns - Deprecations and migration guidance - Common troubleshooting issues - Version compatibility matrix - Updated docs/upgrading/upgrading-react-on-rails.md - Added quick upgrade summary for v16.1.x - Links to detailed release notes Closes #1831 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
WalkthroughAdded and updated upgrade documentation for v16.1.x: a new release notes file with step-by-step upgrade workflow, features, deprecations, bug fixes, and troubleshooting; and an updated upgrading guide that adds a v16.1.x section, dependency instructions, and a deprecation note for Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/upgrading/release-notes/16.1.0.md (1)
188-188: Add language specification to fenced code blocks.Lines 188 and 196 contain fenced code blocks without language identifiers. Per markdown best practices, these should specify the language to enable proper syntax highlighting.
- ``` + ```bash ERROR: You have uncommitted changes - ``` + ```bash- ``` + ```bash # Check versions bundle show shakapacker yarn list shakapacker # or npm ls shakapacker - ``` + ```bashAlso applies to: 196-196
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/upgrading/release-notes/16.1.0.md(1 hunks)docs/upgrading/upgrading-react-on-rails.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
ALWAYS ensure files end with a newline character before committing/pushing
Files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
🧠 Learnings (6)
📓 Common learnings
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm package
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG*.md : Use changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm package
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
Repo: shakacode/react_on_rails PR: 1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
Repo: shakacode/react_on_rails PR: 1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/upgrading/release-notes/16.1.0.md
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG*.md : Use changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
Repo: shakacode/react_on_rails PR: 1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
docs/upgrading/release-notes/16.1.0.md
🪛 markdownlint-cli2 (0.18.1)
docs/upgrading/release-notes/16.1.0.md
188-188: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
196-196: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: claude-review
🔇 Additional comments (4)
docs/upgrading/upgrading-react-on-rails.md (2)
24-73: Well-structured v16.1.x upgrade section with clear navigation.The section appropriately links to the detailed release notes as the authoritative source while providing a quick summary and streamlined upgrade steps here. The progression (dependencies → install → generator → deprecations) follows best practices. Dependency versions are consistent across both files.
1-473: Ensure file ends with a newline character.Per coding guidelines, all files must end with a newline character before committing. Please verify this file ends with a trailing newline.
docs/upgrading/release-notes/16.1.0.md (2)
1-244: Comprehensive and well-organized release notes covering all upgrade objectives.The documentation effectively covers all requirements from issue #1831: step-by-step upgrade workflow, new features (doctor command, server bundle security), deprecations with migration guidance, bug fixes with PR references (correctly formatted without hash), security enhancements, version compatibility matrix, and thorough troubleshooting section. The structure progresses logically from upgrade steps to features to troubleshooting, making it user-friendly.
1-244: Ensure file ends with a newline character.Per coding guidelines, all files must end with a newline character before committing. Please verify this file ends with a trailing newline.
|
@claude review this PR. |
|
Claude finished @justin808's task —— View job Review of PR #2130: Add upgrade guide for v16.0.x to v16.1.1
|
- Use exact versions in examples (not ~>) - Remove package manager-specific commands (support all) - Reduce verbosity for minor/patch release upgrade - Focus on essential information
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/upgrading/upgrading-react-on-rails.md (1)
1-334: Ensure file ends with a newline character.The file must end with a newline per coding guidelines.
Verify that a newline character is present at the end of the file (after the final content on line 334).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/upgrading/release-notes/16.1.0.md(1 hunks)docs/upgrading/upgrading-react-on-rails.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
ALWAYS ensure files end with a newline character before committing/pushing
Files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
🧠 Learnings (8)
📓 Common learnings
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm package
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG*.md : Use changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm package
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-04-26T21:55:55.874Z
Learnt from: alexeyr-ci2
Repo: shakacode/react_on_rails PR: 1732
File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44
Timestamp: 2025-04-26T21:55:55.874Z
Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-09-16T08:01:11.146Z
Learnt from: justin808
Repo: shakacode/react_on_rails PR: 1770
File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2
Timestamp: 2025-09-16T08:01:11.146Z
Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to /CHANGELOG*.md : Use changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-02-12T16:38:06.537Z
Learnt from: Romex91
Repo: shakacode/react_on_rails PR: 1697
File: package-scripts.yml:28-28
Timestamp: 2025-02-12T16:38:06.537Z
Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.
Applied to files:
docs/upgrading/release-notes/16.1.0.mddocs/upgrading/upgrading-react-on-rails.md
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: Applies to lib/react_on_rails/*.rb : Create RBS signature files for new Ruby files in `lib/react_on_rails/` by adding corresponding `.rbs` file in `sig/react_on_rails/`, adding to Steepfile, and validating before committing
Applied to files:
docs/upgrading/release-notes/16.1.0.md
📚 Learning: 2025-11-25T08:05:17.804Z
Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-25T08:05:17.804Z
Learning: The `react_on_rails_pro/` directory has its own Prettier/ESLint configuration and must be linted separately
Applied to files:
docs/upgrading/release-notes/16.1.0.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: claude-review
🔇 Additional comments (1)
docs/upgrading/release-notes/16.1.0.md (1)
64-64: Add author attribution to PR reference.Per changelog format conventions, PR references should include author attribution.
Apply this diff to add the missing author information:
-- Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)) +- Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [@username](https://github.com/username))Please replace
@usernamewith the actual GitHub username of the PR author. Based on learnings, this is the standard format used in the React on Rails changelog.⛔ Skipped due to learnings
Learnt from: CR Repo: shakacode/react_on_rails PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T08:05:17.804Z Learning: Applies to /CHANGELOG*.md : Use changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash in PR number)Learnt from: CR Repo: shakacode/react_on_rails PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T08:05:17.804Z Learning: Applies to /CHANGELOG.md : Update `/CHANGELOG.md` for user-visible changes (features, bug fixes, breaking changes, deprecations, performance improvements) to the open-source React on Rails gem and npm packageLearnt from: CR Repo: shakacode/react_on_rails PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T08:05:17.804Z Learning: Distinguish hypothetical fixes from confirmed fixes in commit messages and PR descriptionsLearnt from: CR Repo: shakacode/react_on_rails PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T08:05:17.804Z Learning: Applies to lib/react_on_rails/*.rb : Create RBS signature files for new Ruby files in `lib/react_on_rails/` by adding corresponding `.rbs` file in `sig/react_on_rails/`, adding to Steepfile, and validating before committingLearnt from: alexeyr-ci2 Repo: shakacode/react_on_rails PR: 1732 File: spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx:40-44 Timestamp: 2025-04-26T21:55:55.874Z Learning: In the react_on_rails project, files under `app-react16` directories are copied/moved to corresponding `/app` directories during the conversion process (removing the `-react16` suffix), which affects their relative import paths at runtime.Learnt from: CR Repo: shakacode/react_on_rails PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T08:05:17.804Z Learning: Applies to sig/react_on_rails/**/*.rbs : In RBS type signature files, define type signatures that correspond to Ruby files in `lib/react_on_rails/`Learnt from: justin808 Repo: shakacode/react_on_rails PR: 1770 File: lib/generators/react_on_rails/templates/base/base/app/javascript/src/HelloWorld/ror_components/HelloWorld.client.jsx:2-2 Timestamp: 2025-09-16T08:01:11.146Z Learning: React on Rails uses webpack CSS Modules configuration with namedExports: true, which requires the import syntax `import * as style from './file.module.css'` rather than the default export pattern. This configuration enables better tree shaking and bundle size optimization for CSS modules.Learnt from: Romex91 Repo: shakacode/react_on_rails PR: 1697 File: package-scripts.yml:28-28 Timestamp: 2025-02-12T16:38:06.537Z Learning: The file `node_package/lib/ReactOnRails.full.js` is autogenerated during the build process and should not be present in the repository.Learnt from: AbanoubGhadban Repo: shakacode/react_on_rails PR: 1644 File: lib/react_on_rails/helper.rb:190-197 Timestamp: 2025-02-18T13:08:01.477Z Learning: RSC support validation in React on Rails Pro is handled through a chain of validations: 1. Pro version check in `run_stream_inside_fiber` 2. RSC support check during pack generation via `ReactOnRailsPro.configuration.enable_rsc_support` 3. RSC support validation during component registration This makes additional validation in the helper methods unnecessary.Learnt from: CR Repo: shakacode/react_on_rails PR: 0 File: CLAUDE.md:0-0 Timestamp: 2025-11-25T08:05:17.804Z Learning: The `react_on_rails_pro/` directory has its own Prettier/ESLint configuration and must be linted separatelyLearnt from: AbanoubGhadban Repo: shakacode/react_on_rails PR: 1644 File: lib/react_on_rails/helper.rb:190-197 Timestamp: 2025-02-18T13:08:01.477Z Learning: RSC support validation is handled in deeper level calls of the React on Rails Pro codebase, so it doesn't need to be validated again in the `rsc_payload_react_component` helper method.
| # React on Rails 16.1.x Release Notes | ||
|
|
||
| ## Upgrading from 16.0.x to 16.1.x | ||
|
|
||
| Update your gem and npm package versions: | ||
|
|
||
| ```ruby | ||
| # Gemfile | ||
| gem "react_on_rails", "16.1.1" | ||
| gem "shakapacker", "8.2.0" | ||
| ``` | ||
|
|
||
| ```json | ||
| // package.json | ||
| { | ||
| "dependencies": { | ||
| "react-on-rails": "16.1.1", | ||
| "shakapacker": "8.2.0" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Then run `bundle install` and your package manager's install command. | ||
|
|
||
| **Important:** The shakapacker gem and npm package versions must match exactly. | ||
|
|
||
| ## New Features in v16.1.0 | ||
|
|
||
| ### Doctor Rake Task | ||
|
|
||
| New diagnostic command for troubleshooting setup issues: | ||
|
|
||
| ```bash | ||
| rake react_on_rails:doctor | ||
| VERBOSE=true rake react_on_rails:doctor # For detailed output | ||
| ``` | ||
|
|
||
| ### Server Bundle Security | ||
|
|
||
| New configuration options for enhanced server bundle security: | ||
|
|
||
| ```ruby | ||
| # config/initializers/react_on_rails.rb | ||
| ReactOnRails.configure do |config| | ||
| # Directory for server bundle output (default: "ssr-generated") | ||
| config.server_bundle_output_path = "ssr-generated" | ||
|
|
||
| # When enabled, server bundles only load from private directories | ||
| config.enforce_private_server_bundles = true | ||
| end | ||
| ``` | ||
|
|
||
| ### Generator Improvements | ||
|
|
||
| - Modern TypeScript patterns with better type inference | ||
| - Optimized tsconfig.json with `"moduleResolution": "bundler"` | ||
| - Enhanced Redux TypeScript integration | ||
| - Smart `bin/dev` defaults | ||
|
|
||
| ## Bug Fixes | ||
|
|
||
| ### v16.1.1 | ||
|
|
||
| - Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)) | ||
|
|
||
| ### v16.1.0 | ||
|
|
||
| - Fixed LoadError in `rake react_on_rails:doctor` when using packaged gem | ||
| - Fixed packs generator error when `server_bundle_js_file` is empty | ||
| - Fixed NoMethodError in environments without Shakapacker | ||
| - Fixed inconsistent Shakapacker version requirements | ||
|
|
||
| ## Deprecations | ||
|
|
||
| Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`. | ||
|
|
||
| ## Related Resources | ||
|
|
||
| - [Changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) | ||
| - [Configuration Reference](../../api-reference/configuration.md) |
There was a problem hiding this comment.
Ensure file ends with a newline character.
The file must end with a newline per coding guidelines.
Add a newline at the end of line 80 (after the closing markdown content).
🤖 Prompt for AI Agents
docs/upgrading/release-notes/16.1.0.md lines 1-80: the file is missing a
trailing newline at EOF; open the file and add a single newline character after
the final line so the file ends with a newline, then save.
Code Review: Upgrade Guide for v16.0.x to v16.1.1Thank you for creating this comprehensive upgrade documentation! Overall, this is a well-structured and helpful guide for users upgrading from v16.0.x to v16.1.x. Below is my detailed feedback: ✅ Strengths
📝 Suggestions for Improvement1. Security Enhancements MissingThe CHANGELOG includes a detailed "Security Enhancements" section for v16.1.0:
Recommendation: Consider adding a "Security Enhancements" section to the release notes to highlight these important fixes, especially since security improvements are highly relevant to users. 2. Version Compatibility Matrix MissingThe PR description mentions "Version compatibility matrix" but this does not appear in the actual release notes file. Recommendation: Consider adding a simple compatibility table showing supported Ruby, Node.js, Shakapacker, and React versions. 3. Generator Improvements Could Be More SpecificThe generator improvements section (lines 53-58) lists features but does not clarify when users will see them. Recommendation: Add a brief note that these improvements only affect newly generated code from rails g react_on_rails:install or component generators. Existing applications are unaffected. 4. Link Format and AttributionLine 64 uses a different format than the CHANGELOG - missing author attribution. Recommendation: For consistency and giving proper attribution, add author credits to match the CHANGELOG format used in the main project. 5. Common Upgrade Issues SectionThe PR description mentions "Common troubleshooting issues" but these do not appear in the release notes. Recommendation: Consider adding a "Common Upgrade Issues" section with solutions to known problems like Shakapacker version mismatches. 6. Pro License FeaturesThe CHANGELOG has extensive "Pro License Features" section that is not mentioned in the release notes:
Recommendation: While these might be intended for Pro-only documentation, a brief note might help users understand what features require Pro. 🔍 Technical Accuracy✅ All version numbers are accurate 🎯 Best Practices Compliance✅ Follows project convention for release notes structure 📋 Test Plan VerificationFrom PR description:
SummaryThis is high-quality documentation that will be very helpful for users upgrading to v16.1.x. The main suggestions are:
The current version is ready to merge as-is, but these additions would make it even more comprehensive and user-friendly. Great work on creating thorough upgrade documentation! 🎉 |
Summary
docs/upgrading/release-notes/16.1.0.mdChanges
New:
docs/upgrading/release-notes/16.1.0.mdComplete upgrade guide covering:
rake react_on_rails:doctordiagnostic commandserver_bundle_output_path,enforce_private_server_bundles)generated_assets_dirs)Updated:
docs/upgrading/upgrading-react-on-rails.mdCloses #1831
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.