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..c8d141f17c --- /dev/null +++ b/docs/upgrading/release-notes/16.1.0.md @@ -0,0 +1,159 @@ +# 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. + +## Version Compatibility + +| Component | Minimum | Recommended | +| ----------- | ------- | ----------- | +| Ruby | 3.0 | 3.3+ | +| Node.js | 18 | 22+ | +| Shakapacker | 6.0 | 8.2.0+ | +| React | 18 | 18+ | +| Rails | 5.2 | 7.0+ | + +**Note:** CI tests against Ruby 3.2+ and Node.js 20+, but the gem supports lower versions as shown above. + +## 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 +``` + +### 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 + +### Webpack Configuration Updates + +- New `generateWebpackConfigs.js` helper for better configuration management +- Improved babel.config.js setup + +### Generator Improvements + +**Note:** These improvements only affect newly generated code from `rails g react_on_rails:install` or component generators. Existing applications are unaffected. + +- Modern TypeScript patterns with better type inference +- Optimized tsconfig.json with `"moduleResolution": "bundler"` +- Enhanced Redux TypeScript integration +- Smart `bin/dev` defaults that auto-navigate to `/hello_world` route + +## Security Enhancements + +v16.1.0 includes important security improvements: + +- **Command injection protection**: Fixed command injection vulnerabilities in generator package installation commands by replacing unsafe string interpolation with secure array-based system calls ([PR 1786](https://github.com/shakacode/react_on_rails/pull/1786)) by [justin808](https://github.com/justin808) +- **Improved input validation**: Enhanced package manager validation and argument sanitization across all generators ([PR 1786](https://github.com/shakacode/react_on_rails/pull/1786)) by [justin808](https://github.com/justin808) +- **Hardened DOM selectors**: Using `CSS.escape()` and proper JavaScript escaping for XSS protection ([PR 1791](https://github.com/shakacode/react_on_rails/pull/1791)) by [AbanoubGhadban](https://github.com/AbanoubGhadban) + +## Bug Fixes + +### v16.1.1 + +- Fixed RSC manifest file path resolution ([PR 1818](https://github.com/shakacode/react_on_rails/pull/1818)) by [AbanoubGhadban](https://github.com/AbanoubGhadban) + +### v16.1.0 + +- Fixed LoadError in `rake react_on_rails:doctor` when using packaged gem ([PR 1795](https://github.com/shakacode/react_on_rails/pull/1795)) by [justin808](https://github.com/justin808) +- Fixed packs generator error when `server_bundle_js_file` is empty ([PR 1802](https://github.com/shakacode/react_on_rails/pull/1802)) by [justin808](https://github.com/justin808) +- Fixed NoMethodError in environments without Shakapacker ([PR 1806](https://github.com/shakacode/react_on_rails/pull/1806)) by [justin808](https://github.com/justin808) +- Fixed inconsistent Shakapacker version requirements ([PR 1806](https://github.com/shakacode/react_on_rails/pull/1806)) by [justin808](https://github.com/justin808) + +## Deprecations + +Remove `config.generated_assets_dirs` from your configuration - asset paths are now automatically determined from `shakapacker.yml`. + +## Common Upgrade Issues + +### Shakapacker Version Mismatch + +**Symptom:** Assets fail to compile or inconsistent behavior between development and production. + +**Solution:** Ensure your Shakapacker gem and npm package versions match exactly: + +```bash +# Check gem version +bundle show shakapacker + +# Check npm version +npm list shakapacker +# or +yarn list shakapacker +``` + +Both should show the same version (e.g., 8.2.0). + +### Missing Server Bundle After Upgrade + +**Symptom:** Server-side rendering fails with "bundle not found" errors. + +**Solution:** If you're using `server_bundle_output_path`, ensure the directory exists and your build process outputs to that location. Run `rake react_on_rails:doctor` to diagnose configuration issues. + +## Pro License Features + +v16.1.0 introduced foundational changes for React on Rails Pro, including: + +- Core/Pro separation with clear licensing boundaries +- Runtime license validation with graceful fallback +- Enhanced immediate hydration (Pro-only feature) + +These changes are internal and do not affect open-source users. For information about Pro features like streaming SSR, React Server Components, and enhanced performance optimizations, see [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/). + +## Related Resources + +- [Changelog](https://github.com/shakacode/react_on_rails/blob/master/CHANGELOG.md) +- [Configuration Reference](../../api-reference/configuration.md) diff --git a/docs/upgrading/upgrading-react-on-rails.md b/docs/upgrading/upgrading-react-on-rails.md index 537156264f..5d76f39f09 100644 --- a/docs/upgrading/upgrading-react-on-rails.md +++ b/docs/upgrading/upgrading-react-on-rails.md @@ -21,7 +21,13 @@ rails generate react_on_rails:install - `shakapacker.yml` settings - other configuration files -## Upgrading to v16 +## Upgrading to v16.1.x (from v16.0.x) + +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. + +**Deprecation:** Remove `config.generated_assets_dirs` from your configuration if present. Asset paths are now automatically determined from `public_output_path` in `config/shakapacker.yml`. + +## Upgrading to v16 (from v14/v15) ### Breaking Changes