If you've ever tried to use `localStorage`, `window`, or `document` inside a SvelteKit component, you've probably run into a frustrating issue: **SvelteKit tries to server-render everything by default**, and browser-specific APIs don't exist on the server. This often leads to: * `ReferenceError: localStorage is not defined` * Broken hydration * Flashing or missing UI elements After running into this problem one too many times while working on a SvelteKit project, I built a lightweight wrapper component that solves this cleanly. It’s called `svelte-clientside`, and it allows **selective client-side rendering** inside a fully SSR-powered SvelteKit app. ## SSR and Browser APIs Don’t Mix This might not surprise seasoned developers, but if you're new to server-side rendering in JavaScript frameworks, it’s easy to miss: **just because something works in development doesn't mean it’s safe for SSR**. SvelteKit blurs the lines even more. For instance, you can use the `fetch` API (which is typically a browser API) on both the server and the client with almost identical syntax. There's no obvious distinction — the same code works in both environments, and that might lead you to believe that all browser APIs are fair game everywhere. That is, until one day, you try something like this: ```svelte ``` And just like that, SvelteKit tries to render your component on the server — where `localStorage` doesn’t exist — and your build explodes with a `ReferenceError`. What’s even more confusing? In dev mode, it might **seem** like it works. You’ll edit a file, the hot module reloader (HMR) kicks in, and magically the error disappears. The variable is defined again, the UI updates, and you assume the issue was just a typo or a fluke. But then you do a full page reload… and bam! That same ugly `localStorage is not defined` error is back to haunt you. This happened to me more times than I’d like to admit, until I finally understood what was really going on behind the scenes — and how different the development environment is from production in SvelteKit. So what can you do? ## Existing Workarounds Before I built `svelte-clientside`, I danced through all the usual workarounds hoping one of them would save me from SSR doom. Spoiler: they all have trade-offs — some subtle, some disastrous. Let’s walk through them: ### 1. `if (browser)` Checks ```svelte ``` This will stops the build from crashing and is actually the right, one of the right, ways to do this. This becomes hectic when you have a billion client-components and now you have to do this for all of those components. In Next Js this is just a simple "use-client" directive on top of the component and you are done worrying about it. If only there was a wrapper component that encapsultes this behavior. ### 2. `onMount()` Usage ```svelte ``` This os going to postpones execution until the client-side kicks in. But, the component *still* renders during SSR with empty values and is not ideal when your component depends heavily on that client-only data or have a lot of client sie components on the page. This is basically telling Svelte, *“Just close your eyes and hope this doesn't break until we're safely on the client.”* --- ### 3. Disabling SSR Entirely ```svelte // +page.js export const ssr = false; ``` This is the easiest to set up but it absolutely **kills** server-side rendering for your whole page. Say goodbye to SEO, faster load times, and server-rendered metadata. It’s the nuclear option. If you’re building a landing page with dynamic components, this might be the worst possible tradeoff. You give up all the good things about SvelteKit just to make one component behave. Please don't do this, unless it's really necessary or you life depends on it. ## Meet `svelte-clientside` That’s why I built [`svelte-clientside`](https://www.npmjs.com/package/svelte-clientside) — a simple Svelte 5 wrapper that renders its children **only** on the client, **only** when ready, and with zero drama. You get all the perks of SSR for the rest of your page, and you isolate the “offending” component inside a clean little wrapper that plays nice with both the dev server and production. ### 🔧 What It Does * Wraps any component that needs `window`, `document`, `localStorage`, WebGL, or any other browser-only API * Lets you show a fallback while the client is loading * Supports optional delays to smooth out transitions and avoid flashes * Works seamlessly with Svelte 5’s new syntax and snippets ## Installation ```bash npm install svelte-clientside ``` [View on npm](https://www.npmjs.com/package/svelte-clientside) [View source on GitHub](https://github.com/KiteCaptain/svelte-clientside) ## How It Works Under the hood, `ClientSide` uses: * `$app/environment` to detect the browser * `onMount()` to wait for the client * Svelte 5 snippets (`{#snippet}`) to dynamically render content Example: ```svelte {#snippet children()} {/snippet} ``` If SSR is running: it renders the fallback or nothing. If on the client: it waits until the component is ready, then renders the actual content. It’s that simple. Note: You could also avoid the snippets entirely and ths would stillwork as required. Example: ```svelte ``` ## Usage Examples ### Basic Usage ```svelte {#snippet children()} {/snippet} ```svelte ### With Custom Fallback ```svelte {#snippet children()} {/snippet} {#snippet fallback()}

Initializing WebGL...

{/snippet} ``` ### With Delay ```svelte {#snippet children()} {/snippet} ``` ### With No Fallback ```svelte {#snippet children()} {/snippet} ``` Nothing shows during SSR — the component is truly invisible until the client is ready. ## Props Reference | Prop | Type | Default | Description | | -------------- | ------- | ------- | ------------------------------------------------ | | `showFallback` | boolean | `true` | Whether to show fallback content during SSR | | `delay` | number | `0` | Delay in ms before rendering client-side content | ## Why This Approach Is Better (Kind of) With `svelte-clientside`, you: ✅ Keep SEO and fast load times thanks to SSR ✅ Avoid hydration issues and browser-only crashes ✅ Show users a smoother experience with fallback + delay ✅ Don’t have to sacrifice your entire page to fix one component In other words, it gives you the **best of both worlds** — SSR where you want it, client-only rendering where you need it. Try it now: [npm package](https://www.npmjs.com/package/svelte-clientside) [GitHub repo](https://github.com/KiteCaptain/svelte-clientside) Got questions? Want to contribute? [Open an issue](https://github.com/KiteCaptain/svelte-clientside/issues), submit a PR, or just drop a star if this saved your dev sanity

How to Use Client-Only Components Without Breaking SvelteKit SSR

Comments