Documentation: Add upgrade guide for v16.0.x to v16.1.1 #1831
Description
Summary
Based on a recent upgrade from v16.0.1.rc.2 to v16.1.1, there are several important steps and improvements that should be documented to help users upgrade smoothly.
Suggested Documentation Additions
1. Upgrade Steps Section
Add a dedicated section for upgrading from v16.0.x to v16.1.1:
## Upgrading from 16.0.x to 16.1.1 ### Step 1: Update Dependencies Update both the gem and npm package versions: **Gemfile:** ```ruby gem "react_on_rails", "16.1.1" gem "shakapacker", "8.2.0" # Required for compatibilitypackage.json:
"shakapacker": "8.2.0"Step 2: Bundle and Yarn Install
bundle update react_on_rails shakapacker yarn installStep 3: Run the Install Generator
Run the generator to get the latest improvements:
rails generate react_on_rails:installNote: The generator will prompt to overwrite several files. Review each change carefully, especially if you have customizations.
### 2. Generator Improvements Documentation Document the new features added by the v16.1.1 generator: ```markdown ## New Development Features in v16.1.1 ### Enhanced bin/dev Script The updated `bin/dev` script provides better development server management with support for multiple modes: - `bin/dev` - Default HMR mode with webpack-dev-server - `bin/dev static` - Watch mode without HMR - `bin/dev prod` - Development with production-optimized assets ### Multiple Procfile Support Three Procfile configurations for different development scenarios: 1. **Procfile.dev** (HMR mode): - Rails server - Webpack dev server for client - Webpack watch for server bundle 2. **Procfile.dev-static-assets** (Static watch mode): - Rails server - Webpack watch mode 3. **Procfile.dev-prod-assets** (Production assets in development): - Rails server with production-optimized assets - Optional: Sidekiq, Redis, Mailcatcher configurations ### Webpack Configuration Updates - New `generateWebpackConfigs.js` helper for better configuration management - Updated configurations for better v16.1.1 compatibility - Improved babel.config.js setup 3. Version Compatibility Matrix
Add or update the compatibility matrix:
| react_on_rails | shakapacker (gem) | shakapacker (npm) | Rails | Ruby | |----------------|-------------------|-------------------|-------|-------| | 16.1.1 | 8.2.0 | 8.2.0 | 7.0+ | 3.0+ | | 16.0.x | 8.0.0 | 8.0.0 | 7.0+ | 3.0+ |4. Breaking Changes / Important Notes
## Important Notes for v16.1.1 ### Shakapacker Version Sync **Critical:** The shakapacker gem and npm package versions MUST match exactly. The generator will fail if versions differ: - Gem version in Gemfile.lock - NPM version in package.json ### Bug Fixes in 16.1.1 - Fixed server-side rendering manifest resolution issue - Improved `bundle_js_file_path` configuration flexibility for react-server-client-manifest.json5. Troubleshooting Section
## Common Upgrade Issues ### Generator Prerequisites Error If you see "ERROR: You have uncommitted changes", commit or stash your changes before running the generator. ### Shakapacker Version Mismatch Error: "Shakapacker gem and node package versions do not match" Solution: Ensure both gem and npm package are the same version (8.2.0 for v16.1.1) ### Test Failures After Upgrade - Rebuild ReScript files if using ReScript: `yarn res:build` - Clear webpack cache: `rm -rf public/packs*` - Precompile assets: `rails assets:precompile`Related Information
- PR demonstrating the upgrade: Update react_on_rails to v16.1.1 react-webpack-rails-tutorial#654
- Bug fix details: Fixed in PR Fix bug at resolving react-server-client-manifest.json file #1818
Benefits to Users
- Clear upgrade path from 16.0.x to 16.1.1
- Understanding of new development features
- Troubleshooting guidance for common issues
- Version compatibility clarity
This documentation would help users take full advantage of the improvements in v16.1.1 while avoiding common pitfalls during the upgrade process.
🤖 Generated with Claude Code