react_on_rails 15.0.0.rc.2 → 16.0.1.rc.0

data/CONTRIBUTING.md

@@ -79,11 +79,11 @@ yalc add react-on-rails
 The workflow is:
 
 1. Make changes to the node package.
-2. We need yalc to push and then run yarn:
+2. **CRITICAL**: Run yalc push to send updates to all linked apps:
 
 ```
 cd <top dir>
-# Will send the updates to other folders
+# Will send the updates to other folders - MUST DO THIS AFTER ANY CHANGES
 yalc push
 cd spec/dummy
 
@@ -91,6 +91,8 @@ cd spec/dummy
 yarn
 ```
 
+**⚠️ Common Mistake**: Forgetting to run `yalc push` after making changes to React on Rails source code will result in test apps not receiving updates, making it appear that your changes have no effect.
+
 When you run `yalc push`, you'll get an informative message
 
 ```
@@ -180,6 +182,42 @@ cd react_on_rails/
 yarn run check
 ```
 
+## Development Commands
+
+### Code Formatting
+
+To format JavaScript/TypeScript files with Prettier:
+
+```sh
+yarn start format
+```
+
+To check formatting without fixing:
+
+```sh
+yarn start format.listDifferent
+```
+
+### Linting
+
+Run all linters (ESLint and RuboCop):
+
+```sh
+rake lint
+```
+
+Run only RuboCop:
+
+```sh
+rake lint:rubocop
+```
+
+Run only ESLint:
+
+```sh
+yarn run lint
+```
+
 ### Starting the Dummy App
 
 To run the dummy app, it's **CRITICAL** to not just run `rails s`. You have to run `foreman start` with one of the Procfiles. If you don't do this, then `webpack` will not generate a new bundle, and you will be seriously confused when you change JavaScript and the app does not change. If you change the Webpack configs, then you need to restart Foreman. If you change the JS code for react-on-rails, you need to run `yarn run build` in the project root.
@@ -210,7 +248,7 @@ gem 'react_on_rails', path: '../relative/path/to/react_on_rails'
 
 Then run `bundle`.
 
-The main installer can be run with `rails generate react_on_rails:install`
+The main installer can be run with `./bin/rails generate react_on_rails:install`
 
 Then use yalc to add the npm module.
 
@@ -232,6 +270,269 @@ The generators are covered by generator tests using Rails's generator testing he
 
 `rake run_rspec:shakapacker_examples_basic` is a great way to run tests on one generator. Once that works, you should run `rake run_rspec:shakapacker_examples`. Be aware that this will create a huge number of files under a `/gen-examples` directory. You should be sure to exclude this directory from your IDE and delete it once your testing is done.
 
