Why doesn't React on Rails hydrate at the DOMContentLoaded event?

[kotarella1110]

In React on Rails, hydration and rendering sometimes occur at the load event. This happens because of the current implementation of the onPageReady function.

react_on_rails/node_package/src/clientStartup.ts

Lines 310 to 337 in 4339d30

	function onPageReady(callback: () => void) {
	if (document.readyState === "complete") {
	callback();
	} else {
	document.addEventListener("readystatechange", function onReadyStateChange() {
	onPageReady(callback);
	document.removeEventListener("readystatechange", onReadyStateChange);
	});
	}
	}
	export function clientStartup(context: Context): void {
	// Check if server rendering
	if (!isWindow(context)) {
	return;
	}
	// Tried with a file local variable, but the install handler gets called twice.
	// eslint-disable-next-line no-underscore-dangle
	if (context.__REACT_ON_RAILS_EVENT_HANDLERS_RAN_ONCE__) {
	return;
	}
	// eslint-disable-next-line no-underscore-dangle, no-param-reassign
	context.__REACT_ON_RAILS_EVENT_HANDLERS_RAN_ONCE__ = true;
	onPageReady(renderInit);
	}

If clientStartup is executed when readyState is loading, hydration occurs at the interactive state (DOMContentLoaded event). However, if clientStartup runs when readyState is already interactive, hydration is delayed until the complete state (load event). => When clientStartup is executed, hydration always occurs when readyState is complete.

This behavior causes hydration to wait until all sub-resources, such as third-party JavaScript or Google Fonts, are fully loaded, potentially delaying the user’s interaction readiness.

Would it be possible to allow hydration at the DOMContentLoaded event when the readyState is already interactive? For example, the following update to onPageReady could address this:

function onPageReady(callback: () => void) {
- if (document.readyState === "complete") {
+ if (document.readyState !== "loading") {
    callback();
  } else {
    document.addEventListener("readystatechange", function onReadyStateChange() { 
      onPageReady(callback); 
      document.removeEventListener("readystatechange", onReadyStateChange); 
    });
  }
}

This adjustment ensures hydration begins as soon as the DOMContentLoaded event fires, even if clientStartup is executed after the interactive state.

Are there any reasons or side effects that might prevent this change from being implemented? If this approach is acceptable, I’d be happy to submit a PR for it.

[alexeyr]

As it happens, I was looking into this as well.

It used to be on DOMContentLoaded, but was switched to load: #1540, mentioning an issue with DOMContentLoaded was revealed in #1539.

And that mentions 7b301f9 which changed it the other way around earlier...

@Judahmeek @justin808 Do you remember what exactly "the race condition revealed by #1539" was? And was the intention actually "after DOMContentLoaded" or "on load"?

If clientStartup is executed when readyState is loading, hydration occurs at the interactive state (DOMContentLoaded event).

I don't think that's correct; when the state changes to interactive, it just adds onReadyStateChange as a listener again, and the callback will only run when it's complete.

[kotarella1110]

Additionally, I’d like to understand the reasoning behind changing the hydration timing from the DOMContentLoaded event to the load event. I understand that this was related to addressing a race condition, but could you share more details about the specific issues that arose?

[Judahmeek]

@kotarella1110 the problem is that the DOMContentLoaded event fires once the HTML document has been loaded, but before all sub-resources, such as the react components in the webpack bundles, have been loaded. Which meant that relying on the DOMContentLoaded event could cause ReactOnRails to try to initialize before all the react components had been registered, which would then cause a fatal error.

The load event only fires once all sub-resources have been loaded.

[kotarella1110]

Does my understanding align with the problem description that renderInit might execute before ReactOnRails.register is completed?

If so, could this issue be resolved by ensuring renderInit waits for ReactOnRails.register to finish? Below is a sample implementation using a Deferred mechanism:

// node_package/src/Deferred.ts
export class Deferred<T> {
  promise: Promise<T>;
  resolve!: (value: T | PromiseLike<T>) => void;
  reject!: (reason?: any) => void;

  constructor() {
    this.promise = new Promise((resolve, reject) => {
      this.resolve = resolve;
      this.reject = reject;
    });
  }
}

// node_package/src/reactOnRailsRenderedDefer.ts
import { Deferred } from './Deferred';

export const reactOnRailsRenderedDefer = new Deferred<void>();

// node_package/src/ReactOnRails.ts
import { reactOnRailsRenderedDefer } from './reactOnRailsRenderedDefer';
// ...
ctx.ReactOnRails = {
  // ...
  register(components: { [id: string]: ReactComponentOrRenderFunction }): void {
    ComponentRegistry.register(components);
    reactOnRailsRenderedDefer.resolve();
  },
  // ...
};

// node_package/src/clientStartup.ts
import { reactOnRailsRenderedDefer } from './reactOnRailsRenderedDefer';
// ...
async function renderInit(): Promise<void> {
  await reactOnRailsRenderedDefer.promise;
  // Install listeners when running on the client (browser).
  // We must do this check for turbolinks AFTER the document is loaded because we load the
  // Webpack bundles first.
  if ((!turbolinksInstalled() || !turbolinksSupported()) && !turboInstalled()) {
    debugTurbolinks('NOT USING TURBOLINKS: calling reactOnRailsPageLoaded');
    reactOnRailsPageLoaded();
    return;
  }
  // ...
}
// ...
function onPageReady(callback: () => void) {
  if (document.readyState !== "loading") {
    callback();
  } else {
    document.addEventListener("DOMContentLoaded", callback);
  }
}
// ...

This implementation leverages a Deferred object to ensure renderInit waits until all components are registered through ReactOnRails.register. Could this approach address the issue effectively?

[AbanoubGhadban]

@kotarella1110 We already implemented an approach similar to your approach here #1656. The PR will be merged very soon. But for backward compatibility, you need to pass force_load: true on the server side for any component you want to hydrate immediately.