Enhance ReactOnRails initialization and type safety

AbanoubGhadban · AbanoubGhadban · commit ba8dd1109744 · 2025-10-05T19:22:24.000+03:00
- Updated global declaration for ReactOnRails to allow undefined, improving type safety.
- Refactored createReactOnRails and createBaseClientObject functions to accept current global state for better caching and validation.
- Introduced type-safe specifications for core and Pro-specific functions, ensuring proper method overrides.
- Enhanced error handling for global object initialization, preventing conflicts with multiple runtime chunks.

These changes improve the robustness and maintainability of the React on Rails framework.
diff --git a/packages/react-on-rails-pro/src/ReactOnRails.client.ts b/packages/react-on-rails-pro/src/ReactOnRails.client.ts
@@ -13,9 +13,10 @@
  */
 
 import { createBaseClientObject } from 'react-on-rails/@internal/base/client';
-import { createReactOnRailsPro } from './createReactOnRailsPro.ts';
+import createReactOnRailsPro from './createReactOnRailsPro.ts';
 
-const ReactOnRails = createReactOnRailsPro(createBaseClientObject);
+const currentGlobal = globalThis.ReactOnRails || null;
+const ReactOnRails = createReactOnRailsPro(createBaseClientObject, currentGlobal);
 
 export * from 'react-on-rails/types';
 export default ReactOnRails;
diff --git a/packages/react-on-rails-pro/src/ReactOnRails.full.ts b/packages/react-on-rails-pro/src/ReactOnRails.full.ts
@@ -13,7 +13,7 @@
  */
 
 import { createBaseFullObject } from 'react-on-rails/@internal/base/full';
-import { createReactOnRailsPro } from './createReactOnRailsPro.ts';
+import createReactOnRailsPro from './createReactOnRailsPro.ts';
 
 // Warn about bundle size when included in browser bundles
 if (typeof window !== 'undefined') {
@@ -24,7 +24,8 @@ if (typeof window !== 'undefined') {
   );
 }
 
-const ReactOnRails = createReactOnRailsPro(createBaseFullObject);
+const currentGlobal = globalThis.ReactOnRails || null;
+const ReactOnRails = createReactOnRailsPro(createBaseFullObject, currentGlobal);
 
 export * from 'react-on-rails/types';
 export default ReactOnRails;
