From 1b418a6481c8c1477ca8d169481cb6b26129d171 Mon Sep 17 00:00:00 2001 From: Alan Date: Tue, 21 Dec 2021 09:16:34 -0800 Subject: [PATCH] Improve wording in documentation for `client:*` directives (#2232) * Make wording around `client:*` directives more clear A friend and I both found the wording on this page to be a touch ambiguous. When does the renderer JS download? Does Astro really delay all JS downloading until the component is ready to be hydrated, or just the component JS? I think these changes make the behavior crystal clear? * Make tense consistent for `client:only` --- .../src/pages/core-concepts/component-hydration.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/src/pages/core-concepts/component-hydration.md b/docs/src/pages/core-concepts/component-hydration.md index 60ea26fd7d..8abb790e89 100644 --- a/docs/src/pages/core-concepts/component-hydration.md +++ b/docs/src/pages/core-concepts/component-hydration.md @@ -62,29 +62,31 @@ Astro renders every component on the server **at build time**, unless [client:on import MyReactComponent from '../components/MyReactComponent.jsx'; --- + JavaScript for the component until it becomes visible in the + user's browser. --> ``` +Note that the renderer JS (e.g. React) and the component's CSS are downloaded with the page. The `client:*` directives only dictate when the component JS is imported and when the component is hydrated. ### `` -Hydrate the component on page load. +Start importing the component JS at page load. Hydrate the component when import completes. ### `` -Hydrate the component as soon as main thread is free (uses [requestIdleCallback()][mdn-ric]). +Start importing the component JS as soon as main thread is free (uses [requestIdleCallback()][mdn-ric]). Hydrate the component when import completes. ### `` -Hydrate the component as soon as the element enters the viewport (uses [IntersectionObserver][mdn-io]). Useful for content lower down on the page. +Start importing the component JS as soon as the element enters the viewport (uses [IntersectionObserver][mdn-io]). Hydrate the component when import completes. Useful for content lower down on the page. ### `` -Hydrate the component as soon as the browser matches the given media query (uses [matchMedia][mdn-mm]). Useful for sidebar toggles, or other elements that should only display on mobile or desktop devices. +Start importing the component JS as soon as the browser matches the given media query (uses [matchMedia][mdn-mm]). Hydrate the component when import completes. Useful for sidebar toggles, or other elements that should only display on mobile or desktop devices. ### `` -Hydrates the component at page load, similar to `client:load`. The component will be **skipped** at build time, useful for components that are entirely dependent on client-side APIs. This is best avoided unless absolutely needed, in most cases it is best to render placeholder content on the server and delay any browser API calls until the component hydrates in the browser. +Start importing the component JS at page load and hydrate when the import completes, similar to `client:load`. The component will be **skipped** at build time, useful for components that are entirely dependent on client-side APIs. This is best avoided unless absolutely needed, in most cases it is best to render placeholder content on the server and delay any browser API calls until the component hydrates in the browser. If more than one renderer is included in the Astro [config](/reference/configuration-reference), `client:only` needs a hint to know which renderer to use for the component. For example, `client:only="react"` would make sure that the component is hydrated in the browser with the React renderer. For custom renderers not provided by `@astrojs`, use the full name of the renderer provided in your Astro config, i.e. ``.