From a402d50b33eba2a937d09e635275c319061ce678 Mon Sep 17 00:00:00 2001
From: Simon H <5968653+dummdidumm@users.noreply.github.com>
Date: Wed, 8 Feb 2023 17:00:17 +0100
Subject: [PATCH] docs: clarify version management feature (#8941)

closes #8697
---
 .changeset/quiet-boats-add.md |  5 +++++
 packages/kit/types/index.d.ts | 18 +++++++++++++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/quiet-boats-add.md

diff --git a/.changeset/quiet-boats-add.md b/.changeset/quiet-boats-add.md
new file mode 100644
index 000000000000..83fbc7d585b6
--- /dev/null
+++ b/.changeset/quiet-boats-add.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+docs: clarify version management feature
diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts
index 630da8f886f9..647a41125c96 100644
--- a/packages/kit/types/index.d.ts
+++ b/packages/kit/types/index.d.ts
@@ -520,7 +520,23 @@ export interface KitConfig {
 		config?: (config: Record<string, any>) => Record<string, any> | void;
 	};
 	/**
-	 * Client-side navigation can be buggy if you deploy a new version of your app while people are using it. If the code for the new page is already loaded, it may have stale content; if it isn't, the app's route manifest may point to a JavaScript file that no longer exists. SvelteKit solves this problem by falling back to traditional full-page navigation if it detects that a new version has been deployed, using the `name` specified here (which defaults to a timestamp of the build).
+	 * Client-side navigation can be buggy if you deploy a new version of your app while people are using it. If the code for the new page is already loaded, it may have stale content; if it isn't, the app's route manifest may point to a JavaScript file that no longer exists.
+	 * SvelteKit helps you solve this problem through version management.
+	 * If SvelteKit encounters an error while loading the page and detects that a new version has been deployed (using the `name` specified here, which defaults to a timestamp of the build) it will fall back to traditional full-page navigation.
+	 * Not all navigations will result in an error though, for example if the JavaScript for the next page is already loaded. If you still want to force a full-page navigation in these cases, use techniques such as setting the `pollInverval` and then using `beforeNavigate`:
+	 * ```html
+	 * /// +layout.svelte
+	 * <script>
+	 * import { beforeNavigate } from '$app/navigation';
+	 * import { updated } from '$app/stores';
+	 *
+	 * beforeNavigate(({ willUnload, to }) => {
+	 *   if ($updated && !willUnload && to?.url) {
+	 *     location.href = to.route.url.href;
+	 *   }
+	 * });
+	 * </script>
+	 * ```
 	 *
 	 * If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of the [`updated`](/docs/modules#$app-stores-updated) store to `true` when it detects one.
 	 */