diff --git a/packages/react-on-rails-pro/src/ReactOnRails.node.ts b/packages/react-on-rails-pro/src/ReactOnRails.node.ts
@@ -16,6 +16,7 @@ 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';
diff --git a/packages/react-on-rails-pro/src/createReactOnRailsPro.ts b/packages/react-on-rails-pro/src/createReactOnRailsPro.ts
@@ -12,11 +12,11 @@
  * 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 { createBaseClientObject, type BaseClientObjectType } 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 type { ReactOnRailsInternal, RegisteredComponent, Store, StoreGenerator } from 'react-on-rails/types';
 import * as ProComponentRegistry from './ComponentRegistry.ts';
 import * as ProStoreRegistry from './StoreRegistry.ts';
 import {
@@ -31,6 +31,22 @@ import {
 
 type BaseObjectCreator = typeof createBaseClientObject | typeof createBaseFullObject;
 
+/**
+ * Pro-specific functions that override base/core stubs with real implementations.
+ * Typed explicitly to ensure type safety when mutating the base object.
+ */
+type ReactOnRailsProSpecificFunctions = Pick<
+  ReactOnRailsInternal,
+  | 'reactOnRailsPageLoaded'
+  | 'reactOnRailsComponentLoaded'
+  | 'getOrWaitForComponent'
+  | 'getOrWaitForStore'
+  | 'getOrWaitForStoreGenerator'
+  | 'reactOnRailsStoreLoaded'
+  | 'streamServerRenderedReactComponent'
+  | 'serverRenderRSCReactComponent'
+>;
+
 // Pro client startup with immediate hydration support
 async function reactOnRailsPageLoaded() {
   debugTurbolinks('reactOnRailsPageLoaded [PRO]');
@@ -62,19 +78,23 @@ function clientStartup() {
   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,
+export default function createReactOnRailsPro(
+  baseObjectCreator: BaseObjectCreator,
+  currentGlobal: BaseClientObjectType | null = null,
+): ReactOnRailsInternal {
+  // Create base object with Pro registries, passing currentGlobal for caching/validation
+  const baseObject = baseObjectCreator(
+    {
+      ComponentRegistry: ProComponentRegistry,
+      StoreRegistry: ProStoreRegistry,
+    },
+    currentGlobal,
+  );
 
-    // Override client-side rendering stubs with Pro implementations
+  // Define Pro-specific functions with proper types
+  // This object acts as a type-safe specification of what we're adding/overriding on the base object
+  const reactOnRailsProSpecificFunctions: ReactOnRailsProSpecificFunctions = {
+    // Override core implementations with Pro implementations
     reactOnRailsPageLoaded(): Promise<void> {
       return reactOnRailsPageLoaded();
     },
@@ -83,11 +103,7 @@ export function createReactOnRailsPro(baseObjectCreator: BaseObjectCreator) {
       return renderOrHydrateComponent(domId);
     },
 
-    // ===================================================================
-    // PRO-ONLY METHOD IMPLEMENTATIONS
-    // These methods don't exist in base, add them here
-    // ===================================================================
-
+    // Pro-only method implementations (override core stubs)
     getOrWaitForComponent(name: string): Promise<RegisteredComponent> {
       return ProComponentRegistry.getOrWaitForComponent(name);
     },
@@ -105,28 +121,42 @@ export function createReactOnRailsPro(baseObjectCreator: BaseObjectCreator) {
     },
 
     // 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 {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    streamServerRenderedReactComponent(): 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 {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serverRenderRSCReactComponent(): any {
       throw new Error('serverRenderRSCReactComponent is supported in RSC bundle only');
     },
   };
 
-  // Assign to global
-  globalThis.ReactOnRails = ReactOnRails;
+  // Type assertion is safe here because:
+  // 1. We start with BaseClientObjectType or BaseFullObjectType (from baseObjectCreator)
+  // 2. We add exactly the methods defined in ReactOnRailsProSpecificFunctions
+  // 3. ReactOnRailsInternal = Base + ReactOnRailsProSpecificFunctions
+  // TypeScript can't track the mutation, but we ensure type safety by explicitly typing
+  // the functions object above
+  const reactOnRailsPro = baseObject as unknown as ReactOnRailsInternal;
+
+  // Assign Pro-specific functions to the ReactOnRailsPro object using Object.assign
+  // This pattern ensures we add exactly what's defined in the type, nothing more, nothing less
+  Object.assign(reactOnRailsPro, reactOnRailsProSpecificFunctions);
 
-  // Reset options to defaults
-  ReactOnRails.resetOptions();
+  // Assign to global if not already assigned
+  if (!globalThis.ReactOnRails) {
+    globalThis.ReactOnRails = reactOnRailsPro;
 
-  // Run Pro client startup with immediate hydration support
-  clientStartup();
+    // Reset options to defaults (only on first initialization)
+    reactOnRailsPro.resetOptions();
+
+    // Run Pro client startup with immediate hydration support (only on first initialization)
+    clientStartup();
+  }
 
-  return ReactOnRails;
+  return reactOnRailsPro;
 }
diff --git a/packages/react-on-rails-pro/src/registerServerComponent/client.tsx b/packages/react-on-rails-pro/src/registerServerComponent/client.tsx
@@ -55,6 +55,7 @@ const registerServerComponent = (...componentNames: string[]) => {
       <RSCRoute componentName={name} componentProps={props} />
     ));
   }
+
   ReactOnRails.register(componentsWrappedInRSCRoute);
 };
 
