[Docs]: Mention need to synchronously render the app

[jukben]

Describe what's incorrect/missing in the documentation

Hi there!

While implementing the data router in our company, we encountered an issue where the router occasionally failed to load a component, resulting in a blank screen. Upon investigating, I found that the RouterProvider subscribes to the routing state.

In our case, it sometimes happened that the loaders finished their execution before the RouterProvider had subscribed. This caused the router state to be out of sync basically in initialized: false state rendering blank screen.

This behavior raises a broader question about whether this approach is robust enough, especially given the asynchronous nature of concurrent React. While this may not necessarily be a bug in the router itself, I feel the current documentation for RouterProvider could benefit from addressing this edge case to prevent confusion for developers. (It would have saved me a couple of hours—it was tough to debug since the race condition only happened in production without dev tools enabled 😅.)

Proposed Documentation Update:

Add a note about the subscription mechanism and potential pitfalls when loaders complete before RouterProvider subscribes.
Provide guidance regarding flushSync workaround.

References:

I also raised a similar issue on the react.dev documentation: React Issue #7317. While that focuses on React’s perspective, I believe React Router documentation should also address this from the router's perspective.

Next Steps:

I'm happy to help drive this forward once we align on the best way to proceed. Let me know what you think!