Refactor React on Rails package structure and enhance functionality

- Consolidated entry points in the knip configuration for both react-on-rails and react-on-rails-pro packages, improving project organization.
- Introduced new base client and full objects to streamline the creation of ReactOnRails instances, enhancing code maintainability.
- Added new methods for server-side rendering and component hydration in the Pro package, expanding functionality.
- Updated package.json files to reflect new exports and improve module resolution.

These changes enhance the overall structure and capabilities of the React on Rails framework.

Author: AbanoubGhadban

knip.ts

@@ -39,9 +39,7 @@ const config: KnipConfig = {
 
     // React on Rails core package workspace
     'packages/react-on-rails': {
-      entry: [
-        'src/ReactOnRails.node.ts!',
-      ],
+      entry: ['src/ReactOnRails.node.ts!'],
       project: ['src/**/*.[jt]s{x,}!', 'tests/**/*.[jt]s{x,}', '!lib/**'],
       ignore: [
         // Jest setup and test utilities - not detected by Jest plugin in workspace setup
@@ -54,6 +52,9 @@ const config: KnipConfig = {
     // React on Rails Pro package workspace
     'packages/react-on-rails-pro': {
       entry: [
+        'src/ReactOnRails.node.ts!',
+        'src/ReactOnRails.full.ts!',
+        'src/ReactOnRails.client.ts!',
         'src/index.ts!',
         'src/ReactOnRailsRSC.ts!',
         'src/registerServerComponent/client.tsx!',

packages/react-on-rails-pro/package.json

@@ -30,7 +30,14 @@
   "author": "[email protected]",
   "license": "UNLICENSED",
   "exports": {
-    ".": "./lib/index.js",
+    ".": {
+      "node": "./lib/ReactOnRails.node.js",
+      "default": "./lib/ReactOnRails.full.js"
+    },
+    "./client": "./lib/ReactOnRails.client.js",
+    "./ReactOnRails.client": "./lib/ReactOnRails.client.js",
+    "./ReactOnRails.full": "./lib/ReactOnRails.full.js",
+    "./ReactOnRails.node": "./lib/ReactOnRails.node.js",
     "./registerServerComponent/client": "./lib/registerServerComponent/client.js",
     "./registerServerComponent/server": {
       "react-server": "./lib/registerServerComponent/server.rsc.js",

packages/react-on-rails-pro/src/ReactOnRails.client.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+
+import { createBaseClientObject } from 'react-on-rails/@internal/base/client';
+import { createReactOnRailsPro } from './createReactOnRailsPro.ts';
+
+const ReactOnRails = createReactOnRailsPro(createBaseClientObject);
+
+export * from 'react-on-rails/types';
+export default ReactOnRails;

packages/react-on-rails-pro/src/ReactOnRails.full.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+
+import { createBaseFullObject } from 'react-on-rails/@internal/base/full';
+import { createReactOnRailsPro } from './createReactOnRailsPro.ts';
+
+// Warn about bundle size when included in browser bundles
+if (typeof window !== 'undefined') {
+  console.warn(
+    'Optimization opportunity: "react-on-rails-pro" includes ~14KB of server-rendering code. ' +
+      'Browsers may not need it. See https://forum.shakacode.com/t/how-to-use-different-versions-of-a-file-for-client-and-server-rendering/1352 ' +
+      '(Requires creating a free account). Click this for the stack trace.',
+  );
+}
+
+const ReactOnRails = createReactOnRailsPro(createBaseFullObject);
+
+export * from 'react-on-rails/types';
+export default ReactOnRails;

packages/react-on-rails-pro/src/ReactOnRails.node.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+
+import ReactOnRails from './ReactOnRails.full.ts';
+import streamServerRenderedReactComponent from './streamServerRenderedReactComponent.ts';
+
+// Add Pro server-side streaming functionality
+ReactOnRails.streamServerRenderedReactComponent = streamServerRenderedReactComponent;
+
+export * from './ReactOnRails.full.ts';
+// eslint-disable-next-line no-restricted-exports -- see https://github.com/eslint/eslint/issues/15617
+export { default } from './ReactOnRails.full.ts';

packages/react-on-rails-pro/src/ReactOnRailsRSC.ts

@@ -22,9 +22,9 @@ import {
   StreamRenderState,
   StreamableComponentResult,
 } from 'react-on-rails/types';
-import ReactOnRails from 'react-on-rails/ReactOnRails.full';
 import handleError from 'react-on-rails/handleError';
 import { convertToError } from 'react-on-rails/serverRenderUtils';
+import ReactOnRails from './ReactOnRails.full.ts';
 
 import {
   streamServerRenderedComponent,

packages/react-on-rails-pro/src/createReactOnRailsPro.ts

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+
+import { createBaseClientObject } from 'react-on-rails/@internal/base/client';
+import { createBaseFullObject } from 'react-on-rails/@internal/base/full';
+import { onPageLoaded, onPageUnloaded } from 'react-on-rails/pageLifecycle';
+import { debugTurbolinks } from 'react-on-rails/turbolinksUtils';
+import type { Store, StoreGenerator, RegisteredComponent } from 'react-on-rails/types';
+import * as ProComponentRegistry from './ComponentRegistry.ts';
+import * as ProStoreRegistry from './StoreRegistry.ts';
+import {
+  renderOrHydrateComponent,
+  hydrateStore,
+  renderOrHydrateAllComponents,
+  hydrateAllStores,
+  renderOrHydrateImmediateHydratedComponents,
+  hydrateImmediateHydratedStores,
+  unmountAll,
+} from './ClientSideRenderer.ts';
+
+type BaseObjectCreator = typeof createBaseClientObject | typeof createBaseFullObject;
+
+// Pro client startup with immediate hydration support
+async function reactOnRailsPageLoaded() {
+  debugTurbolinks('reactOnRailsPageLoaded [PRO]');
+  await Promise.all([hydrateAllStores(), renderOrHydrateAllComponents()]);
+}
+
+function reactOnRailsPageUnloaded(): void {
+  debugTurbolinks('reactOnRailsPageUnloaded [PRO]');
+  unmountAll();
+}
+
+function clientStartup() {
+  if (globalThis.document === undefined) {
+    return;
+  }
+
+  // eslint-disable-next-line no-underscore-dangle
+  if (globalThis.__REACT_ON_RAILS_EVENT_HANDLERS_RAN_ONCE__) {
+    return;
+  }
+
+  // eslint-disable-next-line no-underscore-dangle
+  globalThis.__REACT_ON_RAILS_EVENT_HANDLERS_RAN_ONCE__ = true;
+
+  void renderOrHydrateImmediateHydratedComponents();
+  void hydrateImmediateHydratedStores();
+
+  onPageLoaded(reactOnRailsPageLoaded);
+  onPageUnloaded(reactOnRailsPageUnloaded);
+}
+
+// eslint-disable-next-line import/prefer-default-export
+export function createReactOnRailsPro(baseObjectCreator: BaseObjectCreator) {
+  // Create base object with Pro registries
+  const baseObject = baseObjectCreator({
+    ComponentRegistry: ProComponentRegistry,
+    StoreRegistry: ProStoreRegistry,
+  });
+
+  // Add Pro-specific implementations
+  const ReactOnRails = {
+    ...baseObject,
+
+    // Override client-side rendering stubs with Pro implementations
+    reactOnRailsPageLoaded(): Promise<void> {
+      return reactOnRailsPageLoaded();
+    },
+
+    reactOnRailsComponentLoaded(domId: string): Promise<void> {
+      return renderOrHydrateComponent(domId);
+    },
+
+    // ===================================================================
+    // PRO-ONLY METHOD IMPLEMENTATIONS
+    // These methods don't exist in base, add them here
+    // ===================================================================
+
+    getOrWaitForComponent(name: string): Promise<RegisteredComponent> {
+      return ProComponentRegistry.getOrWaitForComponent(name);
+    },
+
+    getOrWaitForStore(name: string): Promise<Store> {
+      return ProStoreRegistry.getOrWaitForStore(name);
+    },
+
+    getOrWaitForStoreGenerator(name: string): Promise<StoreGenerator> {
+      return ProStoreRegistry.getOrWaitForStoreGenerator(name);
+    },
+
+    reactOnRailsStoreLoaded(storeName: string): Promise<void> {
+      return hydrateStore(storeName);
+    },
+
+    // streamServerRenderedReactComponent is added in ReactOnRails.node.ts
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+    streamServerRenderedReactComponent(..._args: any[]): any {
+      throw new Error(
+        'streamServerRenderedReactComponent requires importing from react-on-rails-pro in Node.js environment',
+      );
+    },
+
+    // serverRenderRSCReactComponent is added in ReactOnRailsRSC.ts
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+    serverRenderRSCReactComponent(..._args: any[]): any {
+      throw new Error('serverRenderRSCReactComponent is supported in RSC bundle only');
+    },
+  };
+
+  // Assign to global
+  globalThis.ReactOnRails = ReactOnRails;
+
+  // Reset options to defaults
+  ReactOnRails.resetOptions();
+
+  // Run Pro client startup with immediate hydration support
+  clientStartup();
+
+  return ReactOnRails;
+}