MeWrite Docs

Svelte: Component is not valid SSR component

SvelteKitでSSR時にクライアント専用コードが実行された場合のエラー

概要

SvelteKitでサーバーサイドレンダリング(SSR)時にブラウザ専用のAPIやライブラリにアクセスしようとした場合に発生するエラーです。

エラーメッセージ

Error: <Component> is not a valid SSR component. You may need to review your build config

または

ReferenceError: window is not defined

原因

  1. ブラウザAPIへのアクセス: window, document, localStorageなどがSSR時に存在しない
  2. クライアント専用ライブラリ: ブラウザでしか動作しないnpmパッケージ
  3. 動的インポートの問題: SSR非対応のコンポーネント

解決策

1. browser チェックを使用

1
2
3
4
5
6
7
8
9
<script>
  import { browser } from '$app/environment';

  let windowWidth;

  if (browser) {
    windowWidth = window.innerWidth;
  }
</script>

2. onMount 内でクライアント処理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<script>
  import { onMount } from 'svelte';

  let chart;

  onMount(async () => {
    // クライアントサイドでのみ実行
    const Chart = (await import('chart.js')).default;
    chart = new Chart(/* ... */);
  });
</script>

3. 動的インポートでSSRを回避

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<script>
  import { browser } from '$app/environment';

  let MapComponent;

  if (browser) {
    import('$lib/Map.svelte').then(module => {
      MapComponent = module.default;
    });
  }
</script>

{#if MapComponent}
  <svelte:component this={MapComponent} />
{/if}

4. +page.js で ssr を無効化

1
2
// +page.js
export const ssr = false;

5. コンポーネントレベルで ssr 無効化

1
2
// +page.svelte または +layout.svelte の script context="module"
export const ssr = false;

6. vite.config.js で SSR 除外

1
2
3
4
5
6
// vite.config.js
export default defineConfig({
  ssr: {
    noExternal: ['some-browser-only-package']
  }
});

7. #if browser でテンプレートをガード

1
2
3
4
5
6
7
8
<script>
  import { browser } from '$app/environment';
  import BrowserOnlyComponent from './BrowserOnlyComponent.svelte';
</script>

{#if browser}
  <BrowserOnlyComponent />
{/if}

よくある間違い

  • サードパーティライブラリがSSR対応か確認していない
  • localStorageを直接トップレベルで使用
  • グローバル変数としてwindowを参照

Svelte の他のエラー

最終更新: 2025-12-09