---
outline: deep
---

# SSR 互換性 {#ssr-compatibility}

VitePress は本番ビルド時に、Node.js 上で Vue のサーバーサイドレンダリング（SSR）機能を使ってアプリを事前レンダリングします。つまり、テーマコンポーネント内のすべてのカスタムコードは SSR 互換性の対象になります。

[公式 Vue ドキュメントの SSR セクション](https://vuejs.org/guide/scaling-up/ssr.html)では、SSR とは何か、SSR と SSG の関係、そして SSR に優しいコードを書く際の一般的な注意点が解説されています。経験則としては、**ブラウザ / DOM API へのアクセスは Vue コンポーネントの `beforeMount` または `mounted` フック内に限定** するのが安全です。

## `<ClientOnly>` {#clientonly}

SSR に適さないコンポーネント（例：カスタムディレクティブを含むなど）を使用・デモする場合は、組み込みの `<ClientOnly>` コンポーネントでラップできます。

 ```md
 <ClientOnly>
   <NonSSRFriendlyComponent />
 </ClientOnly>
 ```

## インポート時に Browser API にアクセスするライブラリ {#libraries-that-access-browser-api-on-import}

一部のコンポーネントやライブラリは **インポート時に** ブラウザ API にアクセスします。インポート時にブラウザ環境を前提とするコードを使うには、動的インポートが必要です。

### mounted フック内でのインポート {#importing-in-mounted-hook}

 ```vue
 <script setup>
 import { onMounted } from 'vue'

 onMounted(() => {
   import('./lib-that-access-window-on-import').then((module) => {
     // ここでコードを利用
   })
 })
 </script>
 ```

### 条件付きインポート {#conditional-import}

[`import.meta.env.SSR`](https://vitejs.dev/guide/env-and-mode.html#env-variables) フラグ（Vite の環境変数の一部）を使って、依存関係を条件付きでインポートすることもできます。

 ```js
 if (!import.meta.env.SSR) {
   import('./lib-that-access-window-on-import').then((module) => {
     // ここでコードを利用
   })
 }
 ```

[`Theme.enhanceApp`](./custom-theme#theme-interface) は非同期にできるため、**インポート時に Browser API に触れる Vue プラグイン** を条件付きでインポート・登録できます。

 ```js [.vitepress/theme/index.js]
 /** @type {import('vitepress').Theme} */
 export default {
   // ...
   async enhanceApp({ app }) {
     if (!import.meta.env.SSR) {
       const plugin = await import('plugin-that-access-window-on-import')
       app.use(plugin.default)
     }
   }
 }
 ```

TypeScript を使う場合：

 ```ts [.vitepress/theme/index.ts]
 import type { Theme } from 'vitepress'

 export default {
   // ...
   async enhanceApp({ app }) {
     if (!import.meta.env.SSR) {
       const plugin = await import('plugin-that-access-window-on-import')
       app.use(plugin.default)
     }
   }
 } satisfies Theme
 ```

### `defineClientComponent`

VitePress は、**インポート時に Browser API にアクセスする Vue コンポーネント** を読み込むためのユーティリティを提供します。

 ```vue
 <script setup>
 import { defineClientComponent } from 'vitepress'

 const ClientComp = defineClientComponent(() => {
   return import('component-that-access-window-on-import')
 })
 </script>

 <template>
   <ClientComp />
 </template>
 ```

ターゲットコンポーネントに props / children / slots を渡すこともできます。

 ```vue
 <script setup>
 import { ref } from 'vue'
 import { defineClientComponent } from 'vitepress'

 const clientCompRef = ref(null)
 const ClientComp = defineClientComponent(
   () => import('component-that-access-window-on-import'),

   // 引数は h() に渡されます - https://vuejs.org/api/render-function.html#h
   [
     {
       ref: clientCompRef
     },
     {
       default: () => 'default slot',
       foo: () => h('div', 'foo'),
       bar: () => [h('span', 'one'), h('span', 'two')]
     }
   ],

   // コンポーネント読み込み後のコールバック（非同期可）
   () => {
     console.log(clientCompRef.value)
   }
 )
 </script>

 <template>
   <ClientComp />
 </template>
 ```

ターゲットコンポーネントは、ラッパーコンポーネントの mounted フックで初めてインポートされます。