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

@@ -74,6 +74,16 @@ Effect cannot be created inside a `$derived` value that was not itself created i
 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 +126,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,22 @@ function add() {
 }
 ```
 
+### await_reactivity_loss
+
+```
+Detected reactivity loss
+```
+
+TODO
+
+### await_waterfall
+
+```
+An async value (%location%) was not read immediately after it resolved. This often indicates an unnecessary waterfall, which can slow down your app.
+```
+
+TODO
+
 ### 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,13 @@
 <!-- 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
+```
+
+TODO
+
 ### invalid_default_snippet
 
 ```

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

@@ -48,6 +48,14 @@ See the [migration guide](/docs/svelte/v5-migration-guide#Components-are-no-long
 
 > 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 +84,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,18 @@ function add() {
 }
 ```
 
+## await_reactivity_loss
+
+> Detected reactivity loss
+
+TODO
+
+## await_waterfall
+
+> An async value (%location%) was not read immediately after it resolved. This often indicates an unnecessary waterfall, which can slow down your app.
+
+TODO
+
 ## 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,9 @@
+## await_outside_boundary
+
+> Cannot await outside a `<svelte:boundary>` with a `pending` snippet
+
+TODO
+
 ## 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"
     },

packages/svelte/src/compiler/errors.js

@@ -170,6 +170,15 @@ export function effect_invalid_placement(node) {
 	e(node, 'effect_invalid_placement', `\`$effect()\` can only be used as an expression statement\nhttps://svelte.dev/e/effect_invalid_placement`);
 }
 
+/**
+ * Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless the `experimental.async` compiler option is `true`
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function experimental_async(node) {
+	e(node, '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\`\nhttps://svelte.dev/e/experimental_async`);
+}
+
 /**
  * `%name%` is not defined
  * @param {null | number | NodeLike} node
@@ -235,6 +244,15 @@ export function invalid_arguments_usage(node) {
 	e(node, 'invalid_arguments_usage', `The arguments keyword cannot be used within the template or at the top level of a component\nhttps://svelte.dev/e/invalid_arguments_usage`);
 }
 
+/**
+ * Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless in runes mode
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function legacy_await_invalid(node) {
+	e(node, 'legacy_await_invalid', `Cannot use \`await\` in deriveds and template expressions, or at the top level of a component, unless in runes mode\nhttps://svelte.dev/e/legacy_await_invalid`);
+}
+
 /**
  * Cannot use `export let` in runes mode — use `$props()` instead
  * @param {null | number | NodeLike} node

packages/svelte/src/compiler/migrate/index.js

@@ -145,7 +145,10 @@ export function migrate(source, { filename, use_ts } = {}) {
 			...validate_component_options({}, ''),
 			...parsed_options,
 			customElementOptions,
-			filename: filename ?? '(unknown)'
+			filename: filename ?? '(unknown)',
+			experimental: {
+				async: true
+			}
 		};
 
 		const str = new MagicString(source);

packages/svelte/src/compiler/phases/1-parse/state/element.js

@@ -295,6 +295,8 @@ export default function element(parser) {
 		} else {
 			element.tag = get_attribute_expression(definition);
 		}
+
+		element.metadata.expression = create_expression_metadata();
 	}
 
 	if (is_top_level_script_or_style) {

packages/svelte/src/compiler/phases/2-analyze/index.js

@@ -1,5 +1,5 @@
-/** @import { Comment, Expression, Node, Program } from 'estree' */
-/** @import { Binding, AST, ValidatedCompileOptions, ValidatedModuleCompileOptions } from '#compiler' */
+/** @import { Expression, Node, Program } from 'estree' */
+/** @import { Binding, AST, ValidatedCompileOptions, ValidatedModuleCompileOptions, ExpressionMetadata } from '#compiler' */
 /** @import { AnalysisState, Visitors } from './types' */
 /** @import { Analysis, ComponentAnalysis, Js, ReactiveStatement, Template } from '../types' */
 import { walk } from 'zimmerframe';
@@ -22,6 +22,7 @@ import { AssignmentExpression } from './visitors/AssignmentExpression.js';
 import { AttachTag } from './visitors/AttachTag.js';
 import { Attribute } from './visitors/Attribute.js';
 import { AwaitBlock } from './visitors/AwaitBlock.js';
