From 4f19bcd6deebb9c761abf180291053c3673a506f Mon Sep 17 00:00:00 2001 From: Thomas Date: Tue, 30 Sep 2025 20:19:04 +0200 Subject: [PATCH 1/4] Enhance `clientOnly` documentation --- .../reference/client/client-only.mdx | 64 +++++++++++++------ 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/src/routes/solid-start/reference/client/client-only.mdx b/src/routes/solid-start/reference/client/client-only.mdx index e35088e58..fa165e3c1 100644 --- a/src/routes/solid-start/reference/client/client-only.mdx +++ b/src/routes/solid-start/reference/client/client-only.mdx @@ -2,36 +2,62 @@ 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, such as Web3 interactions (like `window.ethereum` for Ethereum-based dApps) or IndexedDB for client-side storage. -To use `clientOnly`, isolate the desired component with DOM interactions in a file: +## How to Use `clientOnly` -```tsx -const location = window.document.location; +Follow these steps to implement `clientOnly` in your Solid Start project: -export default function ClientOnlyComponent() { - return
{location.href}
; -} -``` +1. **Isolate Client-Only Logic**: Create a separate file for the component that depends on browser-specific features, such as DOM or browser APIs. + + ```tsx + // ClientOnlyComponent.tsx + export default function ClientOnlyComponent() { + const location = document.location.href; + return
Current URL: {location}
; + } + ``` + +2. **Import with `clientOnly`**: Use `clientOnly` to dynamically import the isolated component in your parent component or page. + + ```tsx + // IsomorphicComponent.tsx + import { clientOnly } from "@solidjs/start"; -Once isolated, it can then be imported dynamically using `clientOnly`: + const ClientOnlyComp = clientOnly(() => import("./ClientOnlyComponent")); + + export default function IsomorphicComponent() { + return ; + } + ``` + +3. **Add a Fallback (Optional)**: Provide a `fallback` prop to display content while the client-only component is loading. + + ```tsx + Loading...} /> + ``` + +## 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 +// for example routes/page.tsx import { clientOnly } from "@solidjs/start"; -const ClientOnlyComp = clientOnly(() => import("../ClientOnlyComp")); +export default clientOnly(async () => ({ default: Page }), { lazy: true }); -function IsomorphicComp() { - return ; +function Page() { + // This code runs only on the client + return
Client-only page content
; } ``` -**Note:** The `` 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 & { fallback?: JSX.Element }` | Props passed to the component, including an optional `fallback` for rendering while the component loads. | From 93c7e1f85ee4b7780aeeb243dc832034c84ef9f0 Mon Sep 17 00:00:00 2001 From: Thomas Date: Tue, 30 Sep 2025 20:26:18 +0200 Subject: [PATCH 2/4] Update --- src/routes/solid-start/reference/client/client-only.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/routes/solid-start/reference/client/client-only.mdx b/src/routes/solid-start/reference/client/client-only.mdx index fa165e3c1..63ba9c77b 100644 --- a/src/routes/solid-start/reference/client/client-only.mdx +++ b/src/routes/solid-start/reference/client/client-only.mdx @@ -5,9 +5,7 @@ title: clientOnly 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, such as Web3 interactions (like `window.ethereum` for Ethereum-based dApps) or IndexedDB for client-side storage. -## How to Use `clientOnly` - -Follow these steps to implement `clientOnly` in your Solid Start project: +## How to Use `clientOnly` in Components 1. **Isolate Client-Only Logic**: Create a separate file for the component that depends on browser-specific features, such as DOM or browser APIs. From 59da5e276cb27d63e205f01a6425891768711240 Mon Sep 17 00:00:00 2001 From: Thomas Date: Sun, 5 Oct 2025 16:31:11 +0200 Subject: [PATCH 3/4] Update src/routes/solid-start/reference/client/client-only.mdx Co-authored-by: Atila Fassina --- src/routes/solid-start/reference/client/client-only.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/solid-start/reference/client/client-only.mdx b/src/routes/solid-start/reference/client/client-only.mdx index 63ba9c77b..79eddf64c 100644 --- a/src/routes/solid-start/reference/client/client-only.mdx +++ b/src/routes/solid-start/reference/client/client-only.mdx @@ -3,7 +3,7 @@ title: clientOnly --- 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, such as Web3 interactions (like `window.ethereum` for Ethereum-based dApps) or IndexedDB for client-side storage. +This is useful for code that relies on the browser-specific APIs, such as `window` or `document`. ## How to Use `clientOnly` in Components From de4cd0451e9237f28b8a86d469454b0f5b5fac5a Mon Sep 17 00:00:00 2001 From: Thomas Date: Sun, 5 Oct 2025 16:33:27 +0200 Subject: [PATCH 4/4] Update code snippets in client-only.mdx --- src/routes/solid-start/reference/client/client-only.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/routes/solid-start/reference/client/client-only.mdx b/src/routes/solid-start/reference/client/client-only.mdx index 79eddf64c..1ec225264 100644 --- a/src/routes/solid-start/reference/client/client-only.mdx +++ b/src/routes/solid-start/reference/client/client-only.mdx @@ -9,8 +9,7 @@ This is useful for code that relies on the browser-specific APIs, such as `windo 1. **Isolate Client-Only Logic**: Create a separate file for the component that depends on browser-specific features, such as DOM or browser APIs. - ```tsx - // ClientOnlyComponent.tsx + ```tsx title="ClientOnlyComponent" export default function ClientOnlyComponent() { const location = document.location.href; return
Current URL: {location}
; @@ -19,8 +18,7 @@ This is useful for code that relies on the browser-specific APIs, such as `windo 2. **Import with `clientOnly`**: Use `clientOnly` to dynamically import the isolated component in your parent component or page. - ```tsx - // IsomorphicComponent.tsx + ```tsx title="IsomorphicComponent.tsx" import { clientOnly } from "@solidjs/start"; const ClientOnlyComp = clientOnly(() => import("./ClientOnlyComponent")); @@ -40,8 +38,7 @@ This is useful for code that relies on the browser-specific APIs, such as `windo To disable SSR for an entire page, apply `clientOnly` at the page level. This ensures the page renders only on the client. -```tsx -// for example routes/page.tsx +```tsx title="routes/page.tsx" import { clientOnly } from "@solidjs/start"; export default clientOnly(async () => ({ default: Page }), { lazy: true });