From d6d13ced086f5ddb617db2bcd524b2417dd5eb14 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Tue, 14 Oct 2025 20:45:29 -0400
Subject: [PATCH] docs: improve createContext documentation (#16952)

* docs: improve createContext documentation

* update context page

* bump
---
 documentation/docs/06-runtime/02-context.md   | 21 ++++++-------------
 .../svelte/src/internal/client/context.js     |  8 +++++++
 .../svelte/src/internal/server/context.js     |  1 +
 packages/svelte/types/index.d.ts              | 10 ++++++++-
 4 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/documentation/docs/06-runtime/02-context.md b/documentation/docs/06-runtime/02-context.md
index f395de421c..0dfb996164 100644
--- a/documentation/docs/06-runtime/02-context.md
+++ b/documentation/docs/06-runtime/02-context.md
@@ -83,27 +83,18 @@ Svelte will warn you if you get it wrong.
 
 ## Type-safe context
 
-A useful pattern is to wrap the calls to `setContext` and `getContext` inside helper functions that let you preserve type safety:
+As an alternative to using `setContext` and `getContext` directly, you can use them via `createContext`. This gives you type safety and makes it unnecessary to use a key:
 
-```js
-/// file: context.js
+```ts
+/// file: context.ts
 // @filename: ambient.d.ts
 interface User {}
 
-// @filename: index.js
+// @filename: index.ts
 // ---cut---
-import { getContext, setContext } from 'svelte';
-
-const key = {};
-
-/** @param {User} user */
-export function setUserContext(user) {
-	setContext(key, user);
-}
+import { createContext } from 'svelte';
 
-export function getUserContext() {
-	return /** @type {User} */ (getContext(key));
-}
+export const [getUserContext, setUserContext] = createContext<User>();
 ```
 
 ## Replacing global state
diff --git a/packages/svelte/src/internal/client/context.js b/packages/svelte/src/internal/client/context.js
index ea63072a37..751a35321a 100644
--- a/packages/svelte/src/internal/client/context.js
+++ b/packages/svelte/src/internal/client/context.js
@@ -71,8 +71,12 @@ export function set_dev_current_component_function(fn) {
 
 /**
  * Returns a `[get, set]` pair of functions for working with context in a type-safe way.
+ *
+ * `get` will throw an error if no parent component called `set`.
+ *
  * @template T
  * @returns {[() => T, (context: T) => T]}
+ * @since 5.40.0
  */
 export function createContext() {
 	const key = {};
@@ -93,6 +97,8 @@ export function createContext() {
  * Retrieves the context that belongs to the closest parent component with the specified `key`.
  * Must be called during component initialisation.
  *
+ * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
+ *
  * @template T
  * @param {any} key
  * @returns {T}
@@ -110,6 +116,8 @@ export function getContext(key) {
  *
  * Like lifecycle functions, this must be called during component initialisation.
  *
+ * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
+ *
  * @template T
  * @param {any} key
  * @param {T} context
diff --git a/packages/svelte/src/internal/server/context.js b/packages/svelte/src/internal/server/context.js
index 1813bfbf78..7779da4c1d 100644
--- a/packages/svelte/src/internal/server/context.js
+++ b/packages/svelte/src/internal/server/context.js
@@ -13,6 +13,7 @@ export function set_ssr_context(v) {
 /**
  * @template T
  * @returns {[() => T, (context: T) => T]}
+ * @since 5.40.0
  */
 export function createContext() {
 	const key = {};
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index 58e3285e4a..a9938fe924 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -450,12 +450,18 @@ declare module 'svelte' {
 	type NotFunction<T> = T extends Function ? never : T;
 	/**
 	 * Returns a `[get, set]` pair of functions for working with context in a type-safe way.
-	 * */
+	 *
+	 * `get` will throw an error if no parent component called `set`.
+	 *
+	 * @since 5.40.0
+	 */
 	export function createContext<T>(): [() => T, (context: T) => T];
 	/**
 	 * Retrieves the context that belongs to the closest parent component with the specified `key`.
 	 * Must be called during component initialisation.
 	 *
+	 * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
+	 *
 	 * */
 	export function getContext<T>(key: any): T;
 	/**
@@ -465,6 +471,8 @@ declare module 'svelte' {
 	 *
 	 * Like lifecycle functions, this must be called during component initialisation.
 	 *
+	 * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
+	 *
 	 * */
 	export function setContext<T>(key: any, context: T): T;
 	/**