+#### Manual Generator Testing Workflow
+
+For comprehensive testing of generator changes, use this manual testing workflow with dedicated test applications:
+
+**1. Set up test application with clean baseline:**
+
+```bash
+# Create a test Rails app
+mkdir -p {project_dir}/test-app
+cd {project_dir}/test-app
+rails new . --skip-javascript
+
+# Set up for testing the generator
+echo 'gem "react_on_rails", path: "../react_on_rails"' >> Gemfile
+yalc add react-on-rails
+
+# Create a clean baseline tag for testing
+git init && git add . && git commit -m "Initial commit"
+git tag generator_testing_base
+bundle install
+
+# Clean reset to baseline state
+git clean -fd && git reset --hard && git clean -fd
+```
+
+**2. Test generator commits systematically:**
+
+When testing specific generator improvements or fixes, test both Shakapacker scenarios:
+
+**Scenario A: No Shakapacker installed (fresh Rails app)**
+
+```bash
+# Reset to clean baseline before each test
+git clean -fd && git reset --hard generator_testing_base && git clean -fd
+
+# Ensure no Shakapacker in Gemfile (remove if present)
+# Edit Gemfile to update gem path: gem 'react_on_rails', path: '../path/to/main/repo'
+bundle install
+
+# Run generator - should install Shakapacker automatically
+./bin/rails generate react_on_rails:install
+
+# Verify Shakapacker was added to Gemfile and installed correctly
+```
+
+**Scenario B: Shakapacker already installed**
+
+```bash
+# Reset to clean baseline
+git clean -fd && git reset --hard generator_testing_base && git clean -fd
+
+# Add Shakapacker to Gemfile
+bundle add shakapacker --strict
+
+# Run Shakapacker installer first
+./bin/rails shakapacker:install
+
+# Edit Gemfile to update gem path: gem 'react_on_rails', path: '../path/to/main/repo'
+bundle install
+
+# Run generator - should detect existing Shakapacker
+./bin/rails generate react_on_rails:install
+
+# Verify generator adapts to existing Shakapacker setup
+```
+
+**3. Document testing results:**
+
+For each commit tested, document:
+
+- Generator execution success/failure for both scenarios
+- Shakapacker installation/detection behavior
+- Component rendering in browser
+- Console output and warnings
+- File generation differences between scenarios
+- Specific issues found
+
+This systematic approach ensures generator changes work correctly whether Shakapacker is pre-installed or needs to be installed by the generator.
+
+#### Testing Generator with Yalc for React Component Functionality
+
+When testing the install generator with new Rails apps, you need to use **yalc** for the JavaScript package to ensure React components work correctly. The Ruby gem path reference is insufficient for client-side rendering.
+
+**Problem**: Using only the gem path (`gem "react_on_rails", path: "../path"`) in a new Rails app results in React components not mounting on the client side, even though server-side rendering works fine.
+
+**Solution**: Use both gem path and yalc for complete testing:
+
+```ruby
+# In test app's Gemfile
+gem 'react_on_rails', path: '../relative/path/to/react_on_rails'
+```
+
+```bash
+# After running the install generator AND after making any changes to the React on Rails source code
+cd /path/to/react_on_rails
+npm run build
+npx yalc publish
+# CRITICAL: Push changes to all linked apps
+npx yalc push
+
+cd /path/to/test_app
+npm install
+
+# Restart development server
+bin/dev
+```
+
+**⚠️ CRITICAL DEBUGGING NOTE:**
+Always run `yalc push` after making changes to React on Rails source code. Without this step, your test app won't receive the updated package, leading to confusing behavior where changes appear to have no effect.
+
+**Alternative to Yalc: npm pack (More Reliable)**
+For a more reliable alternative that exactly mimics real package installation:
+
+```bash
+# In react_on_rails directory
+npm run build
+npm pack  # Creates react-on-rails-15.0.0.tgz
+
+# In test app directory
+npm install ../path/to/react_on_rails/react-on-rails-15.0.0.tgz
+```
+
+This approach:
+
+- ✅ Exactly mimics real package installation
+- ✅ No symlink issues across different filesystems
+- ✅ More reliable for CI/CD testing
+- ⚠️ Requires manual step after each change (can be scripted)
+
+**Why this is needed**:
+
+- The gem provides Rails integration and server-side rendering
+- Yalc provides the complete JavaScript client library needed for component mounting
+- Without yalc, you'll see empty divs where React components should render
+
+**Verification**:
+
+- Visit the hello_world page in browser
+- Check browser console for "RENDERED HelloWorld to dom node" success message
+- Confirm React component is interactive (input field updates name display)
+
+**Development Mode Console Output**:
+
+- `bin/dev` (HMR): Shows HMR warnings and resource preload warnings (expected)
+- `bin/dev static`: Shows only resource preload warnings (cleaner output)
+- `bin/dev prod`: Cleanest output with minimal warnings (production-like environment)
+
+**Note**: Resource preload warnings in development modes are normal and can be ignored. They occur because Shakapacker generates preload tags but scripts load asynchronously. Production mode eliminates most of these warnings.
+
+#### Generator Testing Troubleshooting
+
+**Common Issues and Solutions:**
+
+1. **React components not rendering (empty divs)**
+
+   - **Cause**: Missing yalc setup for JavaScript package
+   - **Solution**: Follow yalc setup steps above after running generator
+
+2. **Generator fails with Shakapacker errors**
+
+   - **Cause**: Conflicting Shakapacker versions or incomplete installation
+   - **Solution**: Clean reset and ensure consistent Shakapacker version across tests
+
+3. **Babel configuration conflicts during yalc development**
+
+   - **Cause**: Both `babel.config.js` and `package.json` "babel" section defining presets
+   - **Solution**: Remove "babel" section from `package.json`, keep only `babel.config.js`
+
+4. **"Package.json not found" errors**
+
+   - **Cause**: Generator trying to access non-existent package.json files
+   - **Solution**: Test with commits that fix this specific issue (e.g., bc69dcd0)
+
+5. **Port conflicts during testing**
+   - **Cause**: Multiple development servers running
+   - **Solution**: Run `bin/dev kill` before starting new test servers
+
+**Testing Best Practices:**
+
+- Always use the double clean command: `git clean -fd && git reset --hard && git clean -fd`
+- Test both Shakapacker scenarios for comprehensive coverage
+- Document exact error messages and steps to reproduce
+- Verify React component interactivity, not just rendering
+- Test all development modes: `bin/dev`, `bin/dev static`, `bin/dev prod`
+
+## Pre-Commit Requirements
+
+**CRITICAL**: Before committing any changes, always run the following commands to ensure code quality:
+
+```bash
+# Navigate to the main react_on_rails directory
+cd react_on_rails/
+
+# Run Prettier for JavaScript/TypeScript formatting
+yarn run format
+
+# Run ESLint for JavaScript/TypeScript linting
+yarn run lint
+
+# Run RuboCop for Ruby linting and formatting
+rake lint:rubocop
+
+# Or run all linters together
+rake lint
+```
+
+**Automated checks:**
+
+- Format all JavaScript/TypeScript files with Prettier
+- Check and fix linting issues with ESLint
+- Check and fix Ruby style issues with RuboCop
+- Ensure all tests pass before pushing
+
+**Tip**: Set up your IDE to run these automatically on save to catch issues early.
+
+## 🤖 Best Practices for AI Coding Agents
+
+**CRITICAL WORKFLOW** to prevent CI failures:
+
+### 1. **After Making Code Changes**
+
+```bash
+# Auto-fix all linting violations after code changes
+rake autofix
+```
+
+### 2. **Common AI Agent Mistakes**
+
+❌ **DON'T:**
+
+- Commit code that hasn't been linted locally
+- Ignore formatting rules when creating new files
+- Add manual formatting that conflicts with Prettier/RuboCop
+
+✅ **DO:**
+
+- Run `rake lint` after any code changes
+- Use `rake autofix` to automatically fix all linting violations
+- Create new files that follow existing patterns
+- Test locally before committing
+
+### 4. **Template File Best Practices**
+
+When creating new template files (`.jsx`, `.rb`, etc.):
+
+1. Copy existing template structure and patterns
+2. Run `yarn run eslint . --fix` immediately after creation
+3. Verify with `rake lint` before committing
+
+### 5. **RuboCop Complexity Issues**
+
+For methods with high ABC complexity (usually formatting/display methods):
+
+```ruby
+# rubocop:disable Metrics/AbcSize
+def complex_formatting_method
+  # ... method with lots of string interpolation/formatting
+end
+# rubocop:enable Metrics/AbcSize
+```
+
+**Remember**: Failing CI wastes time and resources. Always lint locally first!
+
 ### Linting
 
 All linting is performed from the docker container for CI. You will need docker and docker-compose installed locally to lint code changes via the lint container. You can lint locally by running `npm run lint && npm run flow`
