---
description: Guia detalhado de uso do modo experimental async no Svelte 5
alwaysApply: false
---
# Guia: Modo Async Experimental no Svelte 5

Este documento detalha como utilizar o modo `experimental.async` ativado neste projeto.

## 🛠 Como Habilitar

Já está configurado no seu `svelte.config.js`:

```javascript
compilerOptions: {
	experimental: {
		async: true;
	}
}
```

## 📖 Regras de Uso

### 1. Top-Level Await

Agora você pode usar `await` diretamente no seu `<script>`. O componente pausará a renderização até que a promessa seja resolvida.

**✅ Recomendado:**

```svelte
<script>
	const data = await fetch('/api/data').then((r) => r.json());
</script>

<p>{data.message}</p>
```

### 2. $derived Assíncrono

Valores derivados podem aguardar promessas. Eles se tornam reativos: se uma dependência dentro do `$derived` mudar, a promessa é disparada novamente e o valor é atualizado automaticamente.

**✅ Exemplo:**

```javascript
let id = $state(1);
let user = $derived(await getUser(id));
```

### 3. Estados de Carregamento (Loading)

Como o componente "suspende", precisamos de uma forma de mostrar que algo está carregando.

- **Para o carregamento inicial:** Use `<svelte:boundary>`.
- **Para atualizações reativas:** Use `$effect.pending()`.

```svelte
<svelte:boundary>
	<AsyncComponent />
	{#snippet pending()}
		<p>Carregando dados iniciais...</p>
	{/snippet}
</svelte:boundary>
```

---

## 🚫 O que NÃO fazer

### ❌ Async no $effect

O Svelte não permite `async` diretamente em `$effect`. Se precisar de lógica assíncrona lá, use uma IIFE (Immediately Invoked Function Expression).

**Errado:**

```javascript
$effect(async () => {
	await doSomething();
});
```

**Correto:**

```javascript
$effect(() => {
	(async () => {
		await doSomething();
	})();
});
```

### ❌ Evite Loops de Suspensão

Não use `await` em valores que mudam muitas vezes por segundo, pois isso fará o componente entrar e sair do estado de "pending" constantemente, prejudicando a UX.

---

## 🔗 Integração com Remote Functions

Este projeto usa `remoteFunctions`. A melhor forma de usá-las com o modo async é:

```svelte
<script>
	import { listItems } from './data.remote';
	let filter = $state('');

	// A query é chamada e o resultado é 'awaitado' automaticamente
	let items = $derived(await listItems({ filter }));
</script>

{#if $effect.pending()}
	<progress class="progress"></progress>
{/if}

{#each items as item}
	<div>{item.name}</div>
{/each}
```