Skip to content

Commit d9a6e91

Browse files
justin808claude
justin808
and
claude
committed
Add upgrade guide for v16.0.x to v16.1.1
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 <[email protected]>
1 parent 16b3908 commit d9a6e91

File tree

2 files changed

+296
-1
lines changed

2 files changed

+296
-1
lines changed

‎docs/upgrading/release-notes/16.1.0.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# React on Rails 16.1.x Release Notes
2+
3+
## Upgrading from 16.0.x to 16.1.x
4+
5+
This guide covers upgrading from React on Rails v16.0.x to v16.1.1.
6+
7+
### Step 1: Update Dependencies
8+
9+
**Gemfile:**
10+
11+
```ruby
12+
gem "react_on_rails", "~> 16.1.1"
13+
gem "shakapacker", "~> 8.2.0" # Recommended for compatibility
14+
```
15+
16+
**package.json:**
17+
18+
```json
19+
{
20+
"dependencies": {
21+
"react-on-rails": "16.1.1",
22+
"shakapacker": "8.2.0"
23+
}
24+
}
25+
```
26+
27+
**Important:** The shakapacker gem and npm package versions MUST match exactly.
28+
29+
### Step 2: Install Updates
30+
31+
```bash
32+
bundle update react_on_rails shakapacker
33+
yarn install # or npm install
34+
```
35+
36+
### Step 3: Run the Generator (Optional)
37+
38+
Run the generator to get the latest improvements:
39+
40+
```bash
41+
rails generate react_on_rails:install
42+
```
43+
44+
**Note:** The generator will prompt to overwrite files. Review each change carefully, especially if you have customizations. Key files that may be updated:
45+
46+
- `bin/dev` - Enhanced development workflow
47+
- Webpack configurations
48+
- `shakapacker.yml` settings
49+
- TypeScript configuration
50+
51+
### Step 4: Use the New Doctor Command
52+
53+
v16.1.0 introduces a diagnostic rake task to validate your setup:
54+
55+
```bash
56+
rake react_on_rails:doctor
57+
```
58+
59+
For detailed output:
60+
61+
```bash
62+
VERBOSE=true rake react_on_rails:doctor
63+
```
64+
65+
The doctor command checks:
66+
67+
- Environment prerequisites
68+
- Dependencies and version compatibility
69+
- Rails integration
70+
- Webpack configuration
71+
- Shakapacker setup
72+
73+
### Step 5: Test Your Application
74+
75+
```bash
76+
# Test asset compilation
77+
bundle exec rails assets:precompile
78+
79+
# Test development server
80+
bin/dev
81+
82+
# Run your test suite
83+
bundle exec rspec # or your test command
84+
```
85+
86+
## New Features in v16.1.0
87+
88+
### Server Bundle Security
89+
90+
New configuration options for enhanced server bundle security:
91+
92+
```ruby
93+
# config/initializers/react_on_rails.rb
94+
ReactOnRails.configure do |config|
95+
# Directory for server bundle output (default: "ssr-generated")
96+
# Set to nil to load from public directory (legacy behavior)
97+
config.server_bundle_output_path = "ssr-generated"
98+
99+
# When enabled, server bundles only load from private directories
100+
# (default: false for backward compatibility)
101+
config.enforce_private_server_bundles = true
102+
end
103+
```
104+
105+
**Bundle Path Resolution Logic:**
106+
107+
1. If `server_bundle_output_path` is set, server bundles load from that directory
108+
2. If not set, falls back to client bundle directory (public output path)
109+
3. When `enforce_private_server_bundles` is enabled:
110+
- Server bundles only load from the private directory
111+
- No fallback to public directory (improved security)
112+
113+
### Doctor Rake Task
114+
115+
New diagnostic command for troubleshooting:
116+
117+
```bash
118+
rake react_on_rails:doctor
119+
```
120+
121+
Provides comprehensive checks for:
122+
123+
- Environment prerequisites
124+
- Dependency versions
125+
- Rails integration
126+
- Webpack configuration
127+
- Common setup issues
128+
129+
### Generator Improvements
130+
131+
- **Modern TypeScript patterns**: Better type inference instead of explicit annotations
132+
- **Optimized tsconfig.json**: Uses `"moduleResolution": "bundler"` for bundler compatibility
133+
- **Enhanced Redux TypeScript**: Improved type safety with modern React patterns (useMemo, type-only imports)
134+
- **Smart bin/dev defaults**: Auto-navigates to `/hello_world` route for immediate component visibility
135+
- **Cleaner generated code**: Follows modern React and TypeScript best practices
136+
137+
## Deprecations
138+
139+
### `generated_assets_dirs` Configuration
140+
141+
The `config.generated_assets_dirs` option is deprecated. Remove it from `config/initializers/react_on_rails.rb`.
142+
143+
**Why:** Since Shakapacker is now required, asset paths are automatically determined from `shakapacker.yml`.
144+
145+
**Migration:** Use `public_output_path` in `config/shakapacker.yml` to customize asset output location.
146+
147+
### `generated_assets_full_path` Method
148+
149+
Use `public_bundles_full_path` instead for clarity about webpack bundles in public directories.
150+
151+
## Bug Fixes in v16.1.1
152+
153+
- **React Server Components**: Fixed bug in resolving `react-server-client-manifest.json` file path. The manifest file path is now correctly resolved using `bundle_js_file_path` for improved configuration flexibility. [PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)
154+
155+
## Bug Fixes in v16.1.0
156+
157+
- **Doctor rake task**: Fixed LoadError when using packaged gem
158+
- **Packs generator**: Fixed error when `server_bundle_js_file` is empty
159+
- **Non-Packer compatibility**: Fixed NoMethodError in environments without Shakapacker
160+
- **Shakapacker version requirements**: Fixed inconsistent version requirements between basic pack generation (6.5.1+) and advanced auto-bundling (7.0.0+)
161+
162+
## Security Enhancements
163+
164+
- **Private Server Bundle Enforcement**: Server bundles bypass public directory fallbacks when `enforce_private_server_bundles` is enabled
165+
- **Path Validation**: Validates `server_bundle_output_path` points to private directories when enforcement is enabled
166+
- **Command injection fixes**: Replaced unsafe string interpolation with secure array-based system calls
167+
- **Input validation**: Enhanced package manager validation and argument sanitization
168+
- **Hardened DOM selectors**: Using `CSS.escape()` and proper JavaScript escaping for XSS protection
169+
170+
## Version Compatibility
171+
172+
| react_on_rails | shakapacker (gem) | shakapacker (npm) | Rails | Ruby |
173+
| -------------- | ----------------- | ----------------- | ----- | ---- |
174+
| 16.1.x | 8.2.0+ | 8.2.0+ | 6.0+ | 3.2+ |
175+
| 16.0.x | 6.0.0+ | 6.0.0+ | 6.0+ | 3.2+ |
176+
177+
**Recommended versions:**
178+
179+
- Shakapacker 8.2.0 (gem and npm versions must match)
180+
- React 18+
181+
- Node.js 20+
182+
- Ruby 3.2+
183+
184+
## Common Upgrade Issues
185+
186+
### Generator Prerequisites Error
187+
188+
```
189+
ERROR: You have uncommitted changes
190+
```
191+
192+
**Solution:** Commit or stash your changes before running the generator.
193+
194+
### Shakapacker Version Mismatch
195+
196+
```
197+
Shakapacker gem and node package versions do not match
198+
```
199+
200+
**Solution:** Ensure both gem and npm package are the same version:
201+
202+
```bash
203+
# Check versions
204+
bundle show shakapacker
205+
yarn list shakapacker # or npm ls shakapacker
206+
207+
# Update to match
208+
bundle update shakapacker
209+
yarn upgrade [email protected]
210+
```
211+
212+
### Test Failures After Upgrade
213+
214+
1. **Rebuild ReScript files** (if using ReScript):
215+
216+
```bash
217+
yarn res:build
218+
```
219+
220+
2. **Clear webpack cache**:
221+
222+
```bash
223+
rm -rf node_modules/.cache
224+
rm -rf public/packs*
225+
```
226+
227+
3. **Precompile assets**:
228+
```bash
229+
rails assets:precompile
230+
```
231+
232+
### Server Bundle Not Found
233+
234+
If you're using server-side rendering and the server bundle isn't found:
235+
236+
1. Check `config.server_bundle_output_path` is correctly set
237+
2. Run `rake react_on_rails:doctor` to diagnose issues
238+
3. Verify webpack builds both client and server bundles
239+
240+
## Related Resources
241+
242+
- [Changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md)
243+
- [Configuration Reference](../../api-reference/configuration.md)
244+
- [Troubleshooting Guide](../../deployment/troubleshooting.md)
245+
- [Example upgrade PR: react-webpack-rails-tutorial#654](https://github.com/shakacode/react-webpack-rails-tutorial/pull/654)

‎docs/upgrading/upgrading-react-on-rails.md‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,57 @@ rails generate react_on_rails:install
2121
- `shakapacker.yml` settings
2222
- other configuration files
2323

24-
## Upgrading to v16
24+
## Upgrading to v16.1.x (from v16.0.x)
25+
26+
For detailed upgrade instructions, see the [v16.1.x Release Notes](release-notes/16.1.0.md).
27+
28+
### Quick Summary
29+
30+
v16.1.x is a minor release with new features and bug fixes:
31+
32+
- **New `rake react_on_rails:doctor` command** for diagnosing setup issues
33+
- **Server bundle security enhancements** with `server_bundle_output_path` and `enforce_private_server_bundles` options
34+
- **Generator improvements** with modern TypeScript patterns and better defaults
35+
- **Bug fix (v16.1.1)**: Fixed RSC manifest file path resolution
36+
37+
### Upgrade Steps
38+
39+
1. Update dependencies:
40+
41+
```ruby
42+
# Gemfile
43+
gem "react_on_rails", "~> 16.1.1"
44+
gem "shakapacker", "~> 8.2.0"
45+
```
46+
47+
```json
48+
// package.json - versions must match exactly
49+
{
50+
"dependencies": {
51+
"react-on-rails": "16.1.1",
52+
"shakapacker": "8.2.0"
53+
}
54+
}
55+
```
56+
57+
2. Install and verify:
58+
59+
```bash
60+
bundle update react_on_rails shakapacker
61+
yarn install
62+
rake react_on_rails:doctor # New diagnostic command
63+
```
64+
65+
3. Optionally run generator for latest improvements:
66+
```bash
67+
rails generate react_on_rails:install
68+
```
69+
70+
### Deprecation Notice
71+
72+
Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`.
73+
74+
## Upgrading to v16 (from v14/v15)
2575

2676
### Breaking Changes
2777

0 commit comments

Comments
 (0)