react_on_rails 15.0.0.rc.2 → 16.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50ca168413057bb25fbd6ca60307bb48baceabcef86cbbd4a8141bb5913e9ca5
-  data.tar.gz: 6cf924cd26ae04b10d303e0c761daf19af7bd3d15417421e56c6492b6e4264ee
+  metadata.gz: ae77f76930b3765219ace75c93ac15ba789730f9d7fd98690db212e74489936d
+  data.tar.gz: a81127c42c27640473994129251b9f18ea7c609837c0b414eaa83a4edc30442d
 SHA512:
-  metadata.gz: 3485bf92e659aa921d0352ee43e3cd56b836818c17a6d643332a5e5fecaac0da696e2ab1723215d069d25201cf1da41bfadea2546bf435bfea01924ba4010096
-  data.tar.gz: a7e120190894dd8b34637274a6fb8407c8ab6b7a7e6608b744244868d661ba8e11e3d1925a7eaa86d27905cc2db2c870453f6a7af8c795c504d1dd988f0d7130
+  metadata.gz: a0d4a4ece7bf8bd4a90dd7f3e11249f0d8de7d1dd1425a9f4654caeef3758722aaad5d2b6654e50f5526d32f6cddb65847ff3e0e865203017c331d283a01f12f
+  data.tar.gz: 6ec4ef830ab5712e467de1a98d54ccfb6d174079f78d2f9aeb5e84f26eb71038200ad2b0b4f3c4ef03a8ded5b1def16869482afffbaf5c17bd861df10364d3f9

data/CHANGELOG.md

@@ -23,63 +23,92 @@ After a release, please make sure to run `bundle exec rake update_changelog`. Th
 
 Changes since the last non-beta release.
 
