docs: document derived use of $app/state's page (#13346)

#13305
sveltejs · Jan 20, 2025 · f5103c6 · f5103c6
1 parent 18d69fb
commit f5103c6
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 0 deletions.
diff --git a/packages/kit/src/runtime/app/state/index.js b/packages/kit/src/runtime/app/state/index.js
@@ -32,6 +32,17 @@ import { BROWSER } from 'esm-env';
  * {/if}
  * ```
  *
+ * Changes to `page` are available exclusively with runes. (The legacy reactivity syntax will not reflect any changes)
+ *
+ * ```svelte
+ * <!--- file: +page.svelte --->
+ * <script>
+ * 	import { page } from '$app/state';
+ * 	const id = $derived(page.params.id); // This will correctly update id for usage on this page
+ * 	$: badId = page.params.id; // Do not use; will never update after initial load
+ * </script>
+ * ```
+ *
  * On the server, values can only be read during rendering (in other words _not_ in e.g. `load` functions). In the browser, the values can be read at any time.
  *
  * @type {import('@sveltejs/kit').Page}

diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts
@@ -2356,6 +2356,17 @@ declare module '$app/state' {
 	 * {/if}
 	 * ```
 	 *
+	 * Changes to `page` are available exclusively with runes. (The legacy reactivity syntax will not reflect any changes)
+	 *
+	 * ```svelte
+	 * <!--- file: +page.svelte --->
+	 * <script>
+	 * 	import { page } from '$app/state';
+	 * 	const id = $derived(page.params.id); // This will correctly update id for usage on this page
+	 * 	$: badId = page.params.id; // Do not use; will never update after initial load
+	 * </script>
+	 * ```
+	 *
 	 * On the server, values can only be read during rendering (in other words _not_ in e.g. `load` functions). In the browser, the values can be read at any time.
 	 *
 	 * */