diff --git a/packages/react-on-rails-pro/src/registerServerComponent/server.rsc.ts b/packages/react-on-rails-pro/src/registerServerComponent/server.rsc.ts
@@ -33,7 +33,8 @@ import { ReactComponent, RenderFunction } from 'react-on-rails/types';
  * });
  * ```
  */
-const registerServerComponent = (components: { [id: string]: ReactComponent | RenderFunction }) =>
+const registerServerComponent = (components: { [id: string]: ReactComponent | RenderFunction }) => {
   ReactOnRails.register(components);
+};
 
 export default registerServerComponent;
diff --git a/packages/react-on-rails-pro/src/registerServerComponent/server.tsx b/packages/react-on-rails-pro/src/registerServerComponent/server.tsx
@@ -43,6 +43,7 @@ const registerServerComponent = (components: Record<string, ReactComponent>) =>
       <RSCRoute componentName={componentName} componentProps={props} />
     ));
   }
+
   ReactOnRails.register(componentsWrappedInRSCRoute);
 };
 
diff --git a/packages/react-on-rails/src/ReactOnRails.client.ts b/packages/react-on-rails/src/ReactOnRails.client.ts
@@ -1,7 +1,8 @@
 import { createBaseClientObject } from './base/client.ts';
-import { createReactOnRails } from './createReactOnRails.ts';
+import createReactOnRails from './createReactOnRails.ts';
 
-const ReactOnRails = createReactOnRails(createBaseClientObject);
+const currentGlobal = globalThis.ReactOnRails || null;
+const ReactOnRails = createReactOnRails(createBaseClientObject, currentGlobal);
 
 export * from './types/index.ts';
 export default ReactOnRails;
diff --git a/packages/react-on-rails/src/ReactOnRails.full.ts b/packages/react-on-rails/src/ReactOnRails.full.ts
@@ -1,7 +1,8 @@
 import { createBaseFullObject } from './base/full.ts';
-import { createReactOnRails } from './createReactOnRails.ts';
+import createReactOnRails from './createReactOnRails.ts';
 
-const ReactOnRails = createReactOnRails(createBaseFullObject);
+const currentGlobal = globalThis.ReactOnRails || null;
+const ReactOnRails = createReactOnRails(createBaseFullObject, currentGlobal);
 
 export * from './types/index.ts';
 export default ReactOnRails;
diff --git a/packages/react-on-rails/src/ReactOnRails.node.ts b/packages/react-on-rails/src/ReactOnRails.node.ts
@@ -1,6 +1,7 @@
 import ReactOnRails from './ReactOnRails.full.ts';
 
 // Pro-only functionality - provide stub that directs users to upgrade
+
 ReactOnRails.streamServerRenderedReactComponent = () => {
   throw new Error('streamServerRenderedReactComponent requires react-on-rails-pro package');
 };
diff --git a/packages/react-on-rails/src/base/client.ts b/packages/react-on-rails/src/base/client.ts
@@ -7,6 +7,7 @@ import type {
   Store,
   StoreGenerator,
   ReactOnRailsOptions,
+  ReactOnRailsInternal,
 } from '../types/index.ts';
 import * as Authenticity from '../Authenticity.ts';
 import buildConsoleReplay from '../buildConsoleReplay.ts';
@@ -35,11 +36,82 @@ interface Registries {
   };
 }
 
-export function createBaseClientObject(registries: Registries) {
+/**
+ * Base client object type that includes all core ReactOnRails methods except Pro-specific ones.
+ * Derived from ReactOnRailsInternal by omitting Pro-only methods.
+ */
+export type BaseClientObjectType = Omit<
+  ReactOnRailsInternal,
+  // Pro-only methods (not in base)
+  | 'getOrWaitForComponent'
+  | 'getOrWaitForStore'
+  | 'getOrWaitForStoreGenerator'
+  | 'reactOnRailsStoreLoaded'
+  | 'streamServerRenderedReactComponent'
+  | 'serverRenderRSCReactComponent'
+>;
+
+// Cache to track created objects and their registries
+let cachedObject: BaseClientObjectType | null = null;
+let cachedRegistries: Registries | null = null;
+
+export function createBaseClientObject(
+  registries: Registries,
+  currentObject: BaseClientObjectType | null = null,
+): BaseClientObjectType {
   const { ComponentRegistry, StoreRegistry } = registries;
 
-  return {
+  // Error detection: currentObject is null but we have a cached object
+  // This indicates webpack misconfiguration (multiple runtime chunks)
+  if (currentObject === null && cachedObject !== null) {
+    throw new Error(`\
+ReactOnRails was already initialized, but a new initialization was attempted without passing the existing global.
+This usually means Webpack's optimization.runtimeChunk is set to "true" or "multiple" instead of "single".
+
+Fix: Set optimization.runtimeChunk to "single" in your webpack configuration.
+See: https://github.com/shakacode/react_on_rails/issues/1558`);
+  }
+
+  // Error detection: currentObject exists but doesn't match cached object
+  // This could indicate:
+  // 1. Global was contaminated by external code
+  // 2. Mixing core and pro packages
+  if (currentObject !== null && cachedObject !== null && currentObject !== cachedObject) {
+    throw new Error(`\
+ReactOnRails global object mismatch detected.
+The current global ReactOnRails object is different from the one created by this package.
+
+This usually means:
+1. You're mixing react-on-rails (core) with react-on-rails-pro
+2. Another library is interfering with the global ReactOnRails object
+
+Fix: Use only one package (core OR pro) consistently throughout your application.`);
+  }
+
+  // Error detection: Different registries with existing cache
+  // This indicates mixing core and pro packages
+  if (cachedRegistries !== null) {
+    if (
+      registries.ComponentRegistry !== cachedRegistries.ComponentRegistry ||
+      registries.StoreRegistry !== cachedRegistries.StoreRegistry
+    ) {
+      throw new Error(`\
+Cannot mix react-on-rails (core) with react-on-rails-pro.
+Different registries detected - the packages use incompatible registries.
+
+Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
+    }
+  }
+
+  // If we have a cached object, return it (all checks passed above)
+  if (cachedObject !== null) {
+    return cachedObject;
+  }
+
+  // Create and return new object
+  const obj = {
     options: {} as Partial<ReactOnRailsOptions>,
+    isRSCBundle: false,
 
     // ===================================================================
     // STABLE METHOD IMPLEMENTATIONS - Core package implementations
@@ -167,8 +239,8 @@ export function createBaseClientObject(registries: Registries) {
       );
     },
 
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    reactOnRailsComponentLoaded(_domId: string): Promise<void> {
+    reactOnRailsComponentLoaded(domId: string): Promise<void> {
+      void domId; // Mark as used
       throw new Error(
         'ReactOnRails.reactOnRailsComponentLoaded is not initialized. This is a bug in react-on-rails.',
       );
@@ -178,24 +250,26 @@ export function createBaseClientObject(registries: Registries) {
     // SSR STUBS - Will throw errors in client bundle, overridden in full
     // ===================================================================
 
-    serverRenderReactComponent(): never {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serverRenderReactComponent(...args: any[]): any {
+      void args; // Mark as used
       throw new Error(
         'serverRenderReactComponent is not available in "react-on-rails/client". Import "react-on-rails" server-side.',
       );
     },
 
-    handleError(): never {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handleError(...args: any[]): any {
+      void args; // Mark as used
       throw new Error(
         'handleError is not available in "react-on-rails/client". Import "react-on-rails" server-side.',
       );
     },
+  };
 
-    // ===================================================================
-    // FLAGS
-    // ===================================================================
+  // Cache the object and registries
+  cachedObject = obj;
+  cachedRegistries = registries;
 
-    isRSCBundle: false,
-  };
+  return obj;
 }
-
-export type BaseClientObjectType = ReturnType<typeof createBaseClientObject>;
diff --git a/packages/react-on-rails/src/base/full.ts b/packages/react-on-rails/src/base/full.ts
diff --git a/packages/react-on-rails/src/context.ts b/packages/react-on-rails/src/context.ts
diff --git a/packages/react-on-rails/src/createReactOnRails.ts b/packages/react-on-rails/src/createReactOnRails.ts
diff --git a/packages/react-on-rails/src/serverRenderReactComponent.ts b/packages/react-on-rails/src/serverRenderReactComponent.ts
diff --git a/packages/react-on-rails/src/types/index.ts b/packages/react-on-rails/src/types/index.ts

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,7 @@ const registerServerComponent = (...componentNames: string[]) => {`
`55`	`55`	`<RSCRoute componentName={name} componentProps={props} />`
`56`	`56`	`));`
`57`	`57`	`}`
	`58`	`+`
`58`	`59`	`ReactOnRails.register(componentsWrappedInRSCRoute);`
`59`	`60`	`};`
`60`	`61`
Original file line number	Diff line number	Diff line change
`@@ -43,6 +43,7 @@ const registerServerComponent = (components: Record<string, ReactComponent>) =>`
`43`	`43`	`<RSCRoute componentName={componentName} componentProps={props} />`
`44`	`44`	`));`
`45`	`45`	`}`
	`46`	`+`
`46`	`47`	`ReactOnRails.register(componentsWrappedInRSCRoute);`
`47`	`48`	`};`
`48`	`49`