+import { AwaitExpression } from './visitors/AwaitExpression.js';
 import { BindDirective } from './visitors/BindDirective.js';
 import { CallExpression } from './visitors/CallExpression.js';
 import { ClassBody } from './visitors/ClassBody.js';
@@ -140,6 +141,7 @@ const visitors = {
 	AttachTag,
 	Attribute,
 	AwaitBlock,
+	AwaitExpression,
 	BindDirective,
 	CallExpression,
 	ClassBody,
@@ -211,9 +213,14 @@ function js(script, root, allow_reactive_declarations, parent) {
 		body: []
 	};
 
-	const { scope, scopes } = create_scopes(ast, root, allow_reactive_declarations, parent);
+	const { scope, scopes, has_await } = create_scopes(
+		ast,
+		root,
+		allow_reactive_declarations,
+		parent
+	);
 
-	return { ast, scope, scopes };
+	return { ast, scope, scopes, has_await };
 }
 
 /**
@@ -244,7 +251,7 @@ export function analyze_module(source, options) {
 	state.set_source(source);
 	const ast = parse(source, comments, false, false);
 
-	const { scope, scopes } = create_scopes(ast, new ScopeRoot(), false, null);
+	const { scope, scopes, has_await } = create_scopes(ast, new ScopeRoot(), false, null);
 
 	for (const [name, references] of scope.references) {
 		if (name[0] !== '$' || RESERVED.includes(name)) continue;
@@ -261,12 +268,13 @@ export function analyze_module(source, options) {
 
 	/** @type {Analysis} */
 	const analysis = {
-		module: { ast, scope, scopes },
+		module: { ast, scope, scopes, has_await },
 		name: options.filename,
 		accessors: false,
 		runes: true,
 		immutable: true,
 		tracing: false,
+		async_deriveds: new Set(),
 		comments,
 		classes: new Map()
 	};
@@ -314,7 +322,12 @@ export function analyze_component(root, source, options) {
 	const module = js(root.module, scope_root, false, null);
 	const instance = js(root.instance, scope_root, true, module.scope);
 
-	const { scope, scopes } = create_scopes(root.fragment, scope_root, false, instance.scope);
+	const { scope, scopes, has_await } = create_scopes(
+		root.fragment,
+		scope_root,
+		false,
+		instance.scope
+	);
 
 	/** @type {Template} */
 	const template = { ast: root.fragment, scope, scopes };
@@ -422,7 +435,9 @@ export function analyze_component(root, source, options) {
 
 	const component_name = get_component_name(options.filename);
 
-	const runes = options.runes ?? Array.from(module.scope.references.keys()).some(is_rune);
+	const runes =
+		options.runes ??
+		(has_await || instance.has_await || Array.from(module.scope.references.keys()).some(is_rune));
 
 	if (!runes) {
 		for (let check of synthetic_stores_legacy_check) {
@@ -512,7 +527,8 @@ export function analyze_component(root, source, options) {
 		source,
 		undefined_exports: new Map(),
 		snippet_renderers: new Map(),
-		snippets: new Set()
+		snippets: new Set(),
+		async_deriveds: new Set()
 	};
 
 	state.reset({

packages/svelte/src/compiler/phases/2-analyze/visitors/AwaitExpression.js

@@ -0,0 +1,30 @@
+/** @import { AwaitExpression } from 'estree' */
+/** @import { Context } from '../types' */
+import * as e from '../../../errors.js';
+
+/**
+ * @param {AwaitExpression} node
+ * @param {Context} context
+ */
+export function AwaitExpression(node, context) {
+	let suspend = context.state.ast_type === 'instance' && context.state.function_depth === 1;
+
+	if (context.state.expression) {
+		context.state.expression.has_await = true;
+		suspend = true;
+	}
+
+	// disallow top-level `await` or `await` in template expressions
+	// unless a) in runes mode and b) opted into `experimental.async`
+	if (suspend) {
+		if (!context.state.options.experimental.async) {
+			e.experimental_async(node);
+		}
+
+		if (!context.state.analysis.runes) {
+			e.legacy_await_invalid(node);
+		}
+	}
+
+	context.next();
+}