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

data/README.md

@@ -9,7 +9,7 @@
 
 ---
 
-[![License](https://img.shields.io/badge/license-mit-green.svg)](LICENSE.md)[![Gem Version](https://badge.fury.io/rb/react_on_rails.svg)](https://badge.fury.io/rb/react_on_rails) [![npm version](https://badge.fury.io/js/react-on-rails.svg)](https://badge.fury.io/js/react-on-rails) [![Code Climate](https://codeclimate.com/github/shakacode/react_on_rails/badges/gpa.svg)](https://codeclimate.com/github/shakacode/react_on_rails) [![Coverage Status](https://coveralls.io/repos/shakacode/react_on_rails/badge.svg?branch=master&service=github)](https://coveralls.io/github/shakacode/react_on_rails?branch=master) [![](https://ruby-gem-downloads-badge.herokuapp.com/react_on_rails?type=total)](https://rubygems.org/gems/react_on_rails)
+[![License](https://img.shields.io/badge/license-mit-green.svg)](LICENSE.md)[![Gem Version](https://badge.fury.io/rb/react_on_rails.svg)](https://badge.fury.io/rb/react_on_rails) [![npm version](https://badge.fury.io/js/react-on-rails.svg)](https://badge.fury.io/js/react-on-rails) [![Coverage Status](https://coveralls.io/repos/shakacode/react_on_rails/badge.svg?branch=master&service=github)](https://coveralls.io/github/shakacode/react_on_rails?branch=master) [![](https://ruby-gem-downloads-badge.herokuapp.com/react_on_rails?type=total)](https://rubygems.org/gems/react_on_rails)
 
 [![Build Main](https://github.com/shakacode/react_on_rails/actions/workflows/main.yml/badge.svg)](https://github.com/shakacode/react_on_rails/actions/workflows/main.yml)
 [![Build JS Tests](https://github.com/shakacode/react_on_rails/actions/workflows/package-js-tests.yml/badge.svg)](https://github.com/shakacode/react_on_rails/actions/workflows/package-js-tests.yml)
@@ -18,13 +18,18 @@
 
 # News
 
+**🚀 React on Rails v16.0 Released!** Major modernization with ESM support, enhanced React Server Components, and streamlined configuration.
+
+- **ESM-only package**: Modern module system with better tree-shaking and performance
+- **React Server Components**: Improved rendering flow and new `RSCRoute` component for seamless SSR
+- **Performance improvements**: New async loading strategies and optimized bundle generation
+- **Webpacker removal**: Streamlined for Shakapacker-only support (>= 6.0)
 - [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) supports the latest features of React 18, including [React Server Components](https://react.dev/reference/rsc/server-components) and [streaming](https://react.dev/reference/react-dom/server/renderToPipeableStream). Contact [Justin Gordon](mailto:justin@shakacode.com) for more information.
 - ShakaCode now maintains the official successor to `rails/webpacker`, [`shakapacker`](https://github.com/shakacode/shakapacker).
-- Project is updated to support Rails 7 and Shakapacker v6+!
 
 ---
 
-_These are the docs for React on Rails 14. To see the older docs and code: [v13](https://github.com/shakacode/react_on_rails/tree/13.4.0), [v12](https://github.com/shakacode/react_on_rails/tree/12.6.0), and [v11](https://github.com/shakacode/react_on_rails/tree/11.3.0)._
+_These are the docs for React on Rails 16. To see the older docs and code: [v14](https://github.com/shakacode/react_on_rails/tree/14.0.0), [v13](https://github.com/shakacode/react_on_rails/tree/13.4.0), [v12](https://github.com/shakacode/react_on_rails/tree/12.6.0), and [v11](https://github.com/shakacode/react_on_rails/tree/11.3.0)._
 
 # About
 
@@ -42,16 +47,55 @@ We also specialize in helping development teams lower infrastructure and CI cost
 
 If you think ShakaCode can help your project, [click here](https://meetings.hubspot.com/justingordon/30-minute-consultation) to book a call with [Justin Gordon](mailto:justin@shakacode.com), the creator of React on Rails.
 
+## Upgrading React on Rails
+
+After upgrading to a new major version, run the generator to get latest defaults:
+
+```bash
+rails generate react_on_rails:install
+```
+
+**Important**: Review changes carefully before applying to avoid overwriting custom configurations. The generator updates:
+
+- `bin/dev` (improved development workflow)
+- webpack configurations
+- `shakapacker.yml` settings
+- other configuration files
+
+### Troubleshooting Setup Issues
+
+If you encounter issues during installation or after upgrading, use the doctor command to diagnose your setup:
+
+```bash
+rake react_on_rails:doctor
+```
+
+The doctor command checks your environment, dependencies, and configuration files to identify potential issues. Use `VERBOSE=true rake react_on_rails:doctor` for detailed output.
+
+For detailed upgrade instructions, see [upgrade guide documentation](docs/guides/upgrading-react-on-rails.md).
+
 ## React on Rails Pro
 
-Are you interested in optimizing your Webpack setup for React on Rails, including code splitting with [React Router](https://reactrouter.com/) and [loadable-components](https://loadable-components.com/) with server-side rendering for SEO and hot-reloading for developers?
+Some features of React on Rails regarding performance require a React on Rails Pro subscription.
+
+Note: the subscription price is free for evaluation and non-production use.
+
+Notable new features include:
+
+- React Server Components
+- Streaming SSR
+- Loadable Components
+- Code Splitting with React Router
+
+React on Rails Pro is the best way to optimize your Webpack setup for React on Rails, including code splitting with [React Router](https://reactrouter.com/) and [loadable-components](https://loadable-components.com/) with server-side rendering for SEO and hot-reloading for developers.
+
 We did this for Popmenu, [lowering Heroku costs 20-25% while getting a 73% decrease in average response times](https://www.shakacode.com/recent-work/popmenu/). Several years later, Popmenu serves tens of millions of SSR requests daily with React on Rails Pro.
 
 If you're interested, read more about [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/) and [book a call](https://meetings.hubspot.com/justingordon/30-minute-consultation).
 
 # Documentation
 
-See the documentation at **[shakacode.com/react-on-rails/docs](https://www.shakacode.com/react-on-rails/docs/)**.
+See the documentation at **[shakacode.com/react-on-rails/docs](https://www.shakacode.com/react-on-rails/docs/)** and [React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/).
 
 ## Project Objective
 
@@ -61,18 +105,20 @@ To provide a high-performance framework for integrating Ruby on Rails with React
 
 Given that `shakacode/shakapacker` gem already provides basic React integration, why would you use "React on Rails"?
 
-1. Automatic configuration of what bundles are added to the page based on what React components are on the page. This results in faster browser loading time via smaller bundle sizes.
-1. Keep up with the latest changes in different versions of React. React 18 is supported.
-1. Easy passing of props directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API.
-   Tight integration with [shakapacker](https://github.com/shakacode/shakapacker) (or its predecessor [rails/webpacker](https://github.com/rails/webpacker)).
-1. Server-Side Rendering (SSR), often used for SEO crawler indexing and UX performance.
-1. [Automated optimized entry-point creation and bundle inclusion when placing a component on a page. With this feature, you no longer need to configure `javascript_pack_tags` and `stylesheet_pack_tags` on your layouts based on what’s shown. “It just works!”](https://www.shakacode.com/react-on-rails/docs/guides/file-system-based-automated-bundle-generation/)
-1. [Redux](https://redux.js.org/) and [React Router](https://reactrouter.com/) integration with server-side-rendering.
-1. [Internationalization (I18n) and (localization)](https://www.shakacode.com/react-on-rails/docs/guides/i18n)
-1. A supportive community. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/).
-1. [ReScript Support](https://github.com/shakacode/rescript-react-on-rails-example).
-
-See [Rails/Webpacker React Integration Options](https://www.shakacode.com/react-on-rails/docs/guides/rails-webpacker-react-integration-options) for comparisons to other gems.
+1. **Modern ESM-only package** with optimized tree-shaking for smaller bundle sizes and better performance.
+1. **Advanced loading strategies** with `sync`, `async`, and `defer` options for optimal performance based on your needs.
+1. **Automatic configuration** of what bundles are added to the page based on what React components are on the page. This results in faster browser loading time via smaller bundle sizes.
+1. **Keep up with the latest changes** in different versions of React. React 18+ is fully supported with enhanced React Server Components.
+1. **Easy prop passing** directly from your Rails view to your React components rather than having your Rails view load and then make a separate request to your API.
+   Tight integration with [shakapacker](https://github.com/shakacode/shakapacker).
+1. **Server-Side Rendering (SSR)** with enhanced React Server Components support, often used for SEO crawler indexing and UX performance.
+1. **[Automated optimized entry-point creation and bundle inclusion](https://www.shakacode.com/react-on-rails/docs/guides/file-system-based-automated-bundle-generation/)** when placing a component on a page. With this feature, you no longer need to configure `javascript_pack_tags` and `stylesheet_pack_tags` on your layouts based on what's shown. "It just works!"
+1. **[Redux](https://redux.js.org/) and [React Router](https://reactrouter.com/) integration** with server-side-rendering.
+1. **[Internationalization (I18n) and (localization)](https://www.shakacode.com/react-on-rails/docs/guides/i18n)** support.
+1. **Supportive community**. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/).
+1. **[ReScript Support](https://github.com/shakacode/rescript-react-on-rails-example)**.
+
+See [Rails/Shakapacker React Integration Options](https://www.shakacode.com/react-on-rails/docs/guides/rails-webpacker-react-integration-options) for comparisons to other gems.
 
 ## Online demo
 
@@ -88,7 +134,11 @@ _Requires creating a free account._
 
 ## Prerequisites
 
-Ruby on Rails >=5, rails/webpacker >= 4.2 or shakapacker > 6, Ruby >= 3.0.0
+- Ruby on Rails >= 5
+- Shakapacker >= 6.0 (Webpacker is no longer supported as of v16)
+- Ruby >= 3.2 (CI tested: 3.2 - 3.4)
+- Node.js >= 20 (CI tested: 20 - 22)
+- A JavaScript package manager (npm, yarn, pnpm, or bun)
 
 # Support
 
@@ -120,8 +170,8 @@ The following companies support our open-source projects, and ShakaCode uses the
 <br />
 <br />
 
-<a href="https://www.jetbrains.com">
-  <img src="https://user-images.githubusercontent.com/4244251/184881139-42e4076b-024b-4b30-8c60-c3cd0e758c0a.png" alt="JetBrains" height="120px">
+<a href="https://jb.gg/OpenSource" style="margin-right: 20px;">
+  <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains" height="120px">
 </a>
 <a href="https://scoutapp.com">
   <picture>

data/TODO.md

@@ -0,0 +1,135 @@
+# React on Rails TODO
+
+## Generator Improvements
+
+### HelloWorld Component Structure
+
+- [x] Fix bad import in HelloWorld.server.jsx (server importing from client)
+- [x] Simplify to single HelloWorld.jsx file with documentation
+- [ ] **Consider alternative approach**: Create second example component showing client/server split
+  - Add `client_server_different.jsx` in sibling directory like `/examples/` or `/advanced/`
+  - Show real-world use case (React Router, styled-components, etc.)
+  - Keep HelloWorld simple for beginners
+
+### File Organization
+
+- [x] **Improved ror_components directory structure**
+  - Documentation now suggests moving shared components to `../components/` directory
+  - Keeps ror_components clean for React on Rails specific entry points
+  - Recommended structure:
+    ```
+    src/HelloWorld/
+    ├── components/
+    │   └── HelloWorld.jsx          # Shared component implementation
+    └── ror_components/
+        ├── HelloWorld.client.jsx   # Client entry point (when needed)
+        └── HelloWorld.server.jsx   # Server entry point (when needed)
+    ```
+- [ ] **Consider adding generator flag to create this structure automatically**
+
+### Generator Options
+
+- [ ] **Add generator flags for different patterns**
+  - `--simple` (default): Single component file
+  - `--split`: Generate client/server split example
+  - `--example-name`: Customize component name beyond HelloWorld
+
+## Documentation Improvements
+
+### Component Architecture Guide
+
+- [ ] **Add comprehensive docs on client/server patterns**
+  - When to use single vs split files
+  - Common libraries requiring server setup (React Router, styled-components, Apollo)
+  - Migration path from simple to split architecture
+  - Auto-registration behavior explanation
+
+### Code Comments
+
+- [x] Add inline documentation to HelloWorld.jsx explaining split pattern
+- [ ] Add JSDoc comments for better IDE support
+- [ ] Include links to relevant documentation sections
+
+## Testing Infrastructure
+
+- [ ] **Test generator output for both simple and split patterns**
+- [ ] **Validate that auto-registration works correctly**
+- [ ] **Add integration tests for client/server rendering differences**
+
+## Developer Experience
+
+- [ ] **bin/dev help command enhancements**
+
+  - [x] Add emojis and colors for better readability
+  - [ ] Add section about component development patterns
+  - [ ] Include troubleshooting for client/server split issues
+
+- [ ] **Babel Configuration Conflict Detection**
+
+  - [ ] Add validation in generator/initializer to detect conflicting Babel configs
+  - [ ] Improve error messaging for duplicate preset issues
+  - [ ] Common conflict: babel.config.js + package.json "babel" section
+  - [ ] Specific guidance for yalc development workflow
+  - [ ] Add troubleshooting section for this common issue:
+
+    ```
+    ❌ BABEL CONFIGURATION CONFLICT DETECTED
+    Found duplicate Babel configurations:
+    • babel.config.js ✓ (recommended)
+    • package.json "babel" section ❌ (conflicting)
+
+    🔧 FIX: Remove the "babel" section from package.json
+    ```
+
+### IDE Support
+
+- [ ] **Improve TypeScript support**
+  - Add .d.ts files for better type inference
+  - Document TypeScript patterns for client/server split
+  - Consider TypeScript generator templates
+
+## Performance & Bundle Analysis
+
+- [ ] **Bundle splitting documentation**
+  - How React on Rails handles client/server bundles
+  - Best practices for code splitting
+  - webpack bundle analysis guidance
+
+## Real-World Examples
+
+- [ ] **Create example apps showing advanced patterns**
+  - React Router with SSR
+  - styled-components with server-side rendering
+  - Apollo Client hydration
+  - Next.js-style patterns
+
+## Migration Guide
+
+- [ ] **Document upgrade paths**
+  - Converting from Webpacker to Shakapacker
+  - Migrating from single to split components
+  - Updating existing projects to new patterns
+
+## Community & Ecosystem
+
+- [ ] **Plugin ecosystem considerations**
+  - Standard patterns for community components
+  - Guidelines for React on Rails compatible libraries
+  - Template repository for component patterns
+
+---
+
+## Current Known Issues
+
+- Generator installer still has remaining issues (mentioned in context)
+- Version mismatch warnings with yalc during development
+- Need clearer documentation on when to use different patterns
+- **Babel configuration conflicts** - Common during yalc development when package.json and babel.config.js both define presets
+
+## Priority Order
+
+1. Fix remaining generator installer issues
+2. Improve HelloWorld component documentation
+3. Add alternative example showing client/server split
+4. Create comprehensive architecture documentation
+5. Add generator flags for different patterns

data/eslint.config.ts

@@ -44,6 +44,9 @@ const config = tsEslint.config([
     // fixtures
     '**/fixtures/',
     '**/.yalc/**/*',
+    // generator templates - exclude TypeScript templates that need tsconfig.json
+    '**/templates/**/*.tsx',
+    '**/templates/**/*.ts',
   ]),
   {
     files: ['**/*.[jt]s', '**/*.[jt]sx', '**/*.[cm][jt]s'],
@@ -152,6 +155,8 @@ const config = tsEslint.config([
       'import/no-unresolved': 'off',
       // We have `const [name, setName] = useState(props.name)` so can't just destructure props
       'react/destructuring-assignment': 'off',
+      // React 19 doesn't need PropTypes - we're targeting modern React
+      'react/prop-types': 'off',
     },
   },
   {

data/knip.ts

@@ -6,21 +6,32 @@ const config: KnipConfig = {
     '.': {
       entry: [
         'node_package/src/ReactOnRails.node.ts!',
-        'node_package/src/ReactOnRailsRSC.ts!',
-        'node_package/src/registerServerComponent/client.tsx!',
-        'node_package/src/registerServerComponent/server.tsx!',
-        'node_package/src/registerServerComponent/server.rsc.ts!',
-        'node_package/src/wrapServerComponentRenderer/server.tsx!',
-        'node_package/src/wrapServerComponentRenderer/server.rsc.tsx!',
-        'node_package/src/RSCRoute.tsx!',
-        'node_package/src/ServerComponentFetchError.ts!',
+        'node_package/src/pro/ReactOnRailsRSC.ts!',
+        'node_package/src/pro/registerServerComponent/client.tsx!',
+        'node_package/src/pro/registerServerComponent/server.tsx!',
+        'node_package/src/pro/registerServerComponent/server.rsc.ts!',
+        'node_package/src/pro/wrapServerComponentRenderer/server.tsx!',
+        'node_package/src/pro/wrapServerComponentRenderer/server.rsc.tsx!',
+        'node_package/src/pro/RSCRoute.tsx!',
+        'node_package/src/pro/ServerComponentFetchError.ts!',
+        'node_package/src/pro/getReactServerComponent.server.ts!',
+        'node_package/src/pro/transformRSCNodeStream.ts!',
+        'node_package/src/loadJsonFile.ts!',
         'eslint.config.ts',
       ],
       project: ['node_package/src/**/*.[jt]s{x,}!', 'node_package/tests/**/*.[jt]s{x,}'],
       babel: {
         config: ['node_package/babel.config.js'],
       },
-      ignore: ['node_package/tests/emptyForTesting.js'],
+      ignore: [
+        'node_package/tests/emptyForTesting.js',
+        // Pro features exported for external consumption
+        'node_package/src/pro/streamServerRenderedReactComponent.ts:transformRenderStreamChunksToResultObject',
+        'node_package/src/pro/streamServerRenderedReactComponent.ts:streamServerRenderedComponent',
+        'node_package/src/pro/ServerComponentFetchError.ts:isServerComponentFetchError',
+        'node_package/src/pro/RSCRoute.tsx:RSCRouteProps',
+        'node_package/src/pro/streamServerRenderedReactComponent.ts:StreamingTrackers',
+      ],
       ignoreBinaries: [
         // Knip fails to detect it's declared in devDependencies
         'nps',

data/lib/generators/USAGE

@@ -1,9 +1,8 @@
 Description:
 
-The react_on_rails:install generator integrates Webpack with Rails with ease. You
-can pass the redux option if you'd like to have redux setup for you automatically.
+The react_on_rails:install generator integrates a React frontend, including SSR, with Rails.
 
-* Redux
+* Redux (Optional)
 
     Passing the --redux generator option causes the generated Hello World example
     to integrate the Redux state container framework. The necessary node modules
@@ -13,11 +12,11 @@ can pass the redux option if you'd like to have redux setup for you automaticall
 
 After running the generator, you will want to:
 
-    bundle && yarn
+    bundle && npm install     # or yarn install, or pnpm install
 
 Then you may run
 
-    foreman start -f Procfile.dev
+    ./bin/dev
 
 More Details:
 

data/lib/generators/react_on_rails/USAGE

@@ -0,0 +1,65 @@
+Description:
+    The `react_on_rails:doctor` generator diagnoses your React on Rails setup
+    and identifies potential configuration issues. It performs comprehensive
+    checks on your environment, dependencies, and configuration files.
+
+    This command is especially useful for:
+    • Troubleshooting setup issues
+    • Verifying installation after running react_on_rails:install
+    • Ensuring compatibility after upgrades
+    • Getting help with configuration problems
+
+Example:
+    # Basic diagnosis
+    rails generate react_on_rails:doctor
+
+    # Verbose output showing all checks
+    rails generate react_on_rails:doctor --verbose
+
+    # Show help
+    rails generate react_on_rails:doctor --help
+
+Checks performed:
+    Environment Prerequisites:
+    • Node.js installation and version compatibility
+    • JavaScript package manager availability (npm, yarn, pnpm, bun)
+    • Git working directory status
+
+    React on Rails Packages:
+    • React on Rails gem installation
+    • react-on-rails NPM package installation
+    • Version synchronization between gem and NPM package
+    • Shakapacker configuration and installation
+
+    Dependencies:
+    • React and React DOM installation
+    • Babel preset configuration
+    • Required development dependencies
+
+    Rails Integration:
+    • React on Rails initializer configuration
+    • Route and controller setup (Hello World example)
+    • View helper integration
+
+    Webpack Configuration:
+    • Webpack config file existence and structure
+    • React on Rails compatibility checks
+    • Environment-specific configuration validation
+
+    Development Environment:
+    • JavaScript bundle files
+    • Procfile.dev for development workflow
+    • .gitignore configuration for generated files
+
+Options:
+    --verbose, -v: Show detailed output for all checks, including successful ones
+    --fix, -f:     Attempt to fix simple issues automatically (planned feature)
+
+Exit codes:
+    0: All checks passed or only warnings found
+    1: Critical errors found that prevent React on Rails from working
+
+For more help:
+    • Documentation: https://github.com/shakacode/react_on_rails
+    • Issues: https://github.com/shakacode/react_on_rails/issues
+    • Discord: https://discord.gg/reactrails