svelte-clientside

svelte-clientside

A Svelte 5 component wrapper that prevents server-side rendering for client-only components while maintaining SEO-friendly SSR for the rest of your page.

Features

• 🚫 Prevents SSR: Components wrapped with ClientSide only render in the browser
• 🎨 Customizable Fallback: Show loading states or custom content during SSR
• ⚡ Zero Dependencies: Only requires Svelte 5 as a peer dependency
• 🔧 Flexible Options: Optional delays, custom fallbacks, and more
• 📦 Lightweight: Minimal bundle impact

Installation

npm install svelte-clientside

Quick Start

<script>
  import ClientSide from 'svelte-clientside';
  import MyClientOnlyComponent from './MyClientOnlyComponent.svelte';
</script>

<svelte:head>
  <meta property="og:title" content="Your Title" />
</svelte:head>

<h1>This content is server-rendered</h1>

<ClientSide>
  {#snippet children()}
    <MyClientOnlyComponent />
  {/snippet}
</ClientSide>

Usage Examples

Basic Usage

<ClientSide>
  {#snippet children()}
    <MyGameComponent />
  {/snippet}
</ClientSide>

With Custom Fallback

<ClientSide>
  {#snippet children()}
    <MyGameComponent />
  {/snippet}
  
  {#snippet fallback()}
    <div class="loading">
      <div class="spinner"></div>
      <p>Loading game engine...</p>
    </div>
  {/snippet}
</ClientSide>

With Delay (prevents flash)

<ClientSide delay={100}>
  {#snippet children()}
    <MyComponent />
  {/snippet}
</ClientSide>

No Fallback (invisible during SSR)

<ClientSide showFallback={false}>
  {#snippet children()}
    <MyComponent />
  {/snippet}
</ClientSide>

Multiple Components

<ClientSide>
  {#snippet children()}
    <GameEngine />
    <GameUI />
    <GameControls />
  {/snippet}
  
  {#snippet fallback()}
    <div class="game-skeleton">Game loading...</div>
  {/snippet}
</ClientSide>

Props

Prop	Type	Default	Description
showFallback	boolean	true	Whether to show fallback content during SSR
delay	number	0	Optional delay in milliseconds before showing client content

Snippets

Snippet	Required	Description
children	✅	The content to render only on the client-side
fallback	❌	Custom fallback content to show during SSR (optional)

Why Use This?

SvelteKit's SSR is great for SEO and performance, but some components need browser-only APIs (Canvas, WebGL, localStorage, etc.). Instead of disabling SSR for your entire route and losing SEO benefits, wrap only the problematic components with ClientSide.

❌ Before (loses SEO)

// +page.js
export const ssr = false; // Entire page loses SSR

✅ After (keeps SEO)

<svelte:head>
  <meta property="og:title" content="Your Title" /> <!-- Still works! -->
</svelte:head>

<h1>Server-rendered content</h1> <!-- SEO friendly -->

<ClientSide>
  {#snippet children()}
    <MyBrowserOnlyComponent /> <!-- Client-only -->
  {/snippet}
</ClientSide>

Requirements

• Svelte 5.0.0 or higher
• SvelteKit (recommended)

TypeScript Support

This package includes TypeScript definitions. No additional setup required.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Kite Captain