+### [16.0.0] - 2025-01-XX
+
+#### Removed (Breaking Changes)
+
+- **Webpacker support completely removed**. Shakapacker >= 6.0 is now required.
+  - Migration:
+    - Remove any `webpacker` gem references from your Gemfile
+    - Ensure `shakapacker` gem version 6.0 or higher is installed (8.0+ recommended)
+    - Replace any `bin/webpacker` commands with `bin/shakapacker`
+    - Update any webpacker configuration files to shakapacker equivalents
+  - Removed files: `rakelib/webpacker_examples.rake`, `lib/generators/react_on_rails/adapt_for_older_shakapacker_generator.rb`
+  - All webpacker compatibility code and tests have been removed
+- **CI/Development runtime requirements updated**:
+  - _Note, this is just what CI tests_. You can use older versions of Ruby and Node.js, but you may run into issues.\*
+  - Minimum Ruby version: 3.2 (was 3.0)
+  - Maximum Ruby version: 3.4 (was 3.3)
+  - Minimum Node.js version: 20 (was 16)
+  - Maximum Node.js version: 22 (was 20)
+  - Migration: Upgrade your Ruby and Node.js versions to supported ranges
+- **Install generator now validates prerequisites**:
+  - Generator now requires at least one JavaScript package manager (npm, pnpm, yarn, or bun)
+  - Generator uses `Thor::Error` exceptions instead of `exit(1)` for better error handling
+  - Migration: Ensure you have a JavaScript package manager installed before running the generator
+
+#### Enhanced
+
+- Simplified CI matrix configuration with clear dependency level naming (`minimum`/`latest` instead of `oldest`/`newest`)
+- Improved error messages in install generator with clearer troubleshooting steps
+- Enhanced package manager detection with multi-strategy validation
+
+### [15.0.0] - 2025-08-28
+
+See [Release Notes](docs/release-notes/16.0.0.md) for full details.
+
+### Removed (Breaking Changes)
+
+- Deprecated `defer_generated_component_packs` configuration option. You should use `generated_component_packs_loading_strategy` instead.
+  - Migration:
+    - `defer_generated_component_packs: true` → `generated_component_packs_loading_strategy: :defer`
+    - `defer_generated_component_packs: false` → `generated_component_packs_loading_strategy: :sync`
+    - For best performance, use `generated_component_packs_loading_strategy: :async`
+  - [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- The package is ESM-only now. Migration:
+  - If using `require('react-on-rails')`, upgrade to Node v20.19.0+ or change to `import`.
+  - For TypeScript errors, upgrade to TypeScript 5.8+ and set `module` to `nodenext`.
+- `ReactOnRails.reactOnRailsPageLoaded` is now an async function. Migration:
+  - Add `await` when calling this function: `await ReactOnRails.reactOnRailsPageLoaded()`.
+- **RENAMED**: `force_load` configuration renamed to `immediate_hydration` for better API clarity.
+  - `immediate_hydration` now defaults to `false` and requires React on Rails Pro license.
+  - Migration:
+    - `config.force_load = true` → `config.immediate_hydration = true`
+    - `react_component(force_load: true)` → `react_component(immediate_hydration: true)`
+    - `redux_store(force_load: true)` → `redux_store(immediate_hydration: true)`
+
+For detailed migration instructions, see the [16.0.0 Release Notes](docs/release-notes/16.0.0.md).
+
 #### Fixed
 
 - Enable support for ReactRefreshWebpackPlugin v0.6.0 by adding conditional logic regarding configuration. [PR 1748](https://github.com/shakacode/react_on_rails/pull/1748) by [judahmeek](https://github.com/judahmeek).
-
 - Replace RenderOptions.renderRequestId and use local trackers instead. This change should only be relevant to ReactOnRails Pro users. [PR 1745](https://github.com/shakacode/react_on_rails/pull/1745) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-
 - Fixed invalid warnings about non-exact versions when using a pre-release version of React on Rails, as well as missing warnings when using different pre-release versions of the gem and the Node package. [PR 1742](https://github.com/shakacode/react_on_rails/pull/1742) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
 
-### [15.0.0-rc.1] - 2025-06-18
-
 #### Improved
 
 - Ensured that the RSC payload is injected after the component's HTML markup to improve the performance of the RSC payload injection. [PR 1738](https://github.com/shakacode/react_on_rails/pull/1738) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-
-### [15.0.0-rc.0] - 2025-06-16
-
-#### Improved
-
 - Improved RSC rendering flow by eliminating double rendering of server components and reducing the number of HTTP requests.
 - Updated communication protocol between Node Renderer and Rails to version 2.0.0 which supports the ability to upload multiple bundles at once.
-- Added `RSCRoute` component to enable seamless server-side rendering of React Server Components. This component automatically handles RSC payload injection and hydration, allowing server components to be rendered directly within client components while maintaining optimal performance.
-
-[PR 1696](https://github.com/shakacode/react_on_rails/pull/1696) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-
-#### Added
-
-- Configuration option `generated_component_packs_loading_strategy` to control how generated component packs are loaded. It supports `sync`, `async`, and `defer` strategies. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-
-- Support for returning React component from async render-function. [PR 1720](https://github.com/shakacode/react_on_rails/pull/1720) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-
-### Removed (Breaking Changes)
-
-- Deprecated `defer_generated_component_packs` configuration option. You should use `generated_component_packs_loading_strategy` instead. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
-
-### Changed
-
-- **Breaking change**: The package is ESM-only now. Please see [Release Notes](docs/release-notes/15.0.0.md#esm-only-package) for more details.
+- Added `RSCRoute` component to enable seamless server-side rendering of React Server Components. This component automatically handles RSC payload injection and hydration, allowing server components to be rendered directly within client components while maintaining optimal performance. [PR 1696](https://github.com/shakacode/react_on_rails/pull/1696) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - The global context is now accessed using `globalThis`. [PR 1727](https://github.com/shakacode/react_on_rails/pull/1727) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
 - Generated client packs now import from `react-on-rails/client` instead of `react-on-rails`. [PR 1706](https://github.com/shakacode/react_on_rails/pull/1706) by [alexeyr-ci](https://github.com/alexeyr-ci).
   - The "optimization opportunity" message when importing the server-side `react-on-rails` instead of `react-on-rails/client` in browsers is now a warning for two reasons:
     - Make it more prominent
     - Include a stack trace when clicked
 
-### [15.0.0-alpha.2] - 2025-03-07
-
-See [Release Notes](docs/release-notes/15.0.0.md) for full details.
-
 #### Added
 
+- Configuration option `generated_component_packs_loading_strategy` to control how generated component packs are loaded. It supports `sync`, `async`, and `defer` strategies. [PR 1712](https://github.com/shakacode/react_on_rails/pull/1712) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
+- Support for returning React component from async render-function. [PR 1720](https://github.com/shakacode/react_on_rails/pull/1720) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - React Server Components Support (Pro Feature) [PR 1644](https://github.com/shakacode/react_on_rails/pull/1644) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 - Improved component and store hydration performance [PR 1656](https://github.com/shakacode/react_on_rails/pull/1656) by [AbanoubGhadban](https://github.com/AbanoubGhadban).
 
-#### Breaking Changes
+### [15.0.0] - 2025-08-28 - RETRACTED
+
+**⚠️ This version has been retracted due to API design issues. Please upgrade directly to v16.0.0.**
 
-- `ReactOnRails.reactOnRailsPageLoaded` is now an async function
-- `force_load` configuration now defaults to `true`
-- `defer_generated_component_packs` configuration now defaults to `false`
+The `force_load` feature was incorrectly available without a Pro license and has been renamed to `immediate_hydration` for better clarity. All features from v15 are available in v16 with the corrected API.
 
 ### [14.2.0] - 2025-03-03
 
@@ -1577,8 +1606,8 @@ such as:
 
 - Fix several generator-related issues.
 
-[Unreleased]: https://github.com/shakacode/react_on_rails/compare/15.0.0-alpha.2...master
-[15.0.0-alpha.2]: https://github.com/shakacode/react_on_rails/compare/14.2.0...15.0.0-alpha.2
+[Unreleased]: https://github.com/shakacode/react_on_rails/compare/15.0.0...master
+[15.0.0]: https://github.com/shakacode/react_on_rails/compare/14.2.0...15.0.0
 [14.2.0]: https://github.com/shakacode/react_on_rails/compare/14.1.1...14.2.0
 [14.1.1]: https://github.com/shakacode/react_on_rails/compare/14.1.0...14.1.1
 [14.1.0]: https://github.com/shakacode/react_on_rails/compare/14.0.5...14.1.0

data/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Essential Commands
+
+- **Install dependencies**: `bundle && yarn`
+- **Run tests**:
+  - Ruby tests: `rake run_rspec`
+  - JavaScript tests: `yarn run test` or `rake js_tests`
+  - All tests: `rake` (default task runs lint and all tests except examples)
+- **Linting**:
+  - All linters: `rake lint` (runs ESLint and RuboCop)
+  - ESLint only: `yarn run lint` or `rake lint:eslint`
+  - RuboCop only: `rake lint:rubocop`
+- **Code Formatting**:
+  - Format code with Prettier: `yarn start format`
+  - Check formatting without fixing: `yarn start format.listDifferent`
+- **Build**: `yarn run build` (compiles TypeScript to JavaScript in node_package/lib)
+- **Type checking**: `yarn run type-check`
+
+### Development Setup Commands
+
+- **Initial setup**: `bundle && yarn && rake shakapacker_examples:gen_all && rake node_package && rake`
+- **Prepare examples**: `rake shakapacker_examples:gen_all`
+- **Generate node package**: `rake node_package`
+- **Run single test example**: `rake run_rspec:example_basic`
+
+### Test Environment Commands
+
+- **Dummy app tests**: `rake run_rspec:dummy`
+- **Gem-only tests**: `rake run_rspec:gem`
+- **All tests except examples**: `rake all_but_examples`
+
+## Project Architecture
+
+### Dual Package Structure
+
+This project maintains both a Ruby gem and an NPM package:
+
+- **Ruby gem**: Located in `lib/`, provides Rails integration and server-side rendering
+- **NPM package**: Located in `node_package/src/`, provides client-side React integration
+
+### Core Components
+
+#### Ruby Side (`lib/react_on_rails/`)
+
+- **`helper.rb`**: Rails view helpers for rendering React components
+- **`server_rendering_pool.rb`**: Manages Node.js processes for server-side rendering
+- **`configuration.rb`**: Global configuration management
+- **`engine.rb`**: Rails engine integration
+- **Generators**: Located in `lib/generators/react_on_rails/`
+
+#### JavaScript/TypeScript Side (`node_package/src/`)
+
+- **`ReactOnRails.ts`**: Main entry point for client-side functionality
+- **`serverRenderReactComponent.ts`**: Server-side rendering logic
+- **`ComponentRegistry.ts`**: Manages React component registration
+- **`StoreRegistry.ts`**: Manages Redux store registration
+
+### Build System
+
+- **Ruby**: Standard gemspec-based build
+- **JavaScript**: TypeScript compilation to `node_package/lib/`
+- **Testing**: Jest for JS, RSpec for Ruby
+- **Linting**: ESLint for JS/TS, RuboCop for Ruby
+
+### Examples and Testing
+
+- **Dummy app**: `spec/dummy/` - Rails app for testing integration
+- **Examples**: Generated via rake tasks for different webpack configurations
+- **Rake tasks**: Defined in `rakelib/` for various development operations
+
+## Important Notes
+
+- Use `yalc` for local development when testing with external apps
+- The project supports both Webpacker and Shakapacker
+- Server-side rendering uses isolated Node.js processes
+- React Server Components support available in Pro version
+- Generated examples are in `gen-examples/` (ignored by git)
+
+## IDE Configuration
+
+Exclude these directories to prevent IDE slowdowns:
+
+- `/coverage`, `/tmp`, `/gen-examples`, `/node_package/lib`
+- `/node_modules`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
+- `/spec/dummy/app/assets/webpack`, `/spec/dummy/log`

data/CODING_AGENTS.md

@@ -0,0 +1,312 @@
+# 🤖 Coding Agents & AI Contributors Guide
+
+This guide provides specific guidelines for AI coding agents (like Claude Code) contributing to React on Rails. It supplements the main [CONTRIBUTING.md](./CONTRIBUTING.md) with AI-specific workflows and patterns.
+
+## Quick Reference Commands
+
+### Essential Commands
+
+```bash
+# Install dependencies
+bundle && yarn
+
+# Run tests
+bundle exec rspec                    # All tests (from project root)
+cd spec/dummy && bundle exec rspec   # Dummy app tests only
+
+# Linting & Formatting
+bundle exec rubocop                  # Ruby linting
+bundle exec rubocop [file_path]     # Lint specific file
+# Note: yarn format requires local setup, format manually
+
+# Development
+cd spec/dummy && foreman start       # Start dummy app with webpack
+```
+
+### CI Compliance Checklist
+
+- [ ] `bundle exec rubocop` passes with no offenses
+- [ ] All RSpec tests pass
+- [ ] No trailing whitespace
+- [ ] Line length ≤120 characters
+- [ ] Security violations properly scoped with disable comments
+
+## Development Patterns for AI Contributors
+
+### 1. Task Management
+
+Always use TodoWrite tool for multi-step tasks to:
+
+- Track progress transparently
+- Show the user what's being worked on
+- Ensure no steps are forgotten
+- Mark tasks complete as you finish them
+
+```markdown
+Example workflow:
+
+1. Analyze the problem
+2. Create test cases
+3. Implement the fix
+4. Run tests
+5. Fix linting issues
+6. Update documentation
+```
+
+### 2. Test-Driven Development
+
+When fixing bugs or adding features:
+
+1. **Create failing tests first** that reproduce the issue
+2. **Implement the minimal fix** to make tests pass
+3. **Add comprehensive test coverage** for edge cases
+4. **Verify all existing tests still pass**
+
+### 3. File Processing Guidelines
+
+When working with file generation or processing:
+
+- **Filter by extension**: Only process relevant files (e.g., `.js/.jsx/.ts/.tsx` for React components)
+- **Validate assumptions**: Don't assume all files in a directory are components
+- **Handle edge cases**: CSS modules, config files, etc. should be excluded appropriately
+
+Example from CSS module fix:
+
+```ruby
+COMPONENT_EXTENSIONS = /\.(jsx?|tsx?)$/
+
+def filter_component_files(paths)
+  paths.grep(COMPONENT_EXTENSIONS)
+end
+```
+
+## RuboCop Compliance Patterns
+
+### Common Fixes
+
+1. **Trailing Whitespace**
+
+   ```ruby
+   # Bad
+   let(:value) { "test" }
+
+   # Good
+   let(:value) { "test" }
+   ```
+
+2. **Line Length (120 chars max)**
+
+   ```ruby
+   # Bad
+   expect { eval(pack_content.gsub(/import.*from.*['"];/, "").gsub(/ReactOnRails\.register.*/, "")) }.not_to raise_error
+
+   # Good
+   sanitized_content = pack_content.gsub(/import.*from.*['"];/, "")
+                                   .gsub(/ReactOnRails\.register.*/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   ```
+
+3. **Named Subjects (RSpec)**
+
+   ```ruby
+   # Bad
+   describe "#method_name" do
+     subject { instance.method_name(arg) }
+
+     it "does something" do
+       expect(subject).to eq "result"
+     end
+   end
+
+   # Good
+   describe "#method_name" do
+     subject(:method_result) { instance.method_name(arg) }
+
+     it "does something" do
+       expect(method_result).to eq "result"
+     end
+   end
+   ```
+
+4. **Security/Eval Violations**
+
+   ```ruby
+   # Bad
+   expect { eval(dangerous_code) }.not_to raise_error
+
+   # Good
+   # rubocop:disable Security/Eval
+   sanitized_content = dangerous_code.gsub(/harmful_pattern/, "")
+   expect { eval(sanitized_content) }.not_to raise_error
+   # rubocop:enable Security/Eval
+   ```
+
+### RuboCop Workflow
+
+1. Run `bundle exec rubocop [file]` to see violations
+2. Fix violations manually or with auto-correct where safe
+3. Re-run to verify fixes
+4. Use disable comments sparingly and with good reason
+
+## Testing Best Practices
+
+### Test Structure
+
+```ruby
+describe "FeatureName" do
+  context "when condition A" do
+    let(:setup) { create_test_condition }
+
+    before do
+      # Setup code
+    end
+
+    it "does expected behavior" do
+      # Arrange, Act, Assert
+    end
+  end
+end
+```
+
+### Test Fixtures
+
+- Create realistic test data that represents edge cases
+- Use descriptive names for fixtures and variables
+- Clean up after tests (handled by RSpec automatically in most cases)
+
+### CSS Module Testing Example
+
+```ruby
+# Create test fixtures
+Write.create("ComponentWithCSSModule.module.css", css_content)
+Write.create("ComponentWithCSSModule.jsx", jsx_content)
+
+# Test the behavior
+it "ignores CSS module files during pack generation" do
+  generated_packs = PacksGenerator.instance.generate_packs_if_stale
+  expect(generated_packs).not_to include("ComponentWithCSSModule.module.js")
+end
+```
+
+## Git & PR Workflow
+
+### Branch Management
+
+```bash
+git checkout -b fix/descriptive-name
+# Make changes
+git add .
+git commit -m "Descriptive commit message
+
+- Bullet points for major changes
+- Reference issue numbers
+- Include 🤖 Generated with Claude Code signature"
+
+git push -u origin fix/descriptive-name
+```
+
+### Commit Message Format
+
+```
+Brief description of the change
+
+- Detailed bullet points of what changed
+- Why the change was needed
+- Any breaking changes or considerations
+
+Fixes #issue_number
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### PR Creation
+
+Use `gh pr create` with:
+
+- Clear title referencing the issue
+- Comprehensive description with summary and test plan
+- Link to the issue being fixed
+- Include the Claude Code signature
+
+## Common Pitfalls & Solutions
+
+### 1. File Path Issues
+
+- Always use absolute paths in tools
+- Check current working directory with `pwd`
+- Use proper path joining methods
+
+### 2. Test Environment
+
+- Run tests from correct directory (often project root)
+- Understand the difference between gem tests vs dummy app tests
+- Clean up test artifacts appropriately
+
+### 3. Dependency Management
+
+- Don't assume packages are installed globally
+- Use `bundle exec` for Ruby commands
+- Verify setup with `bundle && yarn` when needed
+
+### 4. RuboCop Configuration
+
+- Different rules may apply to different directories
+- Use `bundle exec rubocop` (not global rubocop)
+- Check `.rubocop.yml` files for project-specific rules
+
+## Debugging Workflow
+
+1. **Understand the Problem**
+
+   - Read the issue carefully
+   - Reproduce the bug if possible
+   - Identify root cause
+
+2. **Create Minimal Test Case**
+
+   - Write failing test that demonstrates issue
+   - Keep it focused and minimal
+
+3. **Implement Fix**
+
+   - Make smallest change possible
+   - Ensure fix doesn't break existing functionality
+   - Follow existing code patterns
+
+4. **Verify Solution**
+   - All new tests pass
+   - All existing tests still pass
+   - RuboCop compliance maintained
+   - Manual testing if applicable
+
+## IDE Configuration for AI Context
+
+When analyzing codebases, ignore these directories to avoid confusion:
+
+- `/coverage`, `/tmp`, `/gen-examples`
+- `/node_package/lib`, `/node_modules`
+- `/spec/dummy/app/assets/webpack`
+- `/spec/dummy/log`, `/spec/dummy/node_modules`, `/spec/dummy/tmp`
+- `/spec/react_on_rails/dummy-for-generators`
+
+## Communication with Human Maintainers
+
+- Be transparent about AI-generated changes
+- Explain reasoning behind implementation choices
+- Ask for clarification when requirements are ambiguous
+- Provide comprehensive commit messages and PR descriptions
+- Include test plans and verification steps
+
+## Resources
+
+- [Main Contributing Guide](./CONTRIBUTING.md)
+- [Pull Request Guidelines](./docs/contributor-info/pull-requests.md)
+- [Generator Testing](./docs/contributor-info/generator-testing.md)
+- [RuboCop Documentation](https://docs.rubocop.org/)
+- [RSpec Best Practices](https://rspec.info/)
+
+---
+
+This guide evolves based on AI contributor experiences. Suggest improvements via issues or PRs!