Closes #1288 (#1289)

Co-authored-by: Atila Fassina <[email protected]>

Author: thomasbuilds

src/routes/solid-start/reference/client/client-only.mdx

@@ -2,36 +2,57 @@
 title: clientOnly
 ---
 
-Wrapping components in `clientOnly` will cause them render _only_ in the client. 
-This can useful for components that interact directly with the DOM, such as jQuery, since they can not render on the server.
-It works similar to [`lazy`](/reference/component-apis/lazy) but will only render _after hydration_ and will never load on the server.
+The `clientOnly` function allows components or pages to render exclusively on the client side, bypassing server-side rendering (_SSR_).
+This is useful for code that relies on the browser-specific APIs, such as `window` or `document`.
 
-To use `clientOnly`, isolate the desired component with DOM interactions in a file:
+## How to Use `clientOnly` in Components
 
-```tsx
-const location = window.document.location;
+1. **Isolate Client-Only Logic**: Create a separate file for the component that depends on browser-specific features, such as DOM or browser APIs.
 
-export default function ClientOnlyComponent() {
-	return <div>{location.href}</div>;
-}
-```
+   ```tsx title="ClientOnlyComponent"
+   export default function ClientOnlyComponent() {
+     const location = document.location.href;
+     return <div>Current URL: {location}</div>;
+   }
+   ```
+
+2. **Import with `clientOnly`**: Use `clientOnly` to dynamically import the isolated component in your parent component or page.
+
+   ```tsx title="IsomorphicComponent.tsx"
+   import { clientOnly } from "@solidjs/start";
+
+   const ClientOnlyComp = clientOnly(() => import("./ClientOnlyComponent"));
 
-Once isolated, it can then be imported dynamically using `clientOnly`:
+   export default function IsomorphicComponent() {
+     return <ClientOnlyComp />;
+   }
+   ```
 
-```tsx
+3. **Add a Fallback (Optional)**: Provide a `fallback` prop to display content while the client-only component is loading.
+
+   ```tsx
+   <ClientOnlyComp fallback={<div>Loading...</div>} />
+   ```
+
+## Disabling SSR for Entire Pages
+
+To disable SSR for an entire page, apply `clientOnly` at the page level. This ensures the page renders only on the client.
+
+```tsx title="routes/page.tsx"
 import { clientOnly } from "@solidjs/start";
 
-const ClientOnlyComp = clientOnly(() => import("../ClientOnlyComp"));
+export default clientOnly(async () => ({ default: Page }), { lazy: true });
 
-function IsomorphicComp() {
-	return <ClientOnlyComp />;
+function Page() {
+  // This code runs only on the client
+  return <div>Client-only page content</div>;
 }
 ```
 
-**Note:** The `<ClientOnlyComp />` can take a fallback prop for when it is loading.
-
 ## Parameters
 
-| Argument | Type            | Description                          |
-| -------- | --------------- | ------------------------------------ |
-| fn       | `() => Promise` | Function to be run client-side only. |
+| Argument  | Type                                               | Description                                                                                              |
+| --------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `fn`      | `() => Promise<{ default: () => JSX.Element }>`    | A function that dynamically imports a component to be rendered only on the client side.                  |
+| `options` | `{ lazy?: boolean }`                               | An optional object to configure loading behavior. Set `lazy: false` for eager loading                    |
+| `props`   | `Record<string, any> & { fallback?: JSX.Element }` | Props passed to the component, including an optional `fallback` for rendering while the component loads. |