feat: allow await in components

.changeset/eleven-weeks-dance.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: support `await` in components when using the `experimental.async` compiler option

.github/workflows/ci.yml

@@ -43,6 +43,23 @@ jobs:
       - run: pnpm test
         env:
           CI: true
+  TestNoAsync:
+    permissions: {}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm playwright install chromium
+      - run: pnpm test runtime-runes
+        env:
+          CI: true
+          SVELTE_NO_ASYNC: true
   Lint:
     permissions: {}
     runs-on: ubuntu-latest

documentation/docs/98-reference/.generated/client-errors.md

@@ -1,5 +1,17 @@
 <!-- This file is generated by scripts/process-messages/index.js. Do not edit! -->
 
+### async_derived_orphan
+
+```
+Cannot create a `$derived(...)` with an `await` expression outside of an effect tree
+```
+
+In Svelte there are two types of reaction — [`$derived`](/docs/svelte/$derived) and [`$effect`](/docs/svelte/$effect). Deriveds can be created anywhere, because they run _lazily_ and can be [garbage collected](https://developer.mozilla.org/en-US/docs/Glossary/Garbage_collection) if nothing references them. Effects, by contrast, keep running eagerly whenever their dependencies change, until they are destroyed.
+
+Because of this, effects can only be created inside other effects (or [effect roots](/docs/svelte/$effect#$effect.root), such as the one that is created when you first mount a component) so that Svelte knows when to destroy them.
+
+Some sleight of hand occurs when a derived contains an `await` expression: Since waiting until we read `{await getPromise()}` to call `getPromise` would be too late, we use an effect to instead call it proactively, notifying Svelte when the value is available. But since we're using an effect, we can only create asynchronous deriveds inside another effect.
+
 ### bind_invalid_checkbox_value
 
 ```
@@ -68,12 +80,28 @@ Effect cannot be created inside a `$derived` value that was not itself created i
 `%rune%` can only be used inside an effect (e.g. during component initialisation)
 ```
 
+### effect_pending_outside_reaction
+
+```
+`$effect.pending()` can only be called inside an effect or derived
+```
+
 ### effect_update_depth_exceeded
 
 ```
 Maximum update depth exceeded. This can happen when a reactive block or effect repeatedly sets a new value. Svelte limits the number of nested updates to prevent infinite loops
 ```
 
+### flush_sync_in_effect
+
+```
+Cannot use `flushSync` inside an effect
+```
+
+The `flushSync()` function can be used to flush any pending effects synchronously. It cannot be used if effects are currently being flushed — in other words, you can call it after a state change but _not_ inside an effect.
+
+This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
+
 ### get_abort_signal_outside_reaction
 
 ```
@@ -116,6 +144,14 @@ Rest element properties of `$props()` such as `%property%` are readonly
 The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files
 ```
 
+### set_context_after_init
+
+```
+`setContext` must be called when a component first initializes, not in a subsequent effect or after an `await` expression
+```
+
+This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
+
 ### state_descriptors_fixed
 
 ```

documentation/docs/98-reference/.generated/client-warnings.md

@@ -34,6 +34,67 @@ function add() {
 }
 ```
 
+### await_reactivity_loss
+
+```
+Detected reactivity loss when reading `%name%`. This happens when state is read in an async function after an earlier `await`
+```
+
+Svelte's signal-based reactivity works by tracking which bits of state are read when a template or `$derived(...)` expression executes. If an expression contains an `await`, Svelte transforms it such that any state _after_ the `await` is also tracked — in other words, in a case like this...
+
+```js
+let total = $derived(await a + b);
+```
+
+...both `a` and `b` are tracked, even though `b` is only read once `a` has resolved, after the initial execution.
+
+This does _not_ apply to an `await` that is not 'visible' inside the expression. In a case like this...
+
+```js
+async function sum() {
+	return await a + b;
+}
+
+let total = $derived(await sum());
+```
+
+...`total` will depend on `a` (which is read immediately) but not `b` (which is not). The solution is to pass the values into the function:
+
+```js
+async function sum(a, b) {
+	return await a + b;
+}
+
+let total = $derived(await sum(a, b));
+```
+
+### await_waterfall
+
+```
+An async derived, `%name%` (%location%) was not read immediately after it resolved. This often indicates an unnecessary waterfall, which can slow down your app
+```
+
+In a case like this...
+
+```js
+let a = $derived(await one());
+let b = $derived(await two());
+```
+
+...the second `$derived` will not be created until the first one has resolved. Since `await two()` does not depend on the value of `a`, this delay, often described as a 'waterfall', is unnecessary.
+
+(Note that if the values of `await one()` and `await two()` subsequently change, they can do so concurrently — the waterfall only occurs when the deriveds are first created.)
+
+You can solve this by creating the promises first and _then_ awaiting them:
+
+```js
+let aPromise = $derived(one());
+let bPromise = $derived(two());
+
+let a = $derived(await aPromise);
+let b = $derived(await bPromise);
+```
+
 ### binding_property_non_reactive
 
 ```

documentation/docs/98-reference/.generated/compile-errors.md

@@ -480,6 +480,12 @@ Expected token %token%
 Expected whitespace
 ```
 
+### experimental_async
+
+```
+Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless the `experimental.async` compiler option is `true`
+```
+
 ### export_undefined
 
 ```
@@ -534,6 +540,12 @@ The arguments keyword cannot be used within the template or at the top level of
 %message%
 ```
 
+### legacy_await_invalid
+
+```
+Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless in runes mode
+```
+
 ### legacy_export_invalid
 
 ```

documentation/docs/98-reference/.generated/shared-errors.md

@@ -1,5 +1,25 @@
 <!-- This file is generated by scripts/process-messages/index.js. Do not edit! -->
 
+### await_outside_boundary
+
+```
+Cannot await outside a `<svelte:boundary>` with a `pending` snippet
+```
+
+The `await` keyword can only appear in a `$derived(...)` or template expression, or at the top level of a component's `<script>` block, if it is inside a [`<svelte:boundary>`](/docs/svelte/svelte-boundary) that has a `pending` snippet:
+
+```svelte
+<svelte:boundary>
+	<p>{await getData()}</p>
+
+	{#snippet pending()}
+		<p>loading...</p>
+	{/snippet}
+</svelte:boundary>
+```
+
+This restriction may be lifted in a future version of Svelte.
+
 ### invalid_default_snippet
 
 ```

eslint.config.js

@@ -49,12 +49,13 @@ export default [
 		},
 		rules: {
 			'@typescript-eslint/await-thenable': 'error',
-			'@typescript-eslint/prefer-promise-reject-errors': 'error',
 			'@typescript-eslint/require-await': 'error',
 			'no-console': 'error',
 			'lube/svelte-naming-convention': ['error', { fixSameNames: true }],
 			// eslint isn't that well-versed with JSDoc to know that `foo: /** @type{..} */ (foo)` isn't a violation of this rule, so turn it off
 			'object-shorthand': 'off',
+			// eslint is being a dummy here too
+			'@typescript-eslint/prefer-promise-reject-errors': 'off',
 			'no-var': 'off',
 
 			// TODO: enable these rules and run `pnpm lint:fix`

packages/svelte/messages/client-errors/errors.md

@@ -1,3 +1,13 @@
+## async_derived_orphan
+
+> Cannot create a `$derived(...)` with an `await` expression outside of an effect tree
+
+In Svelte there are two types of reaction — [`$derived`](/docs/svelte/$derived) and [`$effect`](/docs/svelte/$effect). Deriveds can be created anywhere, because they run _lazily_ and can be [garbage collected](https://developer.mozilla.org/en-US/docs/Glossary/Garbage_collection) if nothing references them. Effects, by contrast, keep running eagerly whenever their dependencies change, until they are destroyed.
+
+Because of this, effects can only be created inside other effects (or [effect roots](/docs/svelte/$effect#$effect.root), such as the one that is created when you first mount a component) so that Svelte knows when to destroy them.
+
+Some sleight of hand occurs when a derived contains an `await` expression: Since waiting until we read `{await getPromise()}` to call `getPromise` would be too late, we use an effect to instead call it proactively, notifying Svelte when the value is available. But since we're using an effect, we can only create asynchronous deriveds inside another effect.
+
 ## bind_invalid_checkbox_value
 
 > Using `bind:value` together with a checkbox input is not allowed. Use `bind:checked` instead
@@ -44,10 +54,22 @@ See the [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-long
 
 > `%rune%` can only be used inside an effect (e.g. during component initialisation)
 
+## effect_pending_outside_reaction
+
+> `$effect.pending()` can only be called inside an effect or derived
+
 ## effect_update_depth_exceeded
 
 > Maximum update depth exceeded. This can happen when a reactive block or effect repeatedly sets a new value. Svelte limits the number of nested updates to prevent infinite loops
 
+## flush_sync_in_effect
+
+> Cannot use `flushSync` inside an effect
+
+The `flushSync()` function can be used to flush any pending effects synchronously. It cannot be used if effects are currently being flushed — in other words, you can call it after a state change but _not_ inside an effect.
+
+This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
+
 ## get_abort_signal_outside_reaction
 
 > `getAbortSignal()` can only be called inside an effect or derived
@@ -76,6 +98,12 @@ See the [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-long
 
 > The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files
 
+## set_context_after_init
+
+> `setContext` must be called when a component first initializes, not in a subsequent effect or after an `await` expression
+
+This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
+
 ## state_descriptors_fixed
 
 > Property descriptors defined on `$state` objects must contain `value` and always be `enumerable`, `configurable` and `writable`.

packages/svelte/messages/client-warnings/warnings.md

@@ -30,6 +30,63 @@ function add() {
 }
 ```
 
+## await_reactivity_loss
+
+> Detected reactivity loss when reading `%name%`. This happens when state is read in an async function after an earlier `await`
+
+Svelte's signal-based reactivity works by tracking which bits of state are read when a template or `$derived(...)` expression executes. If an expression contains an `await`, Svelte transforms it such that any state _after_ the `await` is also tracked — in other words, in a case like this...
+
+```js
+let total = $derived(await a + b);
+```
+
+...both `a` and `b` are tracked, even though `b` is only read once `a` has resolved, after the initial execution.
+
+This does _not_ apply to an `await` that is not 'visible' inside the expression. In a case like this...
+
+```js
+async function sum() {
+	return await a + b;
+}
+
+let total = $derived(await sum());
+```
+
+...`total` will depend on `a` (which is read immediately) but not `b` (which is not). The solution is to pass the values into the function:
+
+```js
+async function sum(a, b) {
+	return await a + b;
+}
+
+let total = $derived(await sum(a, b));
+```
+
+## await_waterfall
+
+> An async derived, `%name%` (%location%) was not read immediately after it resolved. This often indicates an unnecessary waterfall, which can slow down your app
+
+In a case like this...
+
+```js
+let a = $derived(await one());
+let b = $derived(await two());
+```
+
+...the second `$derived` will not be created until the first one has resolved. Since `await two()` does not depend on the value of `a`, this delay, often described as a 'waterfall', is unnecessary.
+
+(Note that if the values of `await one()` and `await two()` subsequently change, they can do so concurrently — the waterfall only occurs when the deriveds are first created.)
+
+You can solve this by creating the promises first and _then_ awaiting them:
+
+```js
+let aPromise = $derived(one());
+let bPromise = $derived(two());
+
+let a = $derived(await aPromise);
+let b = $derived(await bPromise);
+```
+
 ## binding_property_non_reactive
 
 > `%binding%` is binding to a non-reactive property

packages/svelte/messages/compile-errors/script.md

@@ -70,6 +70,10 @@ This turned out to be buggy and unpredictable, particularly when working with de
 
 > `$effect()` can only be used as an expression statement
 
+## experimental_async
+
+> Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless the `experimental.async` compiler option is `true`
+
 ## export_undefined
 
 > `%name%` is not defined
@@ -98,6 +102,10 @@ This turned out to be buggy and unpredictable, particularly when working with de
 
 > The arguments keyword cannot be used within the template or at the top level of a component
 
+## legacy_await_invalid
+
+> Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless in runes mode
+
 ## legacy_export_invalid
 
 > Cannot use `export let` in runes mode — use `$props()` instead

packages/svelte/messages/shared-errors/errors.md

@@ -1,3 +1,21 @@
+## await_outside_boundary
+
+> Cannot await outside a `<svelte:boundary>` with a `pending` snippet
+
+The `await` keyword can only appear in a `$derived(...)` or template expression, or at the top level of a component's `<script>` block, if it is inside a [`<svelte:boundary>`](/docs/svelte/svelte-boundary) that has a `pending` snippet:
+
+```svelte
+<svelte:boundary>
+	<p>{await getData()}</p>
+
+	{#snippet pending()}
+		<p>loading...</p>
+	{/snippet}
+</svelte:boundary>
+```
+
+This restriction may be lifted in a future version of Svelte.
+
 ## invalid_default_snippet
 
 > Cannot use `{@render children(...)}` if the parent component uses `let:` directives. Consider using a named snippet instead

packages/svelte/package.json

@@ -59,6 +59,9 @@
     "./internal/disclose-version": {
       "default": "./src/internal/disclose-version.js"
     },
+    "./internal/flags/async": {
+      "default": "./src/internal/flags/async.js"
+    },
     "./internal/flags/legacy": {
       "default": "./src/internal/flags/legacy.js"
     },