Add upgrade guide for v16.0.x to v16.1.1

docs/upgrading/release-notes/16.1.0.md

@@ -0,0 +1,245 @@
+# React on Rails 16.1.x Release Notes
+
+## Upgrading from 16.0.x to 16.1.x
+
+This guide covers upgrading from React on Rails v16.0.x to v16.1.1.
+
+### Step 1: Update Dependencies
+
+**Gemfile:**
+
+```ruby
+gem "react_on_rails", "~> 16.1.1"
+gem "shakapacker", "~> 8.2.0"  # Recommended for compatibility
+```
+
+**package.json:**
+
+```json
+{
+  "dependencies": {
+    "react-on-rails": "16.1.1",
+    "shakapacker": "8.2.0"
+  }
+}
+```
+
+**Important:** The shakapacker gem and npm package versions MUST match exactly.
+
+### Step 2: Install Updates
+
+```bash
+bundle update react_on_rails shakapacker
+yarn install  # or npm install
+```
+
+### Step 3: Run the Generator (Optional)
+
+Run the generator to get the latest improvements:
+
+```bash
+rails generate react_on_rails:install
+```
+
+**Note:** The generator will prompt to overwrite files. Review each change carefully, especially if you have customizations. Key files that may be updated:
+
+- `bin/dev` - Enhanced development workflow
+- Webpack configurations
+- `shakapacker.yml` settings
+- TypeScript configuration
+
+### Step 4: Use the New Doctor Command
+
+v16.1.0 introduces a diagnostic rake task to validate your setup:
+
+```bash
+rake react_on_rails:doctor
+```
+
+For detailed output:
+
+```bash
+VERBOSE=true rake react_on_rails:doctor
+```
+
+The doctor command checks:
+
+- Environment prerequisites
+- Dependencies and version compatibility
+- Rails integration
+- Webpack configuration
+- Shakapacker setup
+
+### Step 5: Test Your Application
+
+```bash
+# Test asset compilation
+bundle exec rails assets:precompile
+
+# Test development server
+bin/dev
+
+# Run your test suite
+bundle exec rspec  # or your test command
+```
+
+## New Features in v16.1.0
+
+### 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")
+  # Set to nil to load from public directory (legacy behavior)
+  config.server_bundle_output_path = "ssr-generated"
+
+  # When enabled, server bundles only load from private directories
+  # (default: false for backward compatibility)
+  config.enforce_private_server_bundles = true
+end
+```
+
+**Bundle Path Resolution Logic:**
+
+1. If `server_bundle_output_path` is set, server bundles load from that directory
+2. If not set, falls back to client bundle directory (public output path)
+3. When `enforce_private_server_bundles` is enabled:
+   - Server bundles only load from the private directory
+   - No fallback to public directory (improved security)
+
+### Doctor Rake Task
+
+New diagnostic command for troubleshooting:
+
+```bash
+rake react_on_rails:doctor
+```
+
+Provides comprehensive checks for:
+
+- Environment prerequisites
+- Dependency versions
+- Rails integration
+- Webpack configuration
+- Common setup issues
+
+### Generator Improvements
+
+- **Modern TypeScript patterns**: Better type inference instead of explicit annotations
+- **Optimized tsconfig.json**: Uses `"moduleResolution": "bundler"` for bundler compatibility
+- **Enhanced Redux TypeScript**: Improved type safety with modern React patterns (useMemo, type-only imports)
+- **Smart bin/dev defaults**: Auto-navigates to `/hello_world` route for immediate component visibility
+- **Cleaner generated code**: Follows modern React and TypeScript best practices
+
+## Deprecations
+
+### `generated_assets_dirs` Configuration
+
+The `config.generated_assets_dirs` option is deprecated. Remove it from `config/initializers/react_on_rails.rb`.
+
+**Why:** Since Shakapacker is now required, asset paths are automatically determined from `shakapacker.yml`.
+
+**Migration:** Use `public_output_path` in `config/shakapacker.yml` to customize asset output location.
+
+### `generated_assets_full_path` Method
+
+Use `public_bundles_full_path` instead for clarity about webpack bundles in public directories.
+
+## Bug Fixes in v16.1.1
+
+- **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)
+
+## Bug Fixes in v16.1.0
+
+- **Doctor rake task**: Fixed LoadError when using packaged gem
+- **Packs generator**: Fixed error when `server_bundle_js_file` is empty
+- **Non-Packer compatibility**: Fixed NoMethodError in environments without Shakapacker
+- **Shakapacker version requirements**: Fixed inconsistent version requirements between basic pack generation (6.5.1+) and advanced auto-bundling (7.0.0+)
+
+## Security Enhancements
+
+- **Private Server Bundle Enforcement**: Server bundles bypass public directory fallbacks when `enforce_private_server_bundles` is enabled
+- **Path Validation**: Validates `server_bundle_output_path` points to private directories when enforcement is enabled
+- **Command injection fixes**: Replaced unsafe string interpolation with secure array-based system calls
+- **Input validation**: Enhanced package manager validation and argument sanitization
+- **Hardened DOM selectors**: Using `CSS.escape()` and proper JavaScript escaping for XSS protection
+
+## Version Compatibility
+
+| react_on_rails | shakapacker (gem) | shakapacker (npm) | Rails | Ruby |
+| -------------- | ----------------- | ----------------- | ----- | ---- |
+| 16.1.x         | 8.2.0+            | 8.2.0+            | 6.0+  | 3.2+ |
+| 16.0.x         | 6.0.0+            | 6.0.0+            | 6.0+  | 3.2+ |
+
+**Recommended versions:**
+
+- Shakapacker 8.2.0 (gem and npm versions must match)
+- React 18+
+- Node.js 20+
+- Ruby 3.2+
+
+## Common Upgrade Issues
+
+### Generator Prerequisites Error
+
+```
+ERROR: You have uncommitted changes
+```
+
+**Solution:** Commit or stash your changes before running the generator.
+
+### Shakapacker Version Mismatch
+
+```
+Shakapacker gem and node package versions do not match
+```
+
+**Solution:** Ensure both gem and npm package are the same version:
+
+```bash
+# Check versions
+bundle show shakapacker
+yarn list shakapacker  # or npm ls shakapacker
+
+# Update to match
+bundle update shakapacker
+yarn upgrade [email protected]
+```
+
+### Test Failures After Upgrade
+
+1. **Rebuild ReScript files** (if using ReScript):
+
+   ```bash
+   yarn res:build
+   ```
+
+2. **Clear webpack cache**:
+
+   ```bash
+   rm -rf node_modules/.cache
+   rm -rf public/packs*
+   ```
+
+3. **Precompile assets**:
+   ```bash
+   rails assets:precompile
+   ```
+
+### Server Bundle Not Found
+
+If you're using server-side rendering and the server bundle isn't found:
+
+1. Check `config.server_bundle_output_path` is correctly set
+2. Run `rake react_on_rails:doctor` to diagnose issues
+3. Verify webpack builds both client and server bundles
+
+## Related Resources
+
+- [Changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md)
+- [Configuration Reference](../../api-reference/configuration.md)
+- [Troubleshooting Guide](../../deployment/troubleshooting.md)
+- [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

@@ -21,7 +21,57 @@ rails generate react_on_rails:install
 - `shakapacker.yml` settings
 - other configuration files
 
-## Upgrading to v16
+## Upgrading to v16.1.x (from v16.0.x)
+
+For detailed upgrade instructions, see the [v16.1.x Release Notes](release-notes/16.1.0.md).
+
+### Quick Summary
+
+v16.1.x is a minor release with new features and bug fixes:
+
+- **New `rake react_on_rails:doctor` command** for diagnosing setup issues
+- **Server bundle security enhancements** with `server_bundle_output_path` and `enforce_private_server_bundles` options
+- **Generator improvements** with modern TypeScript patterns and better defaults
+- **Bug fix (v16.1.1)**: Fixed RSC manifest file path resolution
+
+### Upgrade Steps
+
+1. Update dependencies:
+
+   ```ruby
+   # Gemfile
+   gem "react_on_rails", "~> 16.1.1"
+   gem "shakapacker", "~> 8.2.0"
+   ```
+
+   ```json
+   // package.json - versions must match exactly
+   {
+     "dependencies": {
+       "react-on-rails": "16.1.1",
+       "shakapacker": "8.2.0"
+     }
+   }
+   ```
+
+2. Install and verify:
+
+   ```bash
+   bundle update react_on_rails shakapacker
+   yarn install
+   rake react_on_rails:doctor  # New diagnostic command
+   ```
+
+3. Optionally run generator for latest improvements:
+   ```bash
+   rails generate react_on_rails:install
+   ```
+
+### Deprecation Notice
+
+Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`.
+
+## Upgrading to v16 (from v14/v15)
 
 ### Breaking Changes