react_on_rails_pro 16.2.0.beta.8

data/docs/streaming-server-rendering.md

@@ -0,0 +1,210 @@
+# 🚀 Streaming Server Rendering with React 18
+
+React on Rails Pro supports streaming server rendering using React 18's latest APIs, including `renderToPipeableStream` and Suspense. This guide explains how to implement and optimize streaming server rendering in your React on Rails application.
+
+## Prerequisites
+
+- React on Rails Pro subscription
+- React 19
+- React on Rails v15.0.0-alpha.0 or higher
+- React on Rails Pro v4.0.0 or higher
+
+## Benefits of Streaming Server Rendering
+
+- Faster Time to First Byte (TTFB)
+- Progressive page loading
+- Improved user experience
+- Better SEO performance
+- Optimal handling of data fetching
+
+## Implementation Steps
+
+1. **Use React 19 Version**
+
+First, ensure you're using React 19 in your package.json:
+
+```json
+"dependencies": {
+  "react": "19.0.0",
+  "react-dom": "19.0.0"
+}
+```
+
+> Note: Check the React documentation for the latest release that supports streaming.
+
+2. **Prepare Your React Components**
+
+You can create async React components that return a promise. Then, you can use the `Suspense` component to render a fallback UI while the component is loading.
+
+```jsx
+// app/javascript/components/MyStreamingComponent.jsx
+import React, { Suspense } from 'react';
+
+const fetchData = async () => {
+  // Simulate API call
+  const response = await fetch('api/endpoint');
+  return response.json();
+};
+
+const MyStreamingComponent = () => {
+  return (
+    <>
+      <header>
+        <h1>Streaming Server Rendering</h1>
+      </header>
+      <Suspense fallback={<div>Loading...</div>}>
+        <SlowDataComponent />
+      </Suspense>
+    </>
+  );
+};
+
+const SlowDataComponent = async () => {
+  const data = await fetchData();
+  return <div>{data}</div>;
+};
+
+export default MyStreamingComponent;
+```
+
+```jsx
+// app/javascript/packs/registration.jsx
+import MyStreamingComponent from '../components/MyStreamingComponent';
+
+ReactOnRails.register({ MyStreamingComponent });
+```
+
+3. **Add The Component To Your Rails View**
+
+```erb
+<!-- app/views/example/show.html.erb -->
+
+<%=
+  stream_react_component(
+    'MyStreamingComponent',
+    props: { greeting: 'Hello, Streaming World!' },
+    prerender: true
+  )
+%>
+
+<footer>
+  <p>Footer content</p>
+</footer>
+```
+
+4. **Render The View Using The `stream_view_containing_react_components` Helper**
+
+Ensure you have a controller that renders the view containing the React components. The controller must include the `ReactOnRails::Controller`, `ReactOnRailsPro::Stream` and `ActionController::Live` modules.
+
+```ruby
+# app/controllers/example_controller.rb
+
+class ExampleController < ApplicationController
+  include ReactOnRailsPro::Stream
+
+  def show
+    stream_view_containing_react_components(template: 'example/show')
+  end
+end
+```
+
+5. **Test Your Application**
+
+You can test your application by running `rails server` and navigating to the appropriate route.
+
+
+6. **What Happens During Streaming**
+
+When a user visits the page, they'll experience the following sequence:
+
+1. The initial HTML shell is sent immediately, including:
+   - The page layout
+   - Any static content (like the `<h1>` and footer)
+   - Placeholder content for the React component (typically a loading state)
+
+2. As the React component processes and suspense boundaries resolve:
+   - HTML chunks are streamed to the browser progressively
+   - Each chunk updates a specific part of the page
+   - The browser renders these updates without a full page reload
+
+For example, with our `MyStreamingComponent`, the sequence might be:
+
+1. The initial HTML includes the header, footer, and loading state.
+
+```html
+<header>
+  <h1>Streaming Server Rendering</h1>
+</header>
+<template id="s0">
+  <div>Loading...</div>
+</template>
+<footer>
+  <p>Footer content</p>
+</footer>
+```
+
+2. As the component resolves, HTML chunks are streamed to the browser:
+
+```html
+<template hidden id="b0">
+  <div>[Fetched data]</div>
+</template>
+
+<script>
+  // This implementation is slightly simplified
+  document.getElementById('s0').replaceChildren(
+    document.getElementById('b0')
+  );
+</script>
+```
+
+## When to Use Streaming
+
+Streaming SSR is particularly valuable in specific scenarios. Here's when to consider it:
+
+### Ideal Use Cases
+
+1. **Data-Heavy Pages**
+   - Pages that fetch data from multiple sources
+   - Dashboard-style layouts where different sections can load independently
+   - Content that requires heavy processing or computation
+
+2. **Progressive Enhancement**
+   - When you want users to see and interact with parts of the page while others load
+   - For improving perceived performance on slower connections
+   - When different parts of your page have different priority levels
+
+3. **Large, Complex Applications**
+   - Applications with multiple independent widgets or components
+   - Pages where some content is critical and other content is supplementary
+   - When you need to optimize Time to First Byte (TTFB)
+
+### Best Practices for Streaming
+
+1. **Component Structure**
+   ```jsx
+   // Good: Independent sections that can stream separately
+   <Layout>
+     <Suspense fallback={<HeaderSkeleton />}>
+       <Header />
+     </Suspense>
+     <Suspense fallback={<MainContentSkeleton />}>
+       <MainContent />
+     </Suspense>
+     <Suspense fallback={<SidebarSkeleton />}>
+       <Sidebar />
+     </Suspense>
+   </Layout>
+
+   // Bad: Everything wrapped in a single Suspense boundary
+   <Suspense fallback={<FullPageSkeleton />}>
+     <Header />
+     <MainContent />
+     <Sidebar />
+   </Suspense>
+   ```
+
+2. **Data Loading Strategy**
+   - Prioritize critical data that should be included in the initial HTML
+   - Use streaming for supplementary data that can load progressively
+   - Consider implementing a waterfall strategy for dependent data

