Skip to content

Commit 46c13ee

Browse files
thePunderWomanAndrewKushnir
authored andcommitted
docs: add anti-patterns and notes about 3rd party scripts (angular#59210)
Some users are confused by the requirements of hydration around DOM manipulation, and this adds some clarity around those requirements. PR Close angular#59210
1 parent 241416e commit 46c13ee

1 file changed

Lines changed: 13 additions & 1 deletion

File tree

adev/src/content/guide/hydration.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,11 +99,12 @@ As an example, here are some of the most common cases of this issue.
9999

100100
- `<table>` without a `<tbody>`
101101
- `<div>` inside a `<p>`
102-
- `<a>` inside an `<h1>`
103102
- `<a>` inside another `<a>`
104103

105104
If you are uncertain about whether your HTML is valid, you can use a [syntax validator](https://validator.w3.org/) to check it.
106105

106+
Note: While the HTML standard does not require the `<tbody>` element inside tables, modern browsers automatically create a `<tbody>` element in tables that do not declare one. Because of this inconsistency, always explicitly declare a `<tbody>` element in tables to avoid hydration errors.
107+
107108
### Preserve Whitespaces Configuration
108109

109110
When using the hydration feature, we recommend using the default setting of `false` for `preserveWhitespaces`. If this setting is not in your tsconfig, the value will be `false` and no changes are required. If you choose to enable preserving whitespaces by adding `preserveWhitespaces: true` to your tsconfig, it is possible you may encounter issues with hydration. This is not yet a fully supported configuration.
@@ -150,6 +151,10 @@ The `ngSkipHydration` attribute can only be used on component host nodes. Angula
150151

151152
Keep in mind that adding the `ngSkipHydration` attribute to your root application component would effectively disable hydration for your entire application. Be careful and thoughtful about using this attribute. It is intended as a last resort workaround. Components that break hydration should be considered bugs that need to be fixed.
152153

154+
## Hydration Timing and Application Stability
155+
156+
Application stability is an important part of the hydration process. Hydration and any post-hydration processes only occur once the application has reported stability. There are a number of ways that stability can be delayed. Examples include setting timeouts and intervals, unresolved promises, and pending microtasks. In those cases, you may encounter the [Application remains unstable](errors/NG0506) error, which indicates that your app has not yet reached the stable state after 10 seconds. If you're finding that your application is not hydrating right away, take a look at what is impacting application stability and refactor to avoid causing these delays.
157+
153158
## I18N
154159

155160
HELPFUL: Support for internationalization with hydration is currently in [developer preview](/reference/releases#developer-preview). By default, Angular will skip hydration for components that use i18n blocks, effectively re-rendering those components from scratch.
@@ -169,10 +174,17 @@ bootstrapApplication(AppComponent, {
169174
});
170175
```
171176

177+
## Consistent rendering across server-side and client-side
178+
Avoid introducing `@if` blocks and other conditionals that display different content when server-side rendering than client-side rendering, such as using an `@if` block with Angular's `isPlatformBrowser` function. These rendering differences cause layout shifts, negatively impacting end-user experience and core web vitals.
179+
172180
## Third Party Libraries with DOM Manipulation
173181

174182
There are a number of third party libraries that depend on DOM manipulation to be able to render. D3 charts is a prime example. These libraries worked without hydration, but they may cause DOM mismatch errors when hydration is enabled. For now, if you encounter DOM mismatch errors using one of these libraries, you can add the `ngSkipHydration` attribute to the component that renders using that library.
175183

184+
## Third Party Scripts with DOM Manipulation
185+
186+
Many third party scripts, such as ad trackers and analytics, modify the DOM before hydration can occur. These scripts may cause hydration errors because the page no longer matches the structure expected by Angular. Prefer deferring this type of script until after hydration whenever possible. Consider using [`AfterNextRender`](api/core/afterNextRender) to delay the script until post-hydration processes have occured.
187+
176188
## Incremental Hydration
177189

178190
Incremental hydration is an advanced form of hydration that allows for more granular control over when hydration happens. See the [incremental hydration guide](guide/incremental-hydration) for more information.

0 commit comments

Comments
 (0)