From d9a6e913678bfd74f36d7e996549d52062a759eb Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Tue, 25 Nov 2025 21:09:24 -1000 Subject: [PATCH 1/2] Add upgrade guide for v16.0.x to v16.1.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/upgrading/release-notes/16.1.0.md | 245 +++++++++++++++++++++ docs/upgrading/upgrading-react-on-rails.md | 52 ++++- 2 files changed, 296 insertions(+), 1 deletion(-) create mode 100644 docs/upgrading/release-notes/16.1.0.md diff --git a/docs/upgrading/release-notes/16.1.0.md b/docs/upgrading/release-notes/16.1.0.md new file mode 100644 index 0000000000..9fb9e0abaf --- /dev/null +++ b/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 shakapacker@8.2.0 +``` + +### 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) diff --git a/docs/upgrading/upgrading-react-on-rails.md b/docs/upgrading/upgrading-react-on-rails.md index 537156264f..af0b5235ce 100644 --- a/docs/upgrading/upgrading-react-on-rails.md +++ b/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 From 6409951dabc10ce7a01541ecb07c300be24a6c09 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Thu, 4 Dec 2025 18:33:51 -1000 Subject: [PATCH 2/2] Simplify v16.1.x upgrade documentation - Use exact versions in examples (not ~>) - Remove package manager-specific commands (support all) - Reduce verbosity for minor/patch release upgrade - Focus on essential information --- docs/upgrading/release-notes/16.1.0.md | 215 +++------------------ docs/upgrading/upgrading-react-on-rails.md | 48 +---- 2 files changed, 27 insertions(+), 236 deletions(-) diff --git a/docs/upgrading/release-notes/16.1.0.md b/docs/upgrading/release-notes/16.1.0.md index 9fb9e0abaf..3a6166dd30 100644 --- a/docs/upgrading/release-notes/16.1.0.md +++ b/docs/upgrading/release-notes/16.1.0.md @@ -2,20 +2,16 @@ ## 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:** +Update your gem and npm package versions: ```ruby -gem "react_on_rails", "~> 16.1.1" -gem "shakapacker", "~> 8.2.0" # Recommended for compatibility +# Gemfile +gem "react_on_rails", "16.1.1" +gem "shakapacker", "8.2.0" ``` -**package.json:** - ```json +// package.json { "dependencies": { "react-on-rails": "16.1.1", @@ -24,67 +20,21 @@ gem "shakapacker", "~> 8.2.0" # Recommended for compatibility } ``` -**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) +Then run `bundle install` and your package manager's install command. -Run the generator to get the latest improvements: +**Important:** The shakapacker gem and npm package versions must match exactly. -```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 +## New Features in v16.1.0 -### Step 4: Use the New Doctor Command +### Doctor Rake Task -v16.1.0 introduces a diagnostic rake task to validate your setup: +New diagnostic command for troubleshooting setup issues: ```bash rake react_on_rails:doctor +VERBOSE=true rake react_on_rails:doctor # For detailed output ``` -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: @@ -93,153 +43,38 @@ New configuration options for enhanced server bundle security: # 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 +- Modern TypeScript patterns with better type inference +- Optimized tsconfig.json with `"moduleResolution": "bundler"` +- Enhanced Redux TypeScript integration +- Smart `bin/dev` defaults -- **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 -## Bug Fixes in v16.1.0 +### v16.1.1 -- **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+) +- Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)) -## Security Enhancements +### v16.1.0 -- **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 -``` +- 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 -**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 shakapacker@8.2.0 -``` - -### 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: +## Deprecations -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 +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) -- [Troubleshooting Guide](../../deployment/troubleshooting.md) -- [Example upgrade PR: react-webpack-rails-tutorial#654](https://github.com/shakacode/react-webpack-rails-tutorial/pull/654) diff --git a/docs/upgrading/upgrading-react-on-rails.md b/docs/upgrading/upgrading-react-on-rails.md index af0b5235ce..eb250e38ca 100644 --- a/docs/upgrading/upgrading-react-on-rails.md +++ b/docs/upgrading/upgrading-react-on-rails.md @@ -23,53 +23,9 @@ rails generate react_on_rails:install ## 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). +This is a minor release - update your gem and npm package versions, then run `bundle install` and your package manager's install command. See the [v16.1.x Release Notes](release-notes/16.1.0.md) for new features and bug fixes. -### 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`. +**Deprecation:** Remove `config.generated_assets_dirs` from your configuration if present. ## Upgrading to v16 (from v14/v15)