From 5a8fa69dbf46e99beed812157ed78609f8054331 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Fri, 21 Mar 2025 12:54:53 -0400
Subject: [PATCH] feat: make deriveds writable (#15570)

* feat: make deriveds writable

* add optimistic UI example

* add note to when-not-to-use-effect

* add section on deep reactivity

* root-relative URL

* use hash URL

* mention const

* make handler async, move into script block
---
 .changeset/clever-terms-tell.md               |  5 ++
 documentation/docs/02-runes/03-$derived.md    | 42 +++++++++++++++++
 documentation/docs/02-runes/04-$effect.md     |  2 +
 .../phases/2-analyze/visitors/shared/utils.js | 31 +------------
 .../runes-no-derived-assignment/_config.js    |  8 ----
 .../runes-no-derived-assignment/main.svelte   |  5 --
 .../runes-no-derived-binding/_config.js       |  8 ----
 .../runes-no-derived-binding/main.svelte      |  6 ---
 .../_config.js                                |  8 ----
 .../main.svelte                               | 10 ----
 .../_config.js                                |  8 ----
 .../main.svelte                               | 10 ----
 .../runes-no-derived-update/_config.js        |  8 ----
 .../runes-no-derived-update/main.svelte       |  5 --
 .../samples/writable-derived/_config.js       | 46 +++++++++++++++++++
 .../samples/writable-derived/main.svelte      |  9 ++++
 .../reassign-derived-literal/errors.json      | 14 ------
 .../reassign-derived-literal/input.svelte     |  9 ----
 .../errors.json                               | 14 ------
 .../input.svelte                              |  9 ----
 .../reassign-derived-public-field/errors.json | 14 ------
 .../input.svelte                              |  9 ----
 22 files changed, 105 insertions(+), 175 deletions(-)
 create mode 100644 .changeset/clever-terms-tell.md
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js
 delete mode 100644 packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte
 create mode 100644 packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js
 create mode 100644 packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json
 delete mode 100644 packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte

diff --git a/.changeset/clever-terms-tell.md b/.changeset/clever-terms-tell.md
new file mode 100644
index 0000000000..606868bce3
--- /dev/null
+++ b/.changeset/clever-terms-tell.md
@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: make deriveds writable
diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
index 24ab643b68..2464aa9295 100644
--- a/documentation/docs/02-runes/03-$derived.md
+++ b/documentation/docs/02-runes/03-$derived.md
@@ -52,6 +52,48 @@ Anything read synchronously inside the `$derived` expression (or `$derived.by` f
 
 To exempt a piece of state from being treated as a dependency, use [`untrack`](svelte#untrack).
 
+## Overriding derived values
+
+Derived expressions are recalculated when their dependencies change, but you can temporarily override their values by reassigning them (unless they are declared with `const`). This can be useful for things like _optimistic UI_, where a value is derived from the 'source of truth' (such as data from your server) but you'd like to show immediate feedback to the user:
+
+```svelte
+<script>
+	let { post, like } = $props();
+
+	let likes = $derived(post.likes);
+
+	async function onclick() {
+		// increment the `likes` count immediately...
+		likes += 1;
+
+		// and tell the server, which will eventually update `post`
+		try {
+			await like();
+		} catch {
+			// failed! roll back the change
+			likes -= 1;
+		}
+	}
+</script>
+
+<button {onclick}>🧡 {likes}</button>
+```
+
+> [!NOTE] Prior to Svelte 5.25, deriveds were read-only.
+
+## Deriveds and reactivity
+
+Unlike `$state`, which converts objects and arrays to [deeply reactive proxies]($state#Deep-state), `$derived` values are left as-is. For example, [in a case like this](/playground/untitled#H4sIAAAAAAAAE4VU22rjMBD9lUHd3aaQi9PdstS1A3t5XvpQ2Ic4D7I1iUUV2UjjNMX431eS7TRdSosxgjMzZ45mjt0yzffIYibvy0ojFJWqDKCQVBk2ZVup0LJ43TJ6rn2aBxw-FP2o67k9oCKP5dziW3hRaUJNjoYltjCyplWmM1JIIAn3FlL4ZIkTTtYez6jtj4w8WwyXv9GiIXiQxLVs9pfTMR7EuoSLIuLFbX7Z4930bZo_nBrD1bs834tlfvsBz9_SyX6PZXu9XaL4gOWn4sXjeyzftv4ZWfyxubpzxzg6LfD4MrooxELEosKCUPigQCMPKCZh0OtQE1iSxcsmdHuBvCiHZXALLXiN08EL3RRkaJ_kDVGle0HcSD5TPEeVtj67O4Nrg9aiSNtBY5oODJkrL5QsHtN2cgXp6nSJMWzpWWGasdlsGEMbzi5jPr5KFr0Ep7pdeM2-TCelCddIhDxAobi1jqF3cMaC1RKp64bAW9iFAmXGIHfd4wNXDabtOLN53w8W53VvJoZLh7xk4Rr3CoL-UNoLhWHrT1JQGcM17u96oES5K-kc2XOzkzqGCKL5De79OUTyyrg1zgwXsrEx3ESfx4Bz0M5UjVMHB24mw9SuXtXFoN13fYKOM1tyUT3FbvbWmSWCZX2Er-41u5xPoml45svRahl9Wb9aasbINJixDZwcPTbyTLZSUsAvrg_cPuCR7s782_WU8343Y72Qtlb8OYatwuOQvuN13M_hJKNfxann1v1U_B1KZ_D_mzhzhz24fw85CSz2irtN9w9HshBK7AQAAA==)...
+
+```svelte
+let items = $state([...]);
+
+let index = $state(0);
+let selected = $derived(items[index]);
+```
+
+...you can change (or `bind:` to) properties of `selected` and it will affect the underlying `items` array. If `items` was _not_ deeply reactive, mutating `selected` would have no effect.
+
 ## Update propagation
 
 Svelte uses something called _push-pull reactivity_ — when state is updated, everything that depends on the state (whether directly or indirectly) is immediately notified of the change (the 'push'), but derived values are not re-evaluated until they are actually read (the 'pull').
diff --git a/documentation/docs/02-runes/04-$effect.md b/documentation/docs/02-runes/04-$effect.md
index 75f59102f9..ae1a2146c9 100644
--- a/documentation/docs/02-runes/04-$effect.md
+++ b/documentation/docs/02-runes/04-$effect.md
@@ -254,6 +254,8 @@ In general, `$effect` is best considered something of an escape hatch — useful
 
 > [!NOTE] For things that are more complicated than a simple expression like `count * 2`, you can also use `$derived.by`.
 
+If you're using an effect because you want to be able to reassign the derived value (to build an optimistic UI, for example) note that [deriveds can be directly overridden]($derived#Overriding-derived-values) as of Svelte 5.25.
+
 You might be tempted to do something convoluted with effects to link one value to another. The following example shows two inputs for "money spent" and "money left" that are connected to each other. If you update one, the other should update accordingly. Don't use effects for this ([demo](/playground/untitled#H4sIAAAAAAAACpVRy26DMBD8FcvKgUhtoIdeHBwp31F6MGSJkBbHwksEQvx77aWQqooq9bgzOzP7mGTdIHipPiZJowOpGJAv0po2VmfnDv4OSBErjYdneHWzBJaCjcx91TWOToUtCIEE3cig0OIty44r5l1oDtjOkyFIsv3GINQ_CNYyGegd1DVUlCR7oU9iilDUcP8S8roYs9n8p2wdYNVFm4csTx872BxNCcjr5I11fdgonEkXsjP2CoUUZWMv6m6wBz2x7yxaM-iJvWeRsvSbSVeUy5i0uf8vKA78NIeJLSZWv1I8jQjLdyK4XuTSeIdmVKJGGI4LdjVOiezwDu1yG74My8PLCQaSiroe5s_5C2PHrkVGAgAA)):
 
 ```svelte
diff --git a/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js b/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js
index 04f4347a40..d6c74eddb6 100644
--- a/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js
+++ b/packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js
@@ -21,10 +21,6 @@ export function validate_assignment(node, argument, state) {
 		const binding = state.scope.get(argument.name);
 
 		if (state.analysis.runes) {
-			if (binding?.kind === 'derived') {
-				e.constant_assignment(node, 'derived state');
-			}
-
 			if (binding?.node === state.analysis.props_id) {
 				e.constant_assignment(node, '$props.id()');
 			}
@@ -38,25 +34,6 @@ export function validate_assignment(node, argument, state) {
 			e.snippet_parameter_assignment(node);
 		}
 	}
-	if (
-		argument.type === 'MemberExpression' &&
-		argument.object.type === 'ThisExpression' &&
-		(((argument.property.type === 'PrivateIdentifier' || argument.property.type === 'Identifier') &&
-			state.derived_state.some(
-				(derived) =>
-					derived.name === /** @type {PrivateIdentifier | Identifier} */ (argument.property).name &&
-					derived.private === (argument.property.type === 'PrivateIdentifier')
-			)) ||
-			(argument.property.type === 'Literal' &&
-				argument.property.value &&
-				typeof argument.property.value === 'string' &&
-				state.derived_state.some(
-					(derived) =>
-						derived.name === /** @type {Literal} */ (argument.property).value && !derived.private
-				)))
-	) {
-		e.constant_assignment(node, 'derived state');
-	}
 }
 
 /**
@@ -81,7 +58,6 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 	} else if (argument.type === 'Identifier') {
 		const binding = scope.get(argument.name);
 		if (
-			binding?.kind === 'derived' ||
 			binding?.declaration_kind === 'import' ||
 			(binding?.declaration_kind === 'const' && binding.kind !== 'each')
 		) {
@@ -96,12 +72,7 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 			// );
 
 			// TODO have a more specific error message for assignments to things like `{:then foo}`
-			const thing =
-				binding.declaration_kind === 'import'
-					? 'import'
-					: binding.kind === 'derived'
-						? 'derived state'
-						: 'constant';
+			const thing = binding.declaration_kind === 'import' ? 'import' : 'constant';
 
 			if (is_binding) {
 				e.constant_binding(node, thing);
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js
deleted file mode 100644
index 94985a9939..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte
deleted file mode 100644
index 3bf836f6c5..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-assignment/main.svelte
+++ /dev/null
@@ -1,5 +0,0 @@
-<script>
-	const a = $state(0);
-	let b = $derived(a);
-	b = 1;
-</script>
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js
deleted file mode 100644
index 87b88d79cc..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_binding',
-		message: 'Cannot bind to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte
deleted file mode 100644
index 6c198dc068..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-binding/main.svelte
+++ /dev/null
@@ -1,6 +0,0 @@
-<script>
-	let a = $state(0);
-	let b = $derived({ a });
-</script>
-
-<input type="number" bind:value={b} />
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js
deleted file mode 100644
index 94985a9939..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte
deleted file mode 100644
index d44806757e..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-assignment/main.svelte
+++ /dev/null
@@ -1,10 +0,0 @@
-<script>
-	class Counter {
-		count = $state();
-		#doubled = $derived(this.count * 2);
-
-		nope() {
-			this.#doubled += 1;
-		}
-	}
-</script>
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js
deleted file mode 100644
index 94985a9939..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte
deleted file mode 100644
index e4ee2e8635..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-state-field-update/main.svelte
+++ /dev/null
@@ -1,10 +0,0 @@
-<script>
-	class Counter {
-		count = $state();
-		#doubled = $derived(this.count * 2);
-
-		nope() {
-			this.#doubled++;
-		}
-	}
-</script>
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js
deleted file mode 100644
index 94985a9939..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/_config.js
+++ /dev/null
@@ -1,8 +0,0 @@
-import { test } from '../../test';
-
-export default test({
-	error: {
-		code: 'constant_assignment',
-		message: 'Cannot assign to derived state'
-	}
-});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte b/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte
deleted file mode 100644
index d266c95bb8..0000000000
--- a/packages/svelte/tests/compiler-errors/samples/runes-no-derived-update/main.svelte
+++ /dev/null
@@ -1,5 +0,0 @@
-<script>
-	const a = $state(0);
-	let b = $derived(a);
-	b++;
-</script>
diff --git a/packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js b/packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js
new file mode 100644
index 0000000000..b48ccbdfd0
--- /dev/null
+++ b/packages/svelte/tests/runtime-runes/samples/writable-derived/_config.js
@@ -0,0 +1,46 @@
+import { flushSync } from 'svelte';
+import { test } from '../../test';
+
+export default test({
+	html: `
+		<input type="range"><input type="range"><p>0 * 2 = 0</p>
+	`,
+
+	ssrHtml: `
+		<input type="range" value="0"><input type="range" value="0"><p>0 * 2 = 0</p>
+	`,
+
+	test({ assert, target, window }) {
+		const [input1, input2] = target.querySelectorAll('input');
+
+		flushSync(() => {
+			input1.value = '10';
+			input1.dispatchEvent(new window.Event('input', { bubbles: true }));
+		});
+
+		assert.htmlEqual(
+			target.innerHTML,
+			`<input type="range"><input type="range"><p>10 * 2 = 20</p>`
+		);
+
+		flushSync(() => {
+			input2.value = '99';
+			input2.dispatchEvent(new window.Event('input', { bubbles: true }));
+		});
+
+		assert.htmlEqual(
+			target.innerHTML,
+			`<input type="range"><input type="range"><p>10 * 2 = 99</p>`
+		);
+
+		flushSync(() => {
+			input1.value = '20';
+			input1.dispatchEvent(new window.Event('input', { bubbles: true }));
+		});
+
+		assert.htmlEqual(
+			target.innerHTML,
+			`<input type="range"><input type="range"><p>20 * 2 = 40</p>`
+		);
+	}
+});
diff --git a/packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte b/packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte
new file mode 100644
index 0000000000..ab1dde0b9b
--- /dev/null
+++ b/packages/svelte/tests/runtime-runes/samples/writable-derived/main.svelte
@@ -0,0 +1,9 @@
+<script>
+	let count = $state(0);
+	let double = $derived(count * 2);
+</script>
+
+<input type="range" bind:value={count} />
+<input type="range" bind:value={double} />
+
+<p>{count} * 2 = {double}</p>
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json b/packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json
deleted file mode 100644
index 8681d84ab2..0000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-literal/errors.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-	{
-		"code": "constant_assignment",
-		"message": "Cannot assign to derived state",
-		"start": {
-			"column": 3,
-			"line": 6
-		},
-		"end": {
-			"column": 29,
-			"line": 6
-		}
-	}
-]
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte b/packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte
deleted file mode 100644
index 8f109c9e1f..0000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-literal/input.svelte
+++ /dev/null
@@ -1,9 +0,0 @@
-<script>
-	class Test{
-		der = $derived({ test: 0 });
-
-		set test(v){
-			this["der"] = { test: 45 };
-		}
-	}
-</script>
\ No newline at end of file
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json b/packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json
deleted file mode 100644
index c211aa4608..0000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-private-field/errors.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-	{
-		"code": "constant_assignment",
-		"message": "Cannot assign to derived state",
-		"start": {
-			"column": 3,
-			"line": 6
-		},
-		"end": {
-			"column": 27,
-			"line": 6
-		}
-	}
-]
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte b/packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte
deleted file mode 100644
index 62e2317e03..0000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-private-field/input.svelte
+++ /dev/null
@@ -1,9 +0,0 @@
-<script>
-	class Test{
-		#der = $derived({ test: 0 });
-
-		set test(v){
-			this.#der = { test: 45 };
-		}
-	}
-</script>
\ No newline at end of file
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json b/packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json
deleted file mode 100644
index 98837589ac..0000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-public-field/errors.json
+++ /dev/null
@@ -1,14 +0,0 @@
-[
-	{
-		"code": "constant_assignment",
-		"message": "Cannot assign to derived state",
-		"start": {
-			"column": 3,
-			"line": 6
-		},
-		"end": {
-			"column": 26,
-			"line": 6
-		}
-	}
-]
diff --git a/packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte b/packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte
deleted file mode 100644
index e2c4693e86..0000000000
--- a/packages/svelte/tests/validator/samples/reassign-derived-public-field/input.svelte
+++ /dev/null
@@ -1,9 +0,0 @@
-<script>
-	class Test{
-		der = $derived({ test: 0 });
-
-		set test(v){
-			this.der = { test: 45 };
-		}
-	}
-</script>
\ No newline at end of file