data/docs/troubleshooting.md

@@ -0,0 +1,24 @@
+# Troubleshooting
+
+## Invalid Token Workaround
+On June 27, 2024, tokens mysteriously did not work for a few hours. The problem resolved itself within a few hours.
+
+If you do see this problem, get in touch with the package maintainers via Slack. You can also message
+Justin Gordon at +1-808-281-7272.
+
+As an alternative to the token issue, if you have an account with access to the docs and this file, you can
+create a new token and follow these steps.
+
+To create a new token, visit https://github.com/settings/apps:
+1. Developer Settings
+2. Personal access tokens
+3. Tokens (classic)
+4. Generate a new token, classic
+5. 30-day expiration (to be safer)
+6. Repo privileges (not ideal) but shouldn't last long
+
+Then follow these steps to use your token:
+* [Ruby Gem](https://github.com/shakacode/react_on_rails_pro/blob/master/docs/installation.md#using-a-branch-in-your-gemfile)
+* [Node Package](https://github.com/shakacode/react_on_rails_pro/blob/master/docs/installation.md#instructions-for-using-a-branch)
+
+Note that this token gives `repo` access, so you want to revoke this token ASAP.

data/docs/updating.md

@@ -0,0 +1,219 @@
+# Upgrading React on Rails Pro
+
+## Upgrading from GitHub Packages to Public Distribution
+
+### Who This Guide is For
+
+This guide is for existing React on Rails Pro customers who are:
+
+- Currently using GitHub Packages authentication (private distribution)
+- On version 16.2.0-beta.x or earlier
+- Upgrading to version 16.2.0 or higher
+
+If you're a new customer, see [Installation](./installation.md) instead.
+
+### What's Changing
+
+React on Rails Pro packages are now **publicly distributed** via npmjs.org and RubyGems.org:
+
+- ✅ No more GitHub Personal Access Tokens (PATs)
+- ✅ No more `.npmrc` configuration
+- ✅ Simplified installation with standard `gem install` and `npm install`
+- ✅ License validation now happens at **runtime** using JWT tokens
+
+Package names have changed:
+
+- **Scoped** (old): `@shakacode-tools/react-on-rails-pro-node-renderer`
+- **Unscoped** (new): `react-on-rails-pro-node-renderer`
+
+### Your Current Setup (GitHub Packages)
+
+If you're upgrading, you currently have:
+
+**1. Gemfile with GitHub Packages source:**
+
+```ruby
+source "https://rubygems.pkg.github.com/shakacode-tools" do
+  gem "react_on_rails_pro", "16.1.1"
+end
+```
+
+**2. `.npmrc` file with GitHub authentication:**
+
+```
+always-auth=true
+//npm.pkg.github.com/:_authToken=YOUR_TOKEN
+@shakacode-tools:registry=https://npm.pkg.github.com
+```
+
+**3. Scoped package name in package.json:**
+
+```json
+{
+  "private": true,
+  "dependencies": {
+    "@shakacode-tools/react-on-rails-pro-node-renderer": "16.1.1"
+  }
+}
+```
+
+**4. Scoped require statements:**
+
+```javascript
+const { reactOnRailsProNodeRenderer } = require('@shakacode-tools/react-on-rails-pro-node-renderer');
+```
+
+### Migration Steps
+
+#### Step 1: Update Gemfile
+
+**Remove** the GitHub Packages source and use standard gem installation:
+
+```diff
+- source "https://rubygems.pkg.github.com/shakacode-tools" do
+-   gem "react_on_rails_pro", "16.1.1"
+- end
++ gem "react_on_rails_pro", "~> 16.2"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+#### Step 2: Remove .npmrc Configuration
+
+If you have a `.npmrc` file with GitHub Packages authentication, **delete it** or remove the GitHub-specific lines:
+
+```bash
+# Remove the entire file if it only contained GitHub Packages config
+rm .npmrc
+
+# Or edit it to remove these lines:
+# always-auth=true
+# //npm.pkg.github.com/:_authToken=YOUR_TOKEN
+# @shakacode-tools:registry=https://npm.pkg.github.com
+```
+
+#### Step 3: Update package.json
+
+Change the package name from **scoped** to **unscoped**:
+
+```diff
+{
+  "dependencies": {
+-   "@shakacode-tools/react-on-rails-pro-node-renderer": "16.1.1"
++   "react-on-rails-pro-node-renderer": "^16.2.0"
+  }
+}
+```
+
+Then reinstall:
+
+```bash
+npm install
+# or
+yarn install
+```
+
+#### Step 4: Update Require Statements
+
+Update all require/import statements to use the **unscoped** package name:
+
+**In your node renderer configuration file:**
+
+```diff
+- const { reactOnRailsProNodeRenderer } = require('@shakacode-tools/react-on-rails-pro-node-renderer');
++ const { reactOnRailsProNodeRenderer } = require('react-on-rails-pro-node-renderer');
+```
+
+**If using integrations (Sentry, Honeybadger):**
+
+```diff
+- require('@shakacode-tools/react-on-rails-pro-node-renderer/integrations/sentry').init();
++ require('react-on-rails-pro-node-renderer/integrations/sentry').init();
+
+- require('@shakacode-tools/react-on-rails-pro-node-renderer/integrations/honeybadger').init();
++ require('react-on-rails-pro-node-renderer/integrations/honeybadger').init();
+```
+
+#### Step 5: Configure License Token
+
+Add your React on Rails Pro license token as an environment variable:
+
+```bash
+export REACT_ON_RAILS_PRO_LICENSE="your-license-token-here"
+```
+
+**Or** configure it in your Rails initializer:
+
+```ruby
+# config/initializers/react_on_rails_pro.rb
+ReactOnRailsPro.configure do |config|
+  config.license_token = ENV["REACT_ON_RAILS_PRO_LICENSE"]
+end
+```
+
+⚠️ **Security Warning**: Never commit your license token to version control. Always use environment variables or secure secret management systems (Rails credentials, Heroku config vars, AWS Secrets Manager, etc.).
+
+**Where to get your license token:** Contact [justin@shakacode.com](mailto:justin@shakacode.com) if you don't have your license token.
+
+### Verify Migration
+
+#### 1. Verify Gem Installation
+
+```bash
+bundle list | grep react_on_rails_pro
+# Should show: react_on_rails_pro (16.2.0) or higher
+```
+
+#### 2. Verify NPM Package Installation
+
+```bash
+npm list react-on-rails-pro-node-renderer
+# or
+yarn list --pattern react-on-rails-pro-node-renderer
+
+# Should show: react-on-rails-pro-node-renderer@16.2.0 or higher
+```
+
+#### 3. Verify License Token
+
+Start your Rails server. You should see a success message in the logs:
+
+```
+React on Rails Pro license validated successfully
+```
+
+If the license is invalid or missing, you'll see an error with instructions.
+
+#### 4. Test Your Application
+
+- Start your Rails server
+- Start the node renderer (if using): `npm run node-renderer`
+- Verify that server-side rendering works correctly
+
+### Troubleshooting
+
+#### "Could not find gem 'react_on_rails_pro'"
+
+- Ensure you removed the GitHub Packages source from your Gemfile
+- Run `bundle install` again
+- Check that you have the correct version specified
+
+#### "Cannot find module 'react-on-rails-pro-node-renderer'"
+
+- Verify you updated all require statements to the unscoped name
+- Delete `node_modules` and reinstall: `rm -rf node_modules && npm install`
+- Check that package.json has the correct unscoped package name
+
+#### "License validation failed"
+
+- Ensure `REACT_ON_RAILS_PRO_LICENSE` environment variable is set
+- Verify the token string is correct (no extra spaces or quotes)
+- Contact [justin@shakacode.com](mailto:justin@shakacode.com) if you need a new token
+
+### Need Help?
+
+If you encounter issues during migration, contact [justin@shakacode.com](mailto:justin@shakacode.com) for support.

data/eslint.config.mjs

@@ -0,0 +1,220 @@
+import path from 'node:path';
+import { includeIgnoreFile } from '@eslint/compat';
+import js from '@eslint/js';
+import { FlatCompat } from '@eslint/eslintrc';
+import { defineConfig, globalIgnores } from 'eslint/config';
+import importPlugin from 'eslint-plugin-import';
+import jest from 'eslint-plugin-jest';
+import prettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import typescriptEslint from 'typescript-eslint';
+
+const compat = new FlatCompat({
+  baseDirectory: import.meta.dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default defineConfig([
+  includeIgnoreFile(path.resolve(import.meta.dirname, '.gitignore')),
+  globalIgnores([
+    'gen-documentation/',
+    'spec/react_on_rails/dummy-for-generators',
+    // includes some generated code
+    'spec/dummy/client/app/packs/server-bundle.js',
+    'packages/node-renderer/lib/',
+    'packages/node-renderer/tests/fixtures',
+    '**/node_modules/',
+    '**/assets/webpack/',
+    '**/generated/',
+    '**/app/assets/javascripts/application.js',
+    '**/coverage/',
+    '**/cable.js',
+    '**/public/',
+    '**/tmp/',
+    '**/vendor/',
+    '**/dist/',
+    '**/.yalc/',
+    '**/*.chunk.js',
+  ]),
+  {
+    files: ['**/*.[jt]s', '**/*.[cm][jt]s', '**/*.[jt]sx'],
+  },
+  js.configs.recommended,
+  compat.extends('eslint-config-shakacode'),
+  {
+    languageOptions: {
+      globals: globals.node,
+
+      parserOptions: {
+        // We have @babel/eslint-parser from eslint-config-shakacode, but don't use Babel in the main project
+        requireConfigFile: false,
+
+        babelOptions: {
+          presets: ['@babel/preset-env', '@babel/preset-react'],
+        },
+      },
+    },
+
+    settings: {
+      'import/extensions': ['.js', '.ts'],
+
+      'import/parsers': {
+        '@typescript-eslint/parser': ['.ts'],
+      },
+
+      'import/resolver': {
+        alias: [['Assets', './spec/dummy/client/app/assets']],
+        node: true,
+        typescript: true,
+      },
+    },
+
+    rules: {
+      'no-console': 'off',
+      'no-underscore-dangle': 'off',
+      'no-void': [
+        'error',
+        {
+          // Allow using void to suppress errors about misused promises
+          allowAsStatement: true,
+        },
+      ],
+
+      // Allow using void to suppress errors about misused promises
+      'no-restricted-syntax': 'off',
+      // https://github.com/benmosher/eslint-plugin-import/issues/340
+      'import/no-extraneous-dependencies': 'off',
+      'import/extensions': 'off',
+      'import/prefer-default-export': 'off',
+      'lines-between-class-members': [
+        'error',
+        {
+          enforce: [
+            { blankLine: 'always', prev: '*', next: '*' },
+            { blankLine: 'never', prev: 'field', next: 'field' },
+          ],
+        },
+      ],
+      'no-mixed-operators': 'off',
+      'react/forbid-prop-types': 'off',
+      'react/function-component-definition': [
+        'error',
+        {
+          namedComponents: ['function-declaration', 'arrow-function'],
+          unnamedComponents: 'arrow-function',
+        },
+      ],
+      'react/jsx-filename-extension': [
+        'error',
+        {
+          extensions: ['.jsx', '.tsx'],
+        },
+      ],
+      'react/jsx-props-no-spreading': [
+        'error',
+        {
+          custom: 'ignore',
+        },
+      ],
+      'react/prop-types': 'off',
+      'react/static-property-placement': 'off',
+    },
+  },
+  {
+    files: ['spec/dummy/**/*', 'spec/execjs-compatible-dummy'],
+    languageOptions: {
+      globals: globals.browser,
+    },
+  },
+  {
+    files: ['**/*.ts{x,}'],
+    extends: [importPlugin.flatConfigs.typescript, typescriptEslint.configs.strictTypeChecked],
+
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+      },
+    },
+
+    rules: {
+      '@typescript-eslint/restrict-template-expressions': 'off',
+
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+
+      '@typescript-eslint/no-floating-promises': [
+        'error',
+        {
+          allowForKnownSafePromises: [
+            {
+              from: 'package',
+              package: 'fastify',
+              name: 'FastifyReply',
+            },
+          ],
+        },
+      ],
+
+      'no-shadow': 'off',
+      '@typescript-eslint/no-shadow': 'error',
+    },
+  },
+  {
+    files: ['packages/node-renderer/tests/**', '**/*.test.{js,jsx,ts,tsx}'],
+
+    extends: [jest.configs['flat/recommended'], jest.configs['flat/style']],
+
+    rules: {
+      // Allows Jest mocks before import
+      'import/first': 'off',
+      'jest/no-disabled-tests': 'warn',
+      'jest/no-focused-tests': 'error',
+      'jest/no-identical-title': 'error',
+      'jest/prefer-to-have-length': 'warn',
+      'jest/valid-expect': 'error',
+      // Simplifies test code
+      '@typescript-eslint/no-non-null-assertion': 'off',
+    },
+  },
+  {
+    files: ['packages/node-renderer/src/integrations/**'],
+    ignores: ['packages/node-renderer/src/integrations/api.ts'],
+
+    rules: {
+      // Integrations should only use the public integration API
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: ['../*'],
+        },
+      ],
+    },
+  },
+  {
+    files: ['spec/dummy/e2e-tests/*'],
+
+    rules: {
+      'no-empty-pattern': [
+        'error',
+        {
+          allowObjectPatternsAsParameters: true,
+        },
+      ],
+    },
+  },
+  {
+    files: ['spec/dummy/e2e-tests/*'],
+    rules: {
+      'react-hooks/rules-of-hooks': ['off'],
+    },
+  },
+  // must be the last config in the array
+  // https://github.com/prettier/eslint-plugin-prettier?tab=readme-ov-file#configuration-new-eslintconfigjs
+  prettierRecommended,
+]);