Add support for `client:only` hydrator (#935)

* Adding support for client:only hydration

* Adding documentation for client:only

* Adding changeset

* Updating the test to use a browser-only API

* Adding a browser-specific import script, this reproduces the issue where client:only imports must be removed

* typo fix

* removing mispelled test component

* WIP: delaying inclusion of component imports until the hydration method is known

* WIP: tweaking the test to use window instead of document

* When only one renderer is included, use that for client:only hydration

* temporary test script snuck into the last commit

* WIP: adding check for a client:only renderer hint

* refactor: Remove client:only components instead of delaying all component import statements

* Updating the changeset and docs for the renderer hint

* refactor: pull client:only render matching out to it's own function

* Updating renderer hinting to match full name, with shorthand for internal renderers

Co-authored-by: Tony Sullivan <tony.f.sullivan@gmail.com>

1 files changed, 7 insertions, 1 deletions

diff --git a/docs/src/pages/core-concepts/component-hydration.md b/docs/src/pages/core-concepts/component-hydration.md
index ed2ab453d..bb0fbce29 100644
--- a/docs/src/pages/core-concepts/component-hydration.md
+++ b/docs/src/pages/core-concepts/component-hydration.md
@@ -53,7 +53,7 @@ Besides the obvious performance benefits of sending less JavaScript down to the
 
 ## Hydrate Interactive Components
 
-Astro renders every component on the server **at build time**. To hydrate components on the client **at runtime**, you may use any of the following `client:*` directives. A directive is a component attribute (always with a `:`) which tells Astro how your component should be rendered.
+Astro renders every component on the server **at build time**, unless [client:only](#mycomponent-clientonly-) is used. To hydrate components on the client **at runtime**, you may use any of the following `client:*` directives. A directive is a component attribute (always with a `:`) which tells Astro how your component should be rendered.
 
 ```astro
 ---
@@ -81,6 +81,12 @@ Hydrate the component as soon as the element enters the viewport (uses [Intersec
 
 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.
 
+### `<MyComponent client:only />`
+
+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.
+
+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. `<client:only="my-custom-renderer" />`.
+
 ## Can I Hydrate Astro Components?
 
 [Astro components](./astro-components) (`.astro` files) are HTML-only templating components with no client-side runtime. If you try to hydrate an Astro component with a `client:` modifier, you will get an error.