docs: describe importance of enabledBlocking #46979
Conversation
AndrewKushnir
added
action: review
|
|
||
| When the page is loaded in the browser, Angular will bootstrap as usual and replace the content of the DOM. This process is called hydration. | ||
| This hydration process can cause some flicker _(specially for lazy loaded routes)_. In order to avoid the flicker, it is recommended to set the [`initialNavigation`](https://angular.io/api/router/InitialNavigation) option to `enabledBlocking` when using Server-Side Rendering. | ||
| Using this option, Angular will wait for the route to be loaded before bootstrapping and hydrating. |
There was a problem hiding this comment.
My understanding is that the NgUniversal schematic patches the AppRoutingModule with the initialNavigation: 'enabledBlocking'. If so, we can mention it and recommend adding the initialNavigation for custom setups.
// cc @alan-agius4
There was a problem hiding this comment.
That is correct @AndrewKushnir.
The term hydration here might be misleading as Angular doesn’t re-hydrate the application.
There was a problem hiding this comment.
My understanding is that the NgUniversal schematic patches the
AppRoutingModulewith theinitialNavigation: 'enabledBlocking'. If so, we can mention it and recommend adding theinitialNavigationfor custom setups.// cc @alan-agius4
Oh! Do you know since when this is enabled? I used Universal schematic for the setup on Angular 10 or 11.
Also, this will happen even more frequently with standalone setups... until the schematic takes them into account.
There was a problem hiding this comment.
That is correct @AndrewKushnir.
The term hydration here might be misleading as Angular doesn’t re-hydrate the application.
Agreed about the misuse of "hydration". Should we talk about "initial rendering"?
There was a problem hiding this comment.
Oh! Do you know since when this is enabled? I used Universal schematic for the setup on Angular 10 or 11.
Also, this will happen even more frequently with standalone setups... until the schematic takes them into account.
Universal doesn't support standalone at the moment.
There was a problem hiding this comment.
I think rerendering is good here.
Should I replace "hydration" with "rerendering" so we can merge this?
There was a problem hiding this comment.
@yjaaidi I think we can rephrase this as a router configuration and drop "hydration", here is the proposed content:
==============
Configure Router
To ensure routing is finished before the server serializes the page content, NgUniversal updates the RouterModule.forRoot call in your application and adds the initialNavigation: 'enabledBlocking' as a config option. This config option also ensures that client-side navigation completes before the application bootstraps in the browser, which allows the page to retain the server-side rendered content until the application is fully rendered.
If you use a custom setup and/or renderModule directly, update the Router configuration manually.
If you use the RouterModule.forRoot, include the initialNavigation option.
RouterModule.forRoot(routes, {initialNavigation: 'enabledBlocking'});
If you use the provideRouter API, add the withEnabledBlockingInitialNavigation function call.
provideRouter(routes, withEnabledBlockingInitialNavigation());
==============
What do you think?
There was a problem hiding this comment.
Hey @AndrewKushnir ! Sorry for getting back to you so late.
I was off for a while and now I'm catching up 😅
I like your suggestion. Let's go ahead.
Would you want me to update my PR with it?
There was a problem hiding this comment.
Hey @yjaaidi, no problem!
With the upcoming non-destructive hydration and some changes that we've made in the platform-server, the enabledBlockingInitialNavigation option would no longer be required. I think at this point we can just leave the docs as is (i.e. close this PR) and we'll eventually deprecate the enabledBlockingInitialNavigation once the non-destructive hydration exits the developer preview mode.
There was a problem hiding this comment.
Perfect! Let's do that.
Sorry for the noise then 😅
|
This issue has been automatically locked due to inactivity. Read more about our automatic conversation locking policy. This action has been performed automatically by a bot. |
4 participants
PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
What is the current behavior?
Issue Number: N/A
What is the new behavior?
Does this PR introduce a breaking change?
Other information