From 2b732cc1d02661eb443c5e88ff160f332d79169b Mon Sep 17 00:00:00 2001
From: Danny Koppenhagen <Danny.Koppenhagen@deutschebahn.com>
Date: Wed, 2 Oct 2024 22:29:38 +0200
Subject: [PATCH] docs: add SSR / Nuxt note

closes #358
---
 docs/get-started.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/get-started.md b/docs/get-started.md
index 3ae0fcc..38a754b 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -37,6 +37,8 @@ bun add vue3-openlayers           # install this library
 
 :::
 
+Please ensure you are aware of potential issues with [Server-Side-Rendering (SSR)](#server-side-rendering).
+
 ## Usage: As Plugin
 
 To use `vue3-openlayers` in your application as a Plugin for global component availability,
@@ -118,6 +120,43 @@ import { Map, Layers, Sources } from "vue3-openlayers";
 
 :::
 
+## Server Side Rendering
+
+Be aware that the Vue3Openlayers map cannot be rendered at server side.
+Disabling SSR resolves this issue.
+The following example shows how to disable Vue3Openlayers when running SSR using Nuxt.js.
+
+**Example Nuxt config**
+
+The first approach is to disable the whole affected route where the map is rendered:
+
+```ts
+export default defineNuxtConfig({
+  // ...
+  routeRules: {
+    '/sales': { ssr: false },
+  },
+  // ...
+})
+```
+
+You can also specifically render the map only at client side, by putting inside the `ClientOnly` component:
+
+```vue
+<template>
+  <ClientOnly>
+    <Map.OlMap style="min-width: 400px; min-height: 400px;">
+      <Map.OlView :center="[40, 40]" :zoom="5" projection="EPSG:4326"/>
+      <Layers.OlTileLayer>
+        <Sources.OlSourceOsm/>
+      </Layers.OlTileLayer>
+    </Map.OlMap>
+  </ClientOnly>
+</template>
+```
+
+see also: [Issue #358](https://github.com/MelihAltintas/vue3-openlayers/issues/358)
+
 ## Debug Mode
 
 You can activate the `debug` mode, to log events receiving from OpenLayers and props passed to OpenLayers on the console.