@@ -273,3 +574,77 @@ Run `docker-compose build tests` to build the tests container. Run `docker-compo
 What do project maintainers do? What sort of work is involved? [sstephenson](https://github.com/sstephenson) wrote in the [turbolinks](https://github.com/turbolinks/turbolinks) repo:
 
 > [Why this is not still fully merged?](https://github.com/turbolinks/turbolinks/pull/124#issuecomment-239826060)
+
+# 📦 Demo Naming and README Standards
+
+To keep our React on Rails demos clear, discoverable, and SEO-friendly, all demo repos follow a standardized naming and documentation structure.
+
+---
+
+## ✅ Repository Naming Convention
+
+Use the format:
+
+```
+react_on_rails-demo-v[REACT_ON_RAILS_VERSION]-[key-topics]
+```
+
+**Examples:**
+
+- `react_on_rails-demo-v15-ssr-auto-registration-bundle-splitting`
+- `react_on_rails-demo-v15-react-server-components`
+- `react_on_rails-demo-v15-typescript-setup`
+- `react_on_rails-demo-v15-cypress-setup`
+
+**Why this format?**
+
+- Clear versioning and purpose
+- Easy to discover in GitHub, search engines, and documentation
+- Consistent prefix for grouping demos together
+
+---
+
+## 📝 README Title Format
+
+```
+# React on Rails Demo: [Topics] with v[VERSION] and Rails [VERSION]
+```
+
+**Example:**
+
+```
+# React on Rails Demo: SSR, Auto-Registration & Bundle Splitting with v15 and Rails 8
+```
+
+---
+
+## 📄 README Description Template
+
+```
+A fully working demo of React on Rails v[VERSION] on Rails [VERSION], showcasing [topics].
+
+✅ Includes:
+- [Topic 1]
+- [Topic 2]
+- [Topic 3]
+
+📂 Repo name: `react_on_rails-demo-v[VERSION]-[topics]`
+
+📚 Part of the [React on Rails Demo Series](https://github.com/shakacode?tab=repositories&q=react_on_rails-demo)
+```
+
+**Example:**
+
+```
+A fully working demo of React on Rails v15 on Rails 8, showcasing server-side rendering, file-system-based auto-registration, and intelligent bundle splitting.
+
+✅ Includes:
+- Server-Side Rendering (SSR)
+- Auto-discovered components based on file structure
+- Lightweight vs. heavy component splitting
+- Fix for “package.json not found” install bug
+
+📂 Repo name: `react_on_rails-demo-v15-ssr-auto-registration-bundle-splitting`
+
+📚 Part of the [React on Rails Demo Series](https://github.com/shakacode?tab=repositories&q=react_on_rails-demo)
+```

data/Gemfile.lock

@@ -1,12 +1,13 @@
 PATH
   remote: .
   specs:
-    react_on_rails (15.0.0.rc.1)
+    react_on_rails (16.0.0)
       addressable
       connection_pool
       execjs (~> 2.5)
       rails (>= 5.2)
       rainbow (~> 3.0)
+      shakapacker (>= 6.0)
 
 GEM
   remote: https://rubygems.org/

data/LICENSE.md

@@ -1,6 +1,19 @@
-# The MIT License (MIT)
+# Licensing
 
-Copyright (c) 2017, 2018 Justin Gordon and ShakaCode, http://www.shakacode.com
+- **Core**: MIT (this file)
+- **Pro**: see [REACT-ON-RAILS-PRO-LICENSE.md](./REACT-ON-RAILS-PRO-LICENSE.md)
+
+---
+
+## MIT License for Core React on Rails
+
+This license applies to all files within this repository, with the exception of the code located in the following directories, which are licensed separately under the React on Rails Pro License:
+
+- `lib/react_on_rails/pro/`
+- `node_package/src/pro/`
+
+Copyright (c) 2017, 2018 Justin Gordon and ShakaCode  
+Copyright (c) 2015–2025 ShakaCode, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -12,10 +25,23 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 
+---
+
+## Disclaimer
+
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## React on Rails Pro License
+
+The code in the directories listed above is part of the React on Rails Pro framework and is licensed under the React on Rails Pro License.
+
+You can find the full text of the license agreement here:
+[REACT-ON-RAILS-PRO-LICENSE.md](./REACT-ON-RAILS-PRO-LICENSE.md)

data/LICENSES/README.md

@@ -0,0 +1,14 @@
+# Licensing Overview
+
+This repository uses a dual-licensing model:
+
+- [LICENSE.md](../LICENSE.md) – **MIT** license for the core React on Rails library
+- [REACT-ON-RAILS-PRO-LICENSE.md](../REACT-ON-RAILS-PRO-LICENSE.md) – **commercial license** for React on Rails Pro
+
+---
+
+## Summary
+
+- Core (MIT) → free and open-source for any use
+- Pro → free for non-commercial, educational, and demo use
+- **Production Use** (including by non-profits) requires a paid subscription

data/REACT-ON-RAILS-PRO-LICENSE.md

@@ -0,0 +1,129 @@
+# ShakaCode React on Rails Pro – End User License Agreement (EULA)
+
+_Version 2.0 — 2025-09-06_  
+© 2015–2025 ShakaCode, LLC. All rights reserved.
+
+---
+
+## 1. Definitions
+
+- **Organization** – the single legal entity identified in the order (e.g., GitHub Sponsors, invoice).
+- **Production Use** – any use of the Software in connection with a live application, website, or service accessed by end users **other than**:
+  - evaluation or testing
+  - classroom instruction, tutorials, workshops, coursework
+  - recorded demos, livestreams, or videos
+  - personal/hobby experiments not offered as a service
+
+---
+
+## 2. Grant of License (Per-Organization)
+
+ShakaCode grants the subscribing Organization a **non-exclusive, non-transferable, revocable** license to install and use React on Rails Pro (“Software”) for the Organization’s internal applications.
+
+- Internal modifications are allowed.
+- Redistribution, sublicensing, or hosting the Software for third parties is prohibited.
+
+---
+
+## 3. Consulting Firms and Individual Consultants
+
+- **Consulting Firms** – this license covers only the firm’s own internal systems. Each client Organization requires its own license for any Production Use.
+- **Individual Consultants** – this license covers only the consultant’s own projects personally operated by them, not client organizations. Each client Organization must obtain its own license.
+
+---
+
+## 4. Non-Commercial / Educational / Demo Use (Free)
+
+Free, royalty-free use is permitted for:
+
+- classroom instruction, training, workshops, coursework;
+- tutorials, blog posts, livestreams, or videos;
+- personal/hobby projects not used in production;
+- demo apps showcasing coding techniques.
+
+**Note:** This clause does **not** permit any Production Use by any entity (commercial, non-profit, or individual). All Production Use requires a paid subscription under this Agreement.
+
+---
+
+## 5. Restrictions
+
+The Organization shall not:
+
+1. redistribute or resell the Software or derivatives;
+2. remove, obfuscate, or disable required attribution;
+3. use the Software to build a directly competing product exposing substantially similar functionality.
+
+---
+
+## 6. Attribution (HTML Source)
+
+Pages rendered using the Software must include a retained non-visual attribution comment in the HTML source (provided by the software):
+
+```html
+<!-- Powered by React on Rails Pro (c) ShakaCode -->
+```
+
+The Organization may not remove or obfuscate this attribution.
+
+---
+
+## 7. Fees; Term; Termination
+
+Fees and billing terms are as agreed in the applicable order (e.g., GitHub Sponsors subscription or annual invoice).  
+The license remains active only while fees are paid. ShakaCode may suspend or terminate for non-payment or material breach.  
+Upon termination or lapse, the Organization must immediately cease use and remove the Software (including derivatives) from all Production systems and repositories, except for non-commercial uses explicitly permitted in Section 4.
+
+---
+
+## 8. Updates & Support
+
+While subscribed, the Organization receives software updates and reasonable support (email or issue tracker, business hours). No specific response or resolution times are guaranteed unless set out in an order or separate SLA.
+
+---
+
+## 9. Verification / Audit
+
+If ShakaCode reasonably suspects non-compliance, the Organization will cooperate in good faith to verify compliance, including enabling inspection for attribution presence and providing a usage statement. ShakaCode will use commercially reasonable efforts to minimize disruption.
+
+---
+
+## 10. Feedback & Contributions
+
+By submitting feedback or improvements, the Organization grants ShakaCode a worldwide, royalty-free, irrevocable license to use and incorporate them.
+
+---
+
+## 11. Intellectual Property
+
+The Software is **licensed, not sold**. ShakaCode retains all rights, title, and interest, including all intellectual property rights.
+
+---
+
+## 12. Confidentiality
+
+License keys and any non-public materials are ShakaCode confidential information. The Organization will protect them with at least reasonable care.
+
+---
+
+## 13. Warranty Disclaimer
+
+> EXCEPT AS EXPRESSLY PROVIDED IN §8, THE SOFTWARE IS PROVIDED “AS IS,” WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED.
+
+---
+
+## 14. Limitation of Liability
+
+To the maximum extent permitted by law, ShakaCode is not liable for indirect, incidental, special, consequential, or punitive damages.  
+Direct damages are limited to amounts paid in the 12 months preceding the claim.
+
+---
+
+## 15. Governing Law; Venue
+
+Choose one: **State of Hawaii**, USA. Exclusive jurisdiction and venue lie in the courts located therein.
+
+---
+
+## 16. Entire Agreement; Order of Precedence
+
+This EULA and any order (pricing/term) are the entire agreement. If there is a conflict, the order controls.