UI Assíncrona Declarativa no Svelte 5

Aplicações web modernas são fundamentalmente assíncronas. Os usuários esperam feedback imediato enquanto dados são carregados de APIs, arquivos são enviados para servidores e computações complexas são concluídas em segundo plano. Gerenciar essas operações assíncronas—exibir spinners de carregamento, mostrar resultados, tratar falhas—tem exigido tradicionalmente código imperativo verboso que obscurece a lógica real da UI.

O bloco #await do Svelte 5 transforma esse desafio em um padrão declarativo elegante. Em vez de rastrear manualmente estados de promise com flags booleanas e blocos try-catch, você descreve o que deve ser renderizado em cada estado diretamente no seu template. O framework gerencia a máquina de estados internamente, garantindo que sua UI sempre reflita a realidade atual de suas operações assíncronas.

Este tutorial explora o bloco #await de forma abrangente: desde padrões básicos de uso até técnicas avançadas de composição, desde a recuperação elegante de erros até atualizações otimistas de UI. Ao final, você entenderá não apenas a sintaxe, mas o modelo mental para construir interfaces assíncronas robustas.

O Problema

Gerenciando Estados de Promise de Forma Imperativa

Muitos desenvolvedores começam lidando com dados assíncronos por meio de gerenciamento manual de estado. O exemplo a seguir mostra como você pode buscar dados de usuário e rastrear os estados de carregamento, erro e resultado de forma imperativa. Essa abordagem funciona, mas rapidamente se torna verbosa e propensa a erros à medida que sua aplicação cresce.

<script>
	let user = $state(null)
	let loading = $state(true)
	let error = $state(null)

	async function fetchUser(id) {
		loading = true
		error = null
		user = null

		try {
			const response = await fetch(`/api/users/${id}`)
			if (!response.ok) throw new Error('Failed to fetch user')
			user = await response.json()
		} catch (err) {
			error = err
		} finally {
			loading = false
		}
	}

	$effect(() => {
		fetchUser(1)
	})
</script>

{#if loading}
	<div class="skeleton">Loading...</div>
{:else if error}
	<div class="error">Error: {error.message}</div>
{:else if user}
	<div class="user-card">
		<h2>{user.name}</h2>
		<p>{user.email}</p>
	</div>
{/if}

Isso funciona, mas é verboso. Você está gerenciando manualmente três partes de estado (loading, error, user) que são inerentemente conectadas. Você precisa se lembrar de redefini-las adequadamente, tratar o bloco finally corretamente e coordenar a renderização condicional. À medida que sua aplicação cresce com múltiplas operações assíncronas, esse boilerplate se multiplica.

O bloco #await elimina toda essa cerimônia.

Sintaxe Básica

Os Três Estados de uma Promise

O bloco #await do Svelte foi projetado para mapear diretamente os três estados possíveis de uma Promise JavaScript. Entender esses estados é fundamental para usar o bloco de forma eficaz.

Pendente: A operação está em andamento
Resolvida: A operação foi concluída com sucesso com um valor
Rejeitada: A operação falhou com um erro

O bloco #await mapeia diretamente para esses estados:

{#await promise}
	<!-- Pending: promise is still resolving -->
	<p>Loading...</p>
{:then value}
	<!-- Fulfilled: promise resolved successfully -->
	<p>The result is: {value}</p>
{:catch error}
	<!-- Rejected: promise was rejected -->
	<p>Error: {error.message}</p>
{/await}

Vamos ver isso em ação:

Abaixo está um exemplo prático usando o bloco #await para buscar dados de usuário. Observe como a UI é atualizada automaticamente conforme o estado da promise muda, sem gerenciamento manual de estado.

<script>
	let userId = $state(1)

	async function fetchUser(id) {
		const response = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
		if (!response.ok) throw new Error(`HTTP ${response.status}`)
		return response.json()
	}

	// Derived promise that re-fetches when userId changes
	let userPromise = $derived(fetchUser(userId))
</script>

<div class="user-selector">
	<label>
		User ID:
		<input type="number" bind:value={userId} min="1" max="10" />
	</label>
</div>

{#await userPromise}
	<div class="loading-card">
		<div class="skeleton-avatar"></div>
		<div class="skeleton-text"></div>
		<div class="skeleton-text short"></div>
	</div>
{:then user}
	<div class="user-card">
		<h2>{user.name}</h2>
		<p class="email">{user.email}</p>
		<p class="company">{user.company.name}</p>
	</div>
{:catch error}
	<div class="error-card">
		<span class="icon">⚠️</span>
		<p>Failed to load user: {error.message}</p>
		<button onclick={() => (userId = userId)}>Retry</button>
	</div>
{/await}

<style>
	.loading-card,
	.user-card,
	.error-card {
		padding: 1.5rem;
		border-radius: 8px;
		margin-top: 1rem;
	}

	.loading-card {
		background: #f1f5f9;
	}

	.skeleton-avatar {
		width: 60px;
		height: 60px;
		border-radius: 50%;
		background: linear-gradient(90deg, #e2e8f0 25%, #f1f5f9 50%, #e2e8f0 75%);
		background-size: 200% 100%;
		animation: shimmer 1.5s infinite;
	}

	.skeleton-text {
		height: 1rem;
		margin-top: 0.75rem;
		background: linear-gradient(90deg, #e2e8f0 25%, #f1f5f9 50%, #e2e8f0 75%);
		background-size: 200% 100%;
		animation: shimmer 1.5s infinite;
		border-radius: 4px;
	}

	.skeleton-text.short {
		width: 60%;
	}

	@keyframes shimmer {
		0% {
			background-position: 200% 0;
		}
		100% {
			background-position: -200% 0;
		}
	}

	.user-card {
		background: white;
		border: 1px solid #e2e8f0;
	}

	.error-card {
		background: #fef2f2;
		border: 1px solid #fecaca;
		color: #dc2626;
		text-align: center;
	}
</style>

Quando userId muda, o Svelte cria uma nova promise, e o bloco {#await} transiciona automaticamente pelos seus estados. Nenhum gerenciamento manual de estado é necessário.

Expressões Await em Templates

O Svelte 5 introduz um atalho poderoso: você pode usar await diretamente em expressões de template. Isso é especialmente útil para valores assíncronos simples onde você não precisa de estados de carregamento ou erro.

<script>
	async function getGreeting() {
		const response = await fetch('/api/greeting')
		return response.json()
	}
</script>

<!-- Shorthand: await directly in expression -->
<h1>{await getGreeting()}</h1>

<!-- Equivalent to: -->
{#await getGreeting() then greeting}
	<h1>{greeting}</h1>
{/await}

Atualizações Sincronizadas

Quando múltiplas expressões await dependem do mesmo valor assíncrono, o Svelte sincroniza suas atualizações para evitar inconsistência visual:

<script>
	async function fetchUser(id) {
		const res = await fetch(`/api/users/${id}`)
		return res.json()
	}

	let userId = $state(1)
	let userPromise = $derived(fetchUser(userId))
</script>

<!-- Both update together, not one at a time -->
<h1>Welcome, {(await userPromise).name}!</h1>
<p>Email: {(await userPromise).email}</p>

Quando Usar Qual

Padrão	Caso de Uso
`{await expr}`	Exibição simples, sem necessidade de UI de carregamento/erro
Bloco `{#await}`	Necessidade de estados de carregamento, tratamento de erros ou UI complexa

await expressions render nothing until resolved. For loading states, use the full {#await} block.

Variações de Sintaxe

Flexibilidade para Diferentes Necessidades

Nem toda operação assíncrona requer o mesmo nível de feedback na UI. Uma busca de dados críticos pode precisar de spinners de carregamento, exibição de sucesso e mensagens de erro detalhadas—enquanto uma sincronização em segundo plano pode precisar apenas de surfacear falhas. O Svelte reconhece essa realidade e fornece múltiplas formas sintáticas do bloco #await, cada uma otimizada para diferentes cenários.

Entender quando usar cada variação é fundamental para escrever código limpo e de fácil manutenção. Vamos explorar cada forma, começando pela mais abrangente e avançando para a mais mínima.

Forma Completa: Todos os Três Estados

A sintaxe completa do #await trata explicitamente os três estados da promise. Esta é a escolha ideal quando a experiência do usuário exige feedback claro em cada etapa de uma operação assíncrona.

Quando usar esta forma:

Busca de dados que os usuários estão aguardando ativamente
Operações onde falhas são prováveis e precisam de mensagens claras
Qualquer situação em que os usuários se beneficiam de saber que "algo está acontecendo"

{#await promise}
	<LoadingSpinner />
{:then data}
	<DataDisplay {data} />
{:catch error}
	<ErrorMessage {error} />
{/await}

A estrutura espelha um modelo mental de try-catch-finally: mostrar carregamento durante a tentativa, exibir resultados no sucesso, tratar erros na falha. Cada branch é mutuamente exclusiva—apenas uma é renderizada a qualquer momento.

Omitindo o Bloco Catch

Às vezes você quer tratar erros em um nível mais alto na sua árvore de componentes, em vez de inline. O componente <svelte:boundary> do Svelte fornece essa capacidade, capturando erros de qualquer componente descendente. Quando você está usando boundaries, omitir o bloco :catch mantém seus blocos await focados no caminho feliz.

Quando usar esta forma:

Você tem um error boundary envolvendo este componente
A promise genuinamente não pode ser rejeitada (raro, mas possível)
Você quer que os erros se propaguem para tratamento centralizado

{#await promise}
	<p>Computing...</p>
{:then result}
	<p>Result: {result}</p>
{/await}

If the promise rejects and you've omitted the {:catch} block, the error will propagate to the nearest <svelte:boundary> or remain unhandled. Unhandled rejections can cause confusing behavior, so use this form intentionally, not accidentally.

Omitindo o Bloco Pending

Para operações que normalmente são concluídas quase instantaneamente—como ler de um cache local ou realizar um cálculo rápido—um estado de carregamento pode, na verdade, degradar a experiência do usuário. Um spinner que aparece por 50 milissegundos parece falho. Nesses casos, não mostrar nada durante o breve estado pendente cria uma experiência mais suave.

Quando usar esta forma:

Operações que devem ser concluídas em menos de 100ms
Dados em cache que estão quase sempre disponíveis imediatamente
Conteúdo secundário onde feedback imediato não é crítico

{#await promise then value}
	<p>The answer is {value}</p>
{/await}

Este atalho não renderiza nada enquanto está pendente, depois exibe o conteúdo quando resolvido. Observe a diferença de sintaxe: then aparece na mesma linha que #await, e não há bloco pending separado.

If you're unsure whether an operation is fast enough to skip the loading state, err on the side of showing one. Users tolerate brief spinners better than wondering if something is broken.

Apenas Capturando Erros

Algumas operações são executadas silenciosamente em segundo plano—pings de analytics, prefetching, operações de auto-save. Para essas, o sucesso é a norma esperada e não precisa de reconhecimento na UI. Apenas as falhas merecem atenção do usuário.

Quando usar esta forma:

Operações de sincronização em segundo plano
Chamadas de analytics ou logging
UI otimista onde o sucesso é presumido
Prefetching de recursos para navegação futura

{#await promise catch error}
	<p class="error">Something went wrong: {error.message}</p>
{/await}

Isso não renderiza nada no sucesso—útil para operações em segundo plano onde o sucesso é a norma silenciosa. A UI permanece limpa quando as coisas funcionam, mas expõe os problemas quando ocorrem.

Aqui está um exemplo prático—um indicador de auto-save que só aparece em caso de falha:

<script>
	let content = $state('')
	let savePromise = $state(Promise.resolve())

	function autoSave() {
		savePromise = fetch('/api/save', {
			method: 'POST',
			body: JSON.stringify({ content })
		})
	}

	// Debounced auto-save on content change
	$effect(() => {
		content // track dependency
		const timer = setTimeout(autoSave, 1000)
		return () => clearTimeout(timer)
	})
</script>

<textarea bind:value={content}></textarea>

{#await savePromise catch error}
	<p class="save-error">Auto-save failed: {error.message}</p>
{/await}

Valores Não-Promise

Aqui está um comportamento que surpreende muitos desenvolvedores: o bloco #await não requer uma Promise. Se você passar um valor não-Promise, o Svelte vai direto para o branch :then com esse valor. Isso ocorre de forma síncrona, inclusive durante a renderização no lado do servidor.

Por que isso importa:

Você pode usar #await com valores que podem ou não ser assíncronos
O SSR funciona corretamente—valores não-Promise são renderizados imediatamente no servidor
Isso habilita padrões onde as fontes de dados são intercambiáveis

<script>
	let data = $state({ name: 'Already loaded' })
</script>

{#await data}
	<p>This never shows because data isn't a Promise</p>
{:then value}
	<p>{value.name}</p>
	<!-- Renders immediately -->
{/await}

Esse comportamento torna o {#await} seguro para uso com valores que podem ou não ser promises—um cenário comum quando você está abstraindo fontes de dados ou trabalhando com caches.

Exemplo prático: Um carregador de dados que retorna dados em cache de forma síncrona ou busca de forma assíncrona:

<script>
	const cache = new Map()

	function getData(id) {
		if (cache.has(id)) {
			return cache.get(id) // Returns plain object, not Promise
		}
		return fetch(`/api/data/${id}`)
			.then((r) => r.json())
			.then((data) => {
				cache.set(id, data)
				return data
			})
	}

	let itemId = $state(1)
	let dataResult = $derived(getData(itemId))
</script>

{#await dataResult}
	<p>Loading...</p>
{:then data}
	<p>{data.name}</p>
{/await}

Quando dataResult é um valor em cache, o estado de carregamento nunca aparece—os usuários veem o conteúdo imediatamente. Quando é uma busca, o estado de carregamento aparece adequadamente.

Desestruturação em Blocos Await

As cláusulas :then e :catch suportam desestruturação, permitindo a extração limpa de dados aninhados:

Desestruturação de Objetos

<script>
	async function fetchUserWithPosts(id) {
		const [userRes, postsRes] = await Promise.all([
			fetch(`/api/users/${id}`),
			fetch(`/api/users/${id}/posts`)
		])

		return {
			user: await userRes.json(),
			posts: await postsRes.json(),
			fetchedAt: new Date()
		}
	}

	let userId = $state(1)
	let dataPromise = $derived(fetchUserWithPosts(userId))
</script>

{#await dataPromise}
	<p>Loading user and posts...</p>
{:then { user, posts, fetchedAt }}
	<article>
		<header>
			<h1>{user.name}</h1>
			<time>Fetched at {fetchedAt.toLocaleTimeString()}</time>
		</header>
		<section class="posts">
			{#each posts as post}
				<div class="post">
					<h3>{post.title}</h3>
					<p>{post.body}</p>
				</div>
			{/each}
		</section>
	</article>
{:catch { message, status }}
	<div class="error">
		<p>Error {status}: {message}</p>
	</div>
{/await}

Desestruturação de Arrays

{#await fetchCoordinates()}
	<p>Getting location...</p>
{:then [latitude, longitude]}
	<p>You are at {latitude}, {longitude}</p>
{:catch error}
	<p>Location unavailable: {error.message}</p>
{/await}

Importações Dinâmicas com Desestruturação

Um padrão poderoso para divisão de código — importe componentes dinamicamente e desestruture a exportação padrão:

{#await import('./HeavyComponent.svelte') then { default: HeavyComponent }}
	<HeavyComponent someProp="value" />
{/await}

Isso adia o carregamento de HeavyComponent até que o bloco {#await} seja renderizado, reduzindo o tamanho inicial do seu bundle.

Desestruturação Aninhada com Valores Padrão

Para APIs com formatos de resposta inconsistentes:

{#await apiCall()}
	<p>Loading...</p>
{:then { items = [], meta: { total = 0 } = {} }}
	<p>Found {total} items</p>
	{#each items as item}
		<div>{item.name}</div>
	{/each}
{:catch { status = 500, message = 'Unknown error' }}
	<p>Error {status}: {message}</p>
{/await}

Os valores padrão protegem contra propriedades indefinidas em qualquer nível de aninhamento.

Promises Reativas

Re-execução Automática

Um dos padrões mais poderosos combina {#await} com $derived para criar promises que são executadas automaticamente quando as dependências mudam:

<script>
	let searchQuery = $state('')
	let category = $state('all')
	let page = $state(1)

	async function searchProducts(query, category, page) {
		const params = new URLSearchParams({
			q: query,
			category: category === 'all' ? '' : category,
			page: String(page),
			limit: '20'
		})

		const response = await fetch(`/api/products?${params}`)
		if (!response.ok) throw new Error('Search failed')
		return response.json()
	}

	// This promise re-creates whenever searchQuery, category, or page changes
	let resultsPromise = $derived(searchProducts(searchQuery, category, page))
</script>

<div class="search-controls">
	<input type="search" placeholder="Search products..." bind:value={searchQuery} />

	<select bind:value={category}>
		<option value="all">All Categories</option>
		<option value="electronics">Electronics</option>
		<option value="clothing">Clothing</option>
		<option value="books">Books</option>
	</select>
</div>

{#await resultsPromise}
	<div class="results-grid loading">
		{#each Array(6) as _}
			<div class="product-skeleton"></div>
		{/each}
	</div>
{:then { products, total, pages }}
	<p class="results-count">{total} products found</p>

	<div class="results-grid">
		{#each products as product (product.id)}
			<div class="product-card">
				<img src={product.image} alt={product.name} />
				<h3>{product.name}</h3>
				<p class="price">${product.price.toFixed(2)}</p>
			</div>
		{/each}
	</div>

	<div class="pagination">
		<button disabled={page === 1} onclick={() => page--}>Previous</button>
		<span>Page {page} of {pages}</span>
		<button disabled={page === pages} onclick={() => page++}>Next</button>
	</div>
{:catch error}
	<div class="error-state">
		<p>Search failed: {error.message}</p>
		<button onclick={() => (searchQuery = searchQuery)}>Retry</button>
	</div>
{/await}

Toda vez que qualquer filtro muda, uma nova busca é executada automaticamente. A UI faz a transição suavemente entre carregando → resultados (ou erro) sem orquestração manual.

Tratamento de Condições de Corrida

Usando AbortController

Um desafio crítico com promises reativas: quando o usuário altera as entradas rapidamente, múltiplas requisições podem estar em andamento simultaneamente. Se uma requisição mais lenta for resolvida após uma mais rápida, você exibirá dados desatualizados. A solução é o AbortController:

<script>
	let searchQuery = $state('')
	let controller = $state(null)

	async function search(query) {
		// Cancel any in-flight request
		if (controller) {
			controller.abort()
		}

		// Create new controller for this request
		controller = new AbortController()
		const { signal } = controller

		try {
			const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, { signal })

			if (!response.ok) throw new Error(`HTTP ${response.status}`)
			return response.json()
		} catch (error) {
			// Don't treat abort as an error
			if (error.name === 'AbortError') {
				// Return a never-resolving promise to prevent state update
				return new Promise(() => {})
			}
			throw error
		}
	}

	let resultsPromise = $derived(search(searchQuery))
</script>

<input type="search" bind:value={searchQuery} placeholder="Search..." />

{#await resultsPromise}
	<p>Searching...</p>
{:then results}
	{#if results.length > 0}
		<ul>
			{#each results as result}
				<li>{result.title}</li>
			{/each}
		</ul>
	{:else}
		<p>No results found</p>
	{/if}
{:catch error}
	<p class="error">{error.message}</p>
{/await}

Encapsulando AbortController em um Padrão Reutilizável

Para um código mais limpo, crie uma função utilitária:

<script>
	let searchQuery = $state('')

	function createAbortableFetcher() {
		let controller = null

		return async function abortableFetch(url, options = {}) {
			// Abort previous request
			controller?.abort()
			controller = new AbortController()

			try {
				const response = await fetch(url, {
					...options,
					signal: controller.signal
				})

				if (!response.ok) {
					throw new Error(`HTTP ${response.status}`)
				}

				return response.json()
			} catch (error) {
				if (error.name === 'AbortError') {
					// Return pending promise to "freeze" the await block
					return new Promise(() => {})
				}
				throw error
			}
		}
	}

	const abortableFetch = createAbortableFetcher()

	let resultsPromise = $derived(
		searchQuery.trim()
			? abortableFetch(`/api/search?q=${encodeURIComponent(searchQuery)}`)
			: Promise.resolve([])
	)
</script>

Debouncing de Promises Reativas

Entradas rápidas do usuário (como digitar em uma caixa de busca) podem disparar chamadas excessivas à API. Combine {#await} com debouncing para um fetching reativo eficiente:

<script>
	let searchInput = $state('')
	let debouncedQuery = $state('')

	// Debounce the search input
	$effect(() => {
		const timer = setTimeout(() => {
			debouncedQuery = searchInput
		}, 300)

		return () => clearTimeout(timer)
	})

	async function search(query) {
		if (!query.trim()) return { results: [], total: 0 }

		const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`)
		if (!response.ok) throw new Error('Search failed')
		return response.json()
	}

	// Promise only updates when debounced value changes
	let searchPromise = $derived(search(debouncedQuery))
</script>

<input type="search" placeholder="Type to search..." bind:value={searchInput} />

{#if searchInput !== debouncedQuery}
	<p class="typing-indicator">Searching...</p>
{/if}

{#await searchPromise}
	<div class="search-loading">
		<span class="spinner"></span>
	</div>
{:then { results, total }}
	{#if total > 0}
		<ul class="search-results">
			{#each results as result}
				<li>{result.title}</li>
			{/each}
		</ul>
	{:else if debouncedQuery}
		<p class="no-results">No results for "{debouncedQuery}"</p>
	{/if}
{:catch error}
	<p class="error">{error.message}</p>
{/await}

A UI exibe feedback imediato ("Buscando...") durante o debouncing, e então faz a transição para o estado de carregamento quando o fetch real começa.

Mantendo Dados Anteriores Durante o Carregamento

(Stale-While-Revalidate)

Ao atualizar dados com base na entrada do usuário, geralmente é uma UX melhor mostrar os resultados anteriores enquanto os novos carregam, em vez de um estado em branco ou um spinner. Esse padrão é conhecido como "stale-while-revalidate":

<script>
	let category = $state('electronics')
	let previousData = $state(null)

	async function fetchProducts(category) {
		const response = await fetch(`/api/products?category=${category}`)
		if (!response.ok) throw new Error('Failed to fetch')
		const data = await response.json()

		// Store successful results for next time
		previousData = data
		return data
	}

	let productsPromise = $derived(fetchProducts(category))
</script>

<select bind:value={category}>
	<option value="electronics">Electronics</option>
	<option value="clothing">Clothing</option>
	<option value="books">Books</option>
</select>

{#await productsPromise}
	<!-- Show previous data with loading indicator overlay -->
	{#if previousData}
		<div class="products-container loading">
			<div class="loading-overlay">
				<span class="spinner"></span>
				Updating...
			</div>
			<div class="products-grid stale">
				{#each previousData.products as product (product.id)}
					<div class="product-card">{product.name}</div>
				{/each}
			</div>
		</div>
	{:else}
		<div class="skeleton-grid">
			{#each Array(6) as _}
				<div class="product-skeleton"></div>
			{/each}
		</div>
	{/if}
{:then data}
	<div class="products-grid">
		{#each data.products as product (product.id)}
			<div class="product-card">{product.name}</div>
		{/each}
	</div>
{:catch error}
	<p class="error">{error.message}</p>
{/await}

<style>
	.products-container.loading {
		position: relative;
	}

	.loading-overlay {
		position: absolute;
		inset: 0;
		background: rgba(255, 255, 255, 0.8);
		display: flex;
		align-items: center;
		justify-content: center;
		gap: 0.5rem;
		z-index: 10;
	}

	.stale {
		opacity: 0.6;
		pointer-events: none;
	}
</style>

Implementação Avançada de Cache

Para um cache mais sofisticado com TTL (time-to-live) e lógica stale-while-revalidate, considere este padrão:

<script>
	const cache = new Map()
	const CACHE_TTL = 60000 // 1 minute

	async function fetchWithCache(key, fetcher) {
		const cached = cache.get(key)
		const now = Date.now()

		// Return fresh cached data immediately
		if (cached && now - cached.timestamp < CACHE_TTL) {
			return cached.data
		}

		// Fetch fresh data
		const data = await fetcher()
		cache.set(key, { data, timestamp: now })

		return data
	}

	// For stale-while-revalidate pattern
	function fetchWithSWR(key, fetcher) {
		const cached = cache.get(key)

		const freshPromise = fetcher().then((data) => {
			cache.set(key, { data, timestamp: Date.now() })
			return data
		})

		// If we have any cached data, return it immediately
		if (cached) {
			// Still fetch in background to update cache
			freshPromise.catch(() => {}) // Suppress unhandled rejection
			return cached.data
		}

		return freshPromise
	}

	let userId = $state(1)
	let userPromise = $derived(
		fetchWithSWR(`user-${userId}`, () => fetch(`/api/users/${userId}`).then((r) => r.json()))
	)
</script>

Esse padrão fornece um mecanismo de cache robusto que equilibra imediaticidade com atualização dos dados, melhorando a experiência do usuário durante as atualizações de dados.

Blocos Await Aninhados

Aplicações complexas frequentemente requerem múltiplas operações assíncronas que dependem umas das outras ou podem ser executadas em paralelo. Os blocos #await do Svelte podem ser aninhados ou combinados para lidar com esses cenários de forma limpa.

Dependências Sequenciais

Quando uma operação assíncrona depende do resultado de outra, não é possível buscar B até que A seja concluído. Nesse caso, aninhar blocos #await pode lidar com a sequência:

<script>
	async function fetchUser(id) {
		const res = await fetch(`/api/users/${id}`)
		return res.json()
	}

	async function fetchUserOrders(userId) {
		const res = await fetch(`/api/users/${userId}/orders`)
		return res.json()
	}

	async function fetchOrderDetails(orderId) {
		const res = await fetch(`/api/orders/${orderId}`)
		return res.json()
	}

	let userId = $state(1)
	let selectedOrderId = $state(null)
</script>

{#await fetchUser(userId)}
	<div class="user-loading">Loading user...</div>
{:then user}
	<div class="user-header">
		<h1>{user.name}</h1>
		<p>{user.email}</p>
	</div>

	{#await fetchUserOrders(user.id)}
		<div class="orders-loading">Loading orders...</div>
	{:then orders}
		<div class="orders-list">
			<h2>Orders ({orders.length})</h2>
			{#each orders as order}
				<button
					class="order-item"
					class:selected={selectedOrderId === order.id}
					onclick={() => (selectedOrderId = order.id)}
				>
					Order #{order.id} - ${order.total.toFixed(2)}
				</button>
			{/each}
		</div>

		{#if selectedOrderId}
			{#await fetchOrderDetails(selectedOrderId)}
				<div class="order-details-loading">Loading order details...</div>
			{:then orderDetails}
				<div class="order-details">
					<h3>Order #{orderDetails.id}</h3>
					<ul>
						{#each orderDetails.items as item}
							<li>
								{item.name} × {item.quantity} = ${(item.price * item.quantity).toFixed(2)}
							</li>
						{/each}
					</ul>
					<p class="total">Total: ${orderDetails.total.toFixed(2)}</p>
				</div>
			{:catch error}
				<p class="error">Failed to load order: {error.message}</p>
			{/await}
		{/if}
	{:catch error}
		<p class="error">Failed to load orders: {error.message}</p>
	{/await}
{:catch error}
	<p class="error">Failed to load user: {error.message}</p>
{/await}

Cada nível aguarda seu pai antes de realizar o fetch. A UI revela os dados progressivamente à medida que ficam disponíveis.

Carregamento Paralelo com `Promise.all`

Quando múltiplas operações assíncronas independentes podem ser executadas simultaneamente, use Promise.all para buscá-las em paralelo. Isso reduz o tempo total de carregamento em comparação ao fetching sequencial.

<script>
	async function fetchDashboardData() {
		const [stats, recentActivity, notifications] = await Promise.all([
			fetch('/api/stats').then((r) => r.json()),
			fetch('/api/activity').then((r) => r.json()),
			fetch('/api/notifications').then((r) => r.json())
		])

		return { stats, recentActivity, notifications }
	}

	let dashboardPromise = $derived(fetchDashboardData())
</script>

{#await dashboardPromise}
	<div class="dashboard-skeleton">
		<div class="skeleton-stats"></div>
		<div class="skeleton-activity"></div>
		<div class="skeleton-notifications"></div>
	</div>
{:then { stats, recentActivity, notifications }}
	<div class="dashboard">
		<section class="stats-panel">
			<div class="stat">
				<span class="value">{stats.totalUsers}</span>
				<span class="label">Users</span>
			</div>
			<div class="stat">
				<span class="value">${stats.revenue.toLocaleString()}</span>
				<span class="label">Revenue</span>
			</div>
			<div class="stat">
				<span class="value">{stats.activeProjects}</span>
				<span class="label">Projects</span>
			</div>
		</section>

		<section class="activity-panel">
			<h2>Recent Activity</h2>
			<ul>
				{#each recentActivity as activity}
					<li>
						<span class="user">{activity.user}</span>
						<span class="action">{activity.action}</span>
						<time>{activity.timestamp}</time>
					</li>
				{/each}
			</ul>
		</section>

		<section class="notifications-panel">
			<h2>Notifications ({notifications.unread})</h2>
			{#each notifications.items as notification}
				<div class="notification" class:unread={!notification.read}>
					<p>{notification.message}</p>
				</div>
			{/each}
		</section>
	</div>
{:catch error}
	<div class="dashboard-error">
		<p>Failed to load dashboard: {error.message}</p>
		<button onclick={() => (dashboardPromise = fetchDashboardData())}> Retry </button>
	</div>
{/await}

As três chamadas de API são executadas simultaneamente, reduzindo o tempo total de carregamento em comparação ao fetching sequencial.

Use `Promise.allSettled` para Falhas Parciais

Quando você deseja exibir o que for bem-sucedido, mesmo que algumas requisições falhem:

<script>
	async function fetchWidgetData() {
		const results = await Promise.allSettled([
			fetch('/api/weather').then((r) => r.json()),
			fetch('/api/stocks').then((r) => r.json()),
			fetch('/api/news').then((r) => r.json())
		])

		return {
			weather: results[0].status === 'fulfilled' ? results[0].value : null,
			stocks: results[1].status === 'fulfilled' ? results[1].value : null,
			news: results[2].status === 'fulfilled' ? results[2].value : null,
			errors: results.filter((r) => r.status === 'rejected').map((r) => r.reason)
		}
	}

	let widgetPromise = $derived(fetchWidgetData())
</script>

{#await widgetPromise}
	<p>Loading widgets...</p>
{:then { weather, stocks, news, errors }}
	{#if errors.length > 0}
		<div class="partial-error">Some widgets failed to load</div>
	{/if}

	<div class="widget-grid">
		{#if weather}
			<div class="widget weather">
				<h3>Weather</h3>
				<p>{weather.temperature}°F - {weather.condition}</p>
			</div>
		{:else}
			<div class="widget weather error">
				<p>Weather unavailable</p>
			</div>
		{/if}

		{#if stocks}
			<div class="widget stocks">
				<h3>Stocks</h3>
				{#each stocks.symbols as stock}
					<p>{stock.symbol}: ${stock.price}</p>
				{/each}
			</div>
		{:else}
			<div class="widget stocks error">
				<p>Stocks unavailable</p>
			</div>
		{/if}

		{#if news}
			<div class="widget news">
				<h3>News</h3>
				{#each news.headlines.slice(0, 3) as headline}
					<p>{headline}</p>
				{/each}
			</div>
		{:else}
			<div class="widget news error">
				<p>News unavailable</p>
			</div>
		{/if}
	</div>
{/await}

Este padrão fornece degradação graciosa — os usuários veem o que está disponível em vez de nada.

Blocos `#await` Independentes

Carregamento Estilo Suspense

Às vezes você quer múltiplas operações assíncronas independentes com seus próprios estados de carregamento, em vez de aguardar por todas. Isso cria uma experiência estilo "suspense" onde partes da UI aparecem assim que seus dados estão prontos:

<script>
	async function fetchUserProfile() {
		await sleep(800) // Simulate latency
		return fetch('/api/profile').then((r) => r.json())
	}

	async function fetchNotifications() {
		await sleep(400)
		return fetch('/api/notifications').then((r) => r.json())
	}

	async function fetchRecommendations() {
		await sleep(1200)
		return fetch('/api/recommendations').then((r) => r.json())
	}

	function sleep(ms) {
		return new Promise((r) => setTimeout(r, ms))
	}

	let profilePromise = $derived(fetchUserProfile())
	let notificationsPromise = $derived(fetchNotifications())
	let recommendationsPromise = $derived(fetchRecommendations())
</script>

<div class="dashboard-grid">
	<!-- Each section loads independently -->
	<section class="profile-section">
		{#await profilePromise}
			<div class="skeleton profile-skeleton"></div>
		{:then profile}
			<div class="profile-card">
				<img src={profile.avatar} alt={profile.name} />
				<h2>{profile.name}</h2>
				<p>{profile.bio}</p>
			</div>
		{:catch error}
			<p class="error">Failed to load profile</p>
		{/await}
	</section>

	<section class="notifications-section">
		{#await notificationsPromise}
			<div class="skeleton notifications-skeleton"></div>
		{:then notifications}
			<div class="notifications-list">
				<h3>Notifications ({notifications.length})</h3>
				{#each notifications as notification}
					<div class="notification">{notification.message}</div>
				{/each}
			</div>
		{:catch error}
			<p class="error">Failed to load notifications</p>
		{/await}
	</section>

	<section class="recommendations-section">
		{#await recommendationsPromise}
			<div class="skeleton recommendations-skeleton"></div>
		{:then recommendations}
			<div class="recommendations-grid">
				<h3>Recommended for You</h3>
				{#each recommendations as item}
					<div class="recommendation-card">{item.title}</div>
				{/each}
			</div>
		{:catch error}
			<p class="error">Failed to load recommendations</p>
		{/await}
	</section>
</div>

Cada seção aparece assim que seus dados estão prontos, proporcionando uma experiência de carregamento progressivo.

Transições com Blocos Await

As diretivas de transição do Svelte podem ser aplicadas aos filhos diretos de blocos #await, permitindo animações suaves entre os estados de carregamento, sucesso e erro. Isso melhora a experiência do usuário ao fornecer feedback visual durante as mudanças de estado.

<script>
	import { fade, fly, slide } from 'svelte/transition'

	let query = $state('')
	let debouncedQuery = $state('')

	$effect(() => {
		const timer = setTimeout(() => {
			debouncedQuery = query
		}, 300)
		return () => clearTimeout(timer)
	})

	async function search(q) {
		if (!q) return []
		const res = await fetch(`/api/search?q=${q}`)
		return res.json()
	}

	let searchPromise = $derived(search(debouncedQuery))
</script>

<input bind:value={query} placeholder="Search..." />

{#await searchPromise}
	<div class="loading" transition:fade={{ duration: 150 }}>
		<span class="spinner"></span>
		Searching...
	</div>
{:then results}
	{#if results.length > 0}
		<ul class="results" transition:slide={{ duration: 200 }}>
			{#each results as result, i}
				<li transition:fly={{ y: 10, delay: i * 50 }}>
					{result.title}
				</li>
			{/each}
		</ul>
	{:else if debouncedQuery}
		<p class="no-results" transition:fade>
			No results for "{debouncedQuery}"
		</p>
	{/if}
{:catch error}
	<p class="error" transition:fade>
		{error.message}
	</p>
{/await}

Transições nos filhos diretos de blocos #await funcionam melhor quando os estados possuem conteúdo distinto. Para transições mais suaves entre os estados de carregamento e carregado, considere usar #key:

{#key debouncedQuery}
	{#await searchPromise}
		<div in:fade out:fade>Loading...</div>
	{:then results}
		<div in:fade={{ delay: 150 }}>
			{#each results as result}
				<div>{result.title}</div>
			{/each}
		</div>
	{/await}
{/key}

Tratamento de Timeout

Às vezes, requisições de rede ou operações assíncronas podem demorar muito mais do que o esperado, ou até mesmo travar indefinidamente. Sem um tratamento adequado de timeout, sua UI pode ficar presa em um estado de carregamento, deixando os usuários frustrados e confusos.

É importante antecipar esses cenários e fornecer feedback ou comportamento de fallback quando as operações ultrapassam um limite de tempo razoável. Isso pode ser alcançado envolvendo suas promises com lógica de timeout.

Wrapper Simples de Timeout

Neste exemplo, criamos uma função withTimeout que rejeita uma promise se ela não for resolvida dentro de um limite de tempo especificado. Em seguida, usamos essa função para buscar dados com um timeout, fornecendo feedback ao usuário caso a requisição demore demais.

<script>
	function withTimeout(promise, ms) {
		const timeout = new Promise((_, reject) => {
			setTimeout(() => reject(new Error(`Request timed out after ${ms}ms`)), ms)
		})
		return Promise.race([promise, timeout])
	}

	async function fetchData() {
		const response = await withTimeout(
			fetch('/api/slow-endpoint'),
			5000 // 5 second timeout
		)
		return response.json()
	}

	let dataPromise = $derived(fetchData())
</script>

{#await dataPromise}
	<div class="loading">
		<span class="spinner"></span>
		<p>Loading data...</p>
		<p class="hint">This may take a few seconds</p>
	</div>
{:then data}
	<div class="data">{JSON.stringify(data)}</div>
{:catch error}
	<div class="error">
		{#if error.message.includes('timed out')}
			<p>The request is taking too long. Please try again.</p>
		{:else}
			<p>{error.message}</p>
		{/if}
		<button onclick={() => (dataPromise = fetchData())}>Retry</button>
	</div>
{/await}

Timeout Combinado com AbortController

Para um tratamento de erros robusto, muitas vezes é necessário combinar um timeout com um AbortController. Essa abordagem permite cancelar automaticamente requisições lentas e liberar recursos, garantindo que sua UI permaneça responsiva mesmo quando as condições de rede estão ruins ou o servidor não responde.

<script>
	function createFetchWithTimeout(timeoutMs = 10000) {
		return async function fetchWithTimeout(url, options = {}) {
			const controller = new AbortController()
			const timeoutId = setTimeout(() => controller.abort(), timeoutMs)

			try {
				const response = await fetch(url, {
					...options,
					signal: controller.signal
				})

				clearTimeout(timeoutId)
				return response
			} catch (error) {
				clearTimeout(timeoutId)

				if (error.name === 'AbortError') {
					throw new Error(`Request timed out after ${timeoutMs}ms`)
				}
				throw error
			}
		}
	}

	const fetchWithTimeout = createFetchWithTimeout(5000)
</script>

Estratégias de Tratamento de Erros

Tratar erros de forma elegante é essencial para construir aplicações resilientes e amigáveis ao usuário. Em fluxos assíncronos, falhas podem ocorrer por muitos motivos — problemas de rede, erros de servidor, dados inválidos ou timeouts. O bloco #await do Svelte oferece maneiras flexíveis de expor esses erros aos usuários, se recuperar de falhas e manter uma experiência fluida. Esta seção explora estratégias práticas para o tratamento de erros em cenários do mundo real.

1. Exibição de Erros Inline

A abordagem mais direta é exibir os erros diretamente onde seus dados normalmente apareceriam. Isso mantém o usuário informado sobre os problemas no contexto e permite uma lógica simples de nova tentativa.

{#await dataPromise}
	<LoadingSkeleton />
{:then data}
	<DataView {data} />
{:catch error}
	<div class="inline-error">
		<p>{error.message}</p>
		<button onclick={retry}>Try Again</button>
	</div>
{/await}

2. Limites de Erro com `<svelte:boundary>`

Para o tratamento de erros em nível de aplicação, você pode usar os limites de erro do Svelte. Esse padrão permite capturar e exibir erros de qualquer componente filho ou bloco await, fornecendo um local centralizado para recuperação de erros e registro de logs.

<script>
	let criticalDataPromise = $derived(fetchCriticalData())
</script>

<svelte:boundary onerror={(error) => logError(error)}>
	{#snippet failed(error, reset)}
		<div class="boundary-error">
			<h2>Something went wrong</h2>
			<p>{error.message}</p>
			<button onclick={reset}>Reset</button>
		</div>
	{/snippet}

	{#await criticalDataPromise}
		<p>Loading critical data...</p>
	{:then data}
		<CriticalComponent {data} />
	{/await}
	<!-- Errors will bubble up to the boundary if :catch is omitted -->
</svelte:boundary>

Usando o snippet `pending` para Carregamento Inicial

Os limites também podem exibir um estado de carregamento enquanto as expressões await são resolvidas pela primeira vez:

<svelte:boundary>
	{#snippet pending()}
		<div class="loading-overlay">
			<span class="spinner"></span>
			<p>Loading application...</p>
		</div>
	{/snippet}

	{#snippet failed(error, reset)}
		<p>Error: {error.message} <button onclick={reset}>Retry</button></p>
	{/snippet}

	<Dashboard />
</svelte:boundary>

Rastreando a Contagem de Pendentes com `$effect.pending()`

Para um controle mais granular, use $effect.pending() para saber quantas promises estão pendentes dentro de um limite:

<svelte:boundary>
	{#snippet pending()}
		<p>Loading {$effect.pending()} item(s)...</p>
	{/snippet}

	<UserProfile />
	<Notifications />
	<Recommendations />
</svelte:boundary>

O snippet pending só é exibido durante o carregamento inicial. Para atualizações assíncronas subsequentes (como a re-busca de dados), use $effect.pending() para exibir indicadores de carregamento inline.

3. Nova Tentativa com Backoff Exponencial e Feedback Visual

Às vezes, os erros de rede são temporários. Você pode melhorar a confiabilidade tentando novamente as requisições com falha automaticamente usando backoff exponencial e mostrando aos usuários qual tentativa está em andamento. Esse padrão ajuda a se recuperar de conexões instáveis e transmite confiança aos usuários de que o aplicativo está tentando resolver os problemas.

<script>
	let retryState = $state({ attempt: 0, maxAttempts: 3, isRetrying: false })

	async function fetchWithRetry(url) {
		retryState = { attempt: 0, maxAttempts: 3, isRetrying: false }
		let lastError

		for (let attempt = 1; attempt <= retryState.maxAttempts; attempt++) {
			try {
				retryState = { ...retryState, attempt, isRetrying: attempt > 1 }

				const response = await fetch(url)
				if (!response.ok) throw new Error(`HTTP ${response.status}`)

				retryState = { ...retryState, isRetrying: false }
				return response.json()
			} catch (error) {
				lastError = error

				if (attempt < retryState.maxAttempts) {
					// Exponential backoff: 1s, 2s, 4s
					const delay = Math.pow(2, attempt - 1) * 1000
					await new Promise((r) => setTimeout(r, delay))
				}
			}
		}

		retryState = { ...retryState, isRetrying: false }
		throw lastError
	}

	let dataPromise = $derived(fetchWithRetry('/api/flaky-endpoint'))
</script>

{#await dataPromise}
	<div class="loading">
		{#if retryState.isRetrying}
			<p class="retry-notice">
				Retry attempt {retryState.attempt} of {retryState.maxAttempts}...
			</p>
		{:else}
			<p>Loading...</p>
		{/if}
		<span class="spinner"></span>
	</div>
{:then data}
	<div class="data">{JSON.stringify(data)}</div>
{:catch error}
	<div class="error">
		<p>Failed after {retryState.maxAttempts} attempts: {error.message}</p>
		<button onclick={() => (dataPromise = fetchWithRetry('/api/flaky-endpoint'))}>
			Try Again
		</button>
	</div>
{/await}

<style>
	.retry-notice {
		color: #f59e0b;
		font-weight: 500;
	}
</style>

4. Objetos de Erro Tipados

Para um tratamento de erros avançado, você pode criar classes de erro personalizadas que incluem informações adicionais, como códigos de status e tipos de erro. Isso permite distinguir entre diferentes cenários de erro e exibir uma UI personalizada para cada caso, melhorando tanto a experiência do desenvolvedor quanto o feedback ao usuário.

<script>
	class ApiError extends Error {
		constructor(message, status, code) {
			super(message)
			this.status = status
			this.code = code
			this.name = 'ApiError'
		}
	}

	async function fetchData() {
		const response = await fetch('/api/data')

		if (!response.ok) {
			const body = await response.json().catch(() => ({}))
			throw new ApiError(body.message || 'Request failed', response.status, body.code || 'UNKNOWN')
		}

		return response.json()
	}

	let dataPromise = $derived(fetchData())
</script>

{#await dataPromise}
	<p>Loading...</p>
{:then data}
	<DataDisplay {data} />
{:catch error}
	{#if error instanceof ApiError}
		{#if error.status === 404}
			<NotFound message={error.message} />
		{:else if error.status === 401}
			<LoginPrompt />
		{:else if error.status === 403}
			<AccessDenied />
		{:else if error.status >= 500}
			<ServerError code={error.code} />
		{:else}
			<GenericError message={error.message} />
		{/if}
	{:else if error.name === 'TypeError' || error.message.includes('network')}
		<NetworkError />
	{:else}
		<UnexpectedError message={error.message} />
	{/if}
{/await}

Usando `@const` Dentro de Blocos Await

A diretiva @const permite definir valores computados diretamente dentro dos ramos do seu bloco await. Isso mantém seus templates limpos e facilita a derivação de estatísticas resumidas, flags ou outros auxiliares para renderizar estados de UI complexos sem poluir a seção de script.

{#await fetchOrdersPromise}
	<p>Loading orders...</p>
{:then orders}
	{@const totalValue = orders.reduce((sum, o) => sum + o.total, 0)}
	{@const pendingOrders = orders.filter((o) => o.status === 'pending')}
	{@const averageOrderValue = orders.length > 0 ? totalValue / orders.length : 0}

	<div class="orders-summary">
		<p>Total Orders: {orders.length}</p>
		<p>Total Value: ${totalValue.toFixed(2)}</p>
		<p>Average Order: ${averageOrderValue.toFixed(2)}</p>
		<p>Pending: {pendingOrders.length}</p>
	</div>

	{#each orders as order}
		{@const isHighValue = order.total > averageOrderValue * 1.5}
		<div class="order" class:high-value={isHighValue}>
			<span>Order #{order.id}</span>
			<span>${order.total.toFixed(2)}</span>
			{#if isHighValue}
				<span class="badge">High Value</span>
			{/if}
		</div>
	{/each}
{:catch error}
	{@const isNetworkError = error.message.includes('network')}
	{@const isServerError = error.status >= 500}

	<div class="error-panel">
		{#if isNetworkError}
			<p>Please check your internet connection.</p>
		{:else if isServerError}
			<p>Our servers are having issues. Please try again later.</p>
		{:else}
			<p>{error.message}</p>
		{/if}
	</div>
{/await}

Padrão de Scroll Infinito

O scroll infinito é um padrão de UX popular para carregar mais dados conforme o usuário rola a página, sem exigir paginação manual. Com o bloco #await do Svelte, você pode gerenciar os estados de carregamento e erros para cada lote de dados, proporcionando uma experiência contínua à medida que novos itens são buscados e adicionados à lista.

<script>
	let items = $state([])
	let page = $state(1)
	let hasMore = $state(true)
	let loadingMore = $state(false)
	let initialLoadPromise = $state(null)

	async function fetchPage(pageNum) {
		const response = await fetch(`/api/items?page=${pageNum}&limit=20`)
		if (!response.ok) throw new Error('Failed to fetch')
		return response.json()
	}

	async function loadInitial() {
		const data = await fetchPage(1)
		items = data.items
		hasMore = data.hasMore
		page = 1
		return data
	}

	async function loadMore() {
		if (loadingMore || !hasMore) return

		loadingMore = true
		try {
			const nextPage = page + 1
			const data = await fetchPage(nextPage)

			items = [...items, ...data.items]
			hasMore = data.hasMore
			page = nextPage
		} finally {
			loadingMore = false
		}
	}

	function handleScroll(event) {
		const { scrollTop, scrollHeight, clientHeight } = event.target
		const nearBottom = scrollHeight - scrollTop - clientHeight < 200

		if (nearBottom && hasMore && !loadingMore) {
			loadMore()
		}
	}

	// Initial load
	initialLoadPromise = loadInitial()
</script>

{#await initialLoadPromise}
	<div class="initial-loading">
		{#each Array(5) as _}
			<div class="item-skeleton"></div>
		{/each}
	</div>
{:then}
	<div class="items-container" onscroll={handleScroll}>
		{#each items as item (item.id)}
			<div class="item-card">
				<h3>{item.title}</h3>
				<p>{item.description}</p>
			</div>
		{/each}

		{#if loadingMore}
			<div class="loading-more">
				<span class="spinner"></span>
				Loading more...
			</div>
		{/if}

		{#if !hasMore && items.length > 0}
			<p class="end-message">You've reached the end!</p>
		{/if}
	</div>
{:catch error}
	<div class="error">
		<p>Failed to load items: {error.message}</p>
		<button onclick={() => (initialLoadPromise = loadInitial())}>Retry</button>
	</div>
{/await}

<style>
	.items-container {
		height: 600px;
		overflow-y: auto;
	}

	.loading-more {
		display: flex;
		align-items: center;
		justify-content: center;
		gap: 0.5rem;
		padding: 1rem;
	}

	.end-message {
		text-align: center;
		color: #6b7280;
		padding: 1rem;
	}
</style>

Atualizações Otimistas de UI

As atualizações otimistas de UI tornam seu aplicativo mais rápido ao refletir imediatamente as ações do usuário na interface, mesmo antes de o servidor responder. Essa técnica melhora o desempenho percebido e a satisfação do usuário, mas requer um tratamento cuidadoso de erros e rollbacks caso o servidor rejeite a alteração.

<script>
	let todos = $state([
		{ id: 1, text: 'Learn Svelte', completed: false },
		{ id: 2, text: 'Build an app', completed: false }
	])

	let pendingOperations = $state(new Map()) // id -> operation type

	async function toggleTodo(id) {
		const todo = todos.find((t) => t.id === id)
		const previousState = todo.completed

		// Optimistic update
		todo.completed = !todo.completed
		pendingOperations.set(id, 'toggle')
		pendingOperations = new Map(pendingOperations) // Trigger reactivity

		try {
			const response = await fetch(`/api/todos/${id}`, {
				method: 'PATCH',
				headers: { 'Content-Type': 'application/json' },
				body: JSON.stringify({ completed: todo.completed })
			})

			if (!response.ok) throw new Error('Failed to update')
		} catch (error) {
			// Revert on failure
			todo.completed = previousState
			alert('Failed to update todo. Please try again.')
		} finally {
			pendingOperations.delete(id)
			pendingOperations = new Map(pendingOperations)
		}
	}

	async function deleteTodo(id) {
		const todoIndex = todos.findIndex((t) => t.id === id)
		const deletedTodo = todos[todoIndex]

		// Optimistic update
		todos = todos.filter((t) => t.id !== id)
		pendingOperations.set(id, 'delete')
		pendingOperations = new Map(pendingOperations)

		try {
			const response = await fetch(`/api/todos/${id}`, { method: 'DELETE' })
			if (!response.ok) throw new Error('Failed to delete')
		} catch (error) {
			// Revert on failure
			todos = [...todos.slice(0, todoIndex), deletedTodo, ...todos.slice(todoIndex)]
			alert('Failed to delete todo. Please try again.')
		} finally {
			pendingOperations.delete(id)
			pendingOperations = new Map(pendingOperations)
		}
	}
</script>

<ul class="todo-list">
	{#each todos as todo (todo.id)}
		{@const isPending = pendingOperations.has(todo.id)}
		{@const operation = pendingOperations.get(todo.id)}

		<li class:completed={todo.completed} class:pending={isPending}>
			<label>
				<input
					type="checkbox"
					checked={todo.completed}
					onchange={() => toggleTodo(todo.id)}
					disabled={isPending}
				/>
				<span>{todo.text}</span>
			</label>

			<div class="actions">
				{#if isPending}
					<span class="sync-indicator">
						{operation === 'toggle' ? 'Saving...' : 'Deleting...'}
					</span>
				{:else}
					<button onclick={() => deleteTodo(todo.id)}>Delete</button>
				{/if}
			</div>
		</li>
	{/each}
</ul>

<style>
	.pending {
		opacity: 0.6;
		pointer-events: none;
	}

	.completed span {
		text-decoration: line-through;
		color: #6b7280;
	}

	.sync-indicator {
		font-size: 0.75rem;
		color: #6b7280;
		font-style: italic;
	}
</style>

Envios de Formulários com Blocos `#await`

Envios de formulários são uma fonte comum de complexidade assíncrona na UI. Usando o bloco #await do Svelte, você pode gerenciar os estados de carregamento, sucesso e erro de forma declarativa, fornecendo feedback claro aos usuários e mantendo a lógica do formulário simples e fácil de manter.

<script>
	let formData = $state({ email: '', message: '' })
	let submitState = $state('idle') // 'idle' | 'submitting' | 'success' | 'error'
	let submitPromise = $state(null)
	let submitError = $state(null)

	async function handleSubmit(event) {
		event.preventDefault()
		submitState = 'submitting'
		submitError = null

		submitPromise = fetch('/api/contact', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify(formData)
		}).then(async (response) => {
			if (!response.ok) {
				const error = await response.json()
				throw new Error(error.message || 'Submission failed')
			}
			return response.json()
		})

		try {
			await submitPromise
			submitState = 'success'
		} catch (error) {
			submitState = 'error'
			submitError = error
		}
	}

	function resetForm() {
		formData = { email: '', message: '' }
		submitState = 'idle'
		submitPromise = null
		submitError = null
	}
</script>

{#if submitState === 'idle' || submitState === 'error'}
	<form onsubmit={handleSubmit}>
		{#if submitError}
			<div class="form-error">
				{submitError.message}
			</div>
		{/if}

		<label>
			Email:
			<input type="email" bind:value={formData.email} required />
		</label>

		<label>
			Message:
			<textarea bind:value={formData.message} required></textarea>
		</label>

		<button type="submit">Send Message</button>
	</form>
{:else if submitState === 'submitting'}
	<div class="submitting">
		<span class="spinner"></span>
		<p>Sending your message...</p>
	</div>
{:else if submitState === 'success'}
	<div class="success">
		<span class="icon">✅</span>
		<h2>Message Sent!</h2>
		<p>We'll get back to you soon.</p>
		<button onclick={resetForm}>Send Another</button>
	</div>
{/if}

Padrão de Paginação

Paginação é um padrão clássico para exibir grandes conjuntos de dados em partes gerenciáveis. Com o bloco #await do Svelte, você pode lidar com estados de carregamento e erros para cada página, tornando a navegação entre páginas suave e amigável ao usuário.

<script>
	let currentPage = $state(1)
	let pageSize = $state(10)

	async function fetchPage(page, size) {
		const response = await fetch(`/api/items?page=${page}&limit=${size}`)
		if (!response.ok) throw new Error('Failed to fetch')
		return response.json()
	}

	let pagePromise = $derived(fetchPage(currentPage, pageSize))
</script>

{#await pagePromise}
	<div class="table-loading">
		{#each Array(pageSize) as _}
			<div class="row-skeleton"></div>
		{/each}
	</div>
{:then { items, total, totalPages }}
	<table>
		<thead>
			<tr>
				<th>ID</th>
				<th>Name</th>
				<th>Status</th>
			</tr>
		</thead>
		<tbody>
			{#each items as item (item.id)}
				<tr>
					<td>{item.id}</td>
					<td>{item.name}</td>
					<td>{item.status}</td>
				</tr>
			{/each}
		</tbody>
	</table>

	<div class="pagination">
		<button disabled={currentPage === 1} onclick={() => currentPage--}> Previous </button>

		<span>Page {currentPage} of {totalPages} ({total} total items)</span>

		<button disabled={currentPage === totalPages} onclick={() => currentPage++}> Next </button>
	</div>
{:catch error}
	<div class="table-error">
		<p>Failed to load data: {error.message}</p>
		<button onclick={() => (currentPage = currentPage)}>Retry</button>
	</div>
{/await}

Considerações de Acessibilidade

Acessibilidade é fundamental para tornar sua UI assíncrona utilizável por todos, incluindo pessoas que usam leitores de tela ou outras tecnologias assistivas. Ao adicionar funções ARIA e regiões ao vivo adequadas, você pode garantir que estados de carregamento, erros e atualizações de conteúdo sejam anunciados de forma clara e imediata para todos os usuários.

<script>
	let dataPromise = $derived(fetchData())
</script>

{#await dataPromise}
	<!-- Announce loading state to screen readers -->
	<div role="status" aria-live="polite" aria-busy="true" class="loading">
		<span class="spinner" aria-hidden="true"></span>
		<span class="sr-only">Loading content, please wait...</span>
		<span aria-hidden="true">Loading...</span>
	</div>
{:then data}
	<!-- Announce when content is ready -->
	<div role="region" aria-live="polite" aria-busy="false" aria-label="Content loaded">
		<DataDisplay {data} />
	</div>
{:catch error}
	<!-- Announce errors clearly -->
	<div role="alert" aria-live="assertive" class="error">
		<span class="error-icon" aria-hidden="true">⚠️</span>
		<p>Error: {error.message}</p>
		<button onclick={retry}> Retry loading </button>
	</div>
{/await}

<style>
	.sr-only {
		position: absolute;
		width: 1px;
		height: 1px;
		padding: 0;
		margin: -1px;
		overflow: hidden;
		clip: rect(0, 0, 0, 0);
		white-space: nowrap;
		border: 0;
	}
</style>

Práticas essenciais de acessibilidade:

Use role="status" para estados de carregamento, para que os leitores de tela os anunciem
Use aria-live="polite" para atualizações não críticas
Use role="alert" e aria-live="assertive" para erros
Forneça texto apenas para leitores de tela com a classe .sr-only
Use aria-busy para indicar o estado de carregamento
Garanta o gerenciamento do foco após mudanças de estado

Temporização do Estado de Carregamento

Ao lidar com operações assíncronas, a temporização dos indicadores de carregamento pode impactar significativamente a experiência do usuário. Spinners ou mensagens de carregamento mal temporizados podem resultar em uma interface desconcertante, fazendo a aplicação parecer lenta ou sem resposta. Esta seção explora estratégias para gerenciar a temporização do estado de carregamento de forma eficaz.

Evitando Oscilação da UI

Para operações rápidas, um spinner de carregamento que aparece brevemente é pior do que nenhum spinner. Implemente tempos mínimos de exibição:

<script>
	async function withMinimumDelay(promise, minMs = 400) {
		const startTime = Date.now()
		const result = await promise
		const elapsed = Date.now() - startTime

		if (elapsed < minMs) {
			await new Promise((r) => setTimeout(r, minMs - elapsed))
		}

		return result
	}

	// For operations that might be very fast
	let dataPromise = $derived(withMinimumDelay(fetchData(), 400))
</script>

{#await dataPromise}
	<LoadingSpinner />
{:then data}
	<DataDisplay {data} />
{/await}

Indicador de Carregamento com Atraso

Para operações geralmente rápidas, exiba o estado de carregamento apenas se demorar mais do que o esperado:

<script>
	let showLoading = $state(false)
	let loadingTimer = null

	async function fetchWithDelayedLoader() {
		showLoading = false

		// Only show loading after 200ms
		loadingTimer = setTimeout(() => {
			showLoading = true
		}, 200)

		try {
			const response = await fetch('/api/data')
			return response.json()
		} finally {
			clearTimeout(loadingTimer)
		}
	}

	let dataPromise = $derived(fetchWithDelayedLoader())
</script>

{#await dataPromise}
	{#if showLoading}
		<LoadingSpinner />
	{/if}
{:then data}
	<DataDisplay {data} />
{:catch error}
	<ErrorDisplay {error} />
{/await}

Armadilhas Comuns e Soluções

Ao trabalhar com blocos #await do Svelte, os desenvolvedores podem encontrar diversas armadilhas comuns que podem levar a desempenho abaixo do ideal, estados de UI confusos ou até mesmo bugs. Esta seção destaca alguns desses problemas e fornece soluções práticas para evitá-los.

1. Criando Novas Promises a Cada Renderização

Armadilha: Criar uma nova promise dentro do bloco await a cada renderização causa requisições de rede desnecessárias e quebra a reatividade.

Solução: Armazene a promise em uma variável ou estado derivado para que ela só seja atualizada quando necessário.

<!-- PREFERRED: Store the promise in a variable -->
<script>
	let dataPromise = $derived(fetch('/api/data').then((r) => r.json()))
</script>

<!-- AVOID: This creates a new promise every render cycle -->
{#await fetch('/api/data').then((r) => r.json())}
	<p>Loading...</p>
{:then data}
	<p>{data}</p>
{/await}

{#await dataPromise}
	<p>Loading...</p>
{:then data}
	<p>{data}</p>
{/await}

2. Esquecendo o Tratamento de Erros

Armadilha: Omitir o tratamento de erros em blocos await pode levar a rejeições de promise não tratadas e uma UI confusa para os usuários.

Solução: Sempre inclua um bloco {:catch} para tratar erros de forma elegante e informar o usuário.

<!-- AVOID: Unhandled rejection if promise fails -->
{#await riskyOperation() then result}
	<p>{result}</p>
{/await}

<!-- PREFERRED: Always handle potential errors -->
{#await riskyOperation()}
	<p>Loading...</p>
{:then result}
	<p>{result}</p>
{:catch error}
	<p>Error: {error.message}</p>
{/await}

3. Condições de Corrida com Atualizações Rápidas

Armadilha: Quando múltiplas requisições assíncronas são disparadas rapidamente (por exemplo, usuário digitando em uma caixa de busca), requisições mais lentas podem ser resolvidas após as mais rápidas, exibindo dados desatualizados.

Solução: Use AbortController para cancelar requisições anteriores e garantir que apenas o resultado mais recente seja exibido.

<!-- AVOID: Potential race condition -->
<script>
	let query = $state('')

	// Slow request might resolve after a faster one
	let resultsPromise = $derived(fetch(`/api/search?q=${query}`).then((r) => r.json()))
</script>

<!-- PREFERRED: Use AbortController for cancellation -->
<script>
	let query = $state('')
	let controller = null

	async function search(q) {
		// Cancel previous request
		controller?.abort()
		controller = new AbortController()

		try {
			const response = await fetch(`/api/search?q=${q}`, {
				signal: controller.signal
			})
			return response.json()
		} catch (error) {
			if (error.name === 'AbortError') {
				return new Promise(() => {}) // Never resolves
			}
			throw error
		}
	}

	let resultsPromise = $derived(search(query))
</script>

4. Não Exibindo Estado de Carregamento para Operações Rápidas

Armadilha: Operações rápidas podem fazer o spinner de carregamento piscar brevemente, resultando em uma UI instável.

Solução: Adicione um tempo mínimo de exibição para os indicadores de carregamento para garantir uma experiência de usuário suave.

<!-- PREFERRED: Add minimum display time -->
<script>
	async function withMinimumDelay(promise, minMs = 300) {
		const [result] = await Promise.all([promise, new Promise((r) => setTimeout(r, minMs))])
		return result
	}

	let dataPromise = $derived(withMinimumDelay(quickOperation()))
</script>

<!-- AVOID: Jumpy UI for fast operations -->
{#await quickOperation()}
	<FullPageSpinner /> <!-- Flashes briefly -->
{:then result}
	<p>{result}</p>
{/await}

5. Vazamentos de Memória com Desmontagem de Componentes

Armadilha: Operações assíncronas podem tentar atualizar o estado após um componente ser desmontado, causando vazamentos de memória ou erros.

Solução: Use $effect com uma função de limpeza para cancelar requisições quando o componente é desmontado ou as dependências mudam. Esta é a abordagem moderna do Svelte 5.

<script>
	let userId = $state(1)
	let userData = $state(null)
	let error = $state(null)

	// $effect automatically handles cleanup when:
	// - the component is destroyed
	// - userId changes (before re-running)
	$effect(() => {
		const controller = new AbortController()

		async function loadUser() {
			try {
				const response = await fetch(`/api/users/${userId}`, {
					signal: controller.signal
				})
				userData = await response.json()
			} catch (err) {
				// Ignore abort errors - they're expected during cleanup
				if (err.name !== 'AbortError') {
					error = err
				}
			}
		}

		loadUser()

		// Cleanup function runs before effect re-runs or on unmount
		return () => {
			controller.abort()
		}
	})
</script>

{#if error}
	<p class="error">{error.message}</p>
{:else if userData}
	<p>{userData.name}</p>
{:else}
	<p>Loading...</p>
{/if}

Para casos mais simples com promises $derived, a limpeza é automática — quando uma nova promise é criada, o Svelte para de rastrear a antiga:

<script>
	let userId = $state(1)

	// When userId changes, Svelte automatically ignores
	// the result of the previous promise
	let userPromise = $derived(fetch(`/api/users/${userId}`).then((r) => r.json()))
</script>

{#await userPromise}
	<p>Loading...</p>
{:then user}
	<p>{user.name}</p>
{:catch error}
	<p>{error.message}</p>
{/await}

6. Não Preservando a Posição de Rolagem

Armadilha: Ao navegar ou atualizar conteúdo, os usuários podem perder sua posição de rolagem, levando a uma experiência frustrante.

Solução: Use a diretiva @attach (recomendada para interações com o DOM) para restaurar e salvar a posição de rolagem, garantindo navegação suave e continuidade para os usuários.

<script>
	let scrollPosition = $state(0)

	// Attachment runs when element mounts - perfect for DOM setup
	function restoreScroll(element) {
		// Restore scroll position on mount
		if (scrollPosition > 0) {
			element.scrollTop = scrollPosition
		}

		// Save scroll position on scroll
		function handleScroll() {
			scrollPosition = element.scrollTop
		}

		element.addEventListener('scroll', handleScroll)

		// Cleanup when element unmounts
		return () => {
			element.removeEventListener('scroll', handleScroll)
		}
	}
</script>

{#await dataPromise}
	<div class="loading">Loading...</div>
{:then data}
	<!-- {@attach} is ideal here: runs on mount, has direct element access -->
	<div class="scrollable-content" {@attach restoreScroll}>
		{#each data.items as item}
			<div>{item.name}</div>
		{/each}
	</div>
{/await}

Alternativa usando $effect (quando você precisa de dependências reativas):

<script>
	let scrollPosition = $state(0)
	let container = $state(null)

	function saveScroll() {
		if (container) {
			scrollPosition = container.scrollTop
		}
	}

	// $effect is better when scroll restoration depends on other reactive state
	// e.g., if scrollPosition came from a store or needed to react to route changes
	$effect(() => {
		if (container && scrollPosition > 0) {
			container.scrollTop = scrollPosition
		}
	})
</script>

{#await dataPromise}
	<div class="loading">Loading...</div>
{:then data}
	<div bind:this={container} class="scrollable-content" onscroll={saveScroll}>
		{#each data.items as item}
			<div>{item.name}</div>
		{/each}
	</div>
{/await}

Quando usar qual:

{@attach}: Melhor para interações com o DOM autocontidas, onde o elemento é a principal preocupação
$effect: Melhor quando o comportamento depende de múltiplos valores reativos ou estado externo

Integração com Funções de Carregamento do SvelteKit

Em aplicações SvelteKit, o carregamento de dados geralmente ocorre nas funções de carregamento +page.js. O bloco #await complementa isso para operações no lado do cliente:

<!-- +page.svelte -->
<script>
	let { data } = $props() // Server-loaded data

	// Additional client-side async operations
	let recommendationsPromise = $derived(
		fetch(`/api/recommendations?based_on=${data.product.id}`).then((r) => r.json())
	)
</script>

<!-- Server data is immediately available -->
<h1>{data.product.name}</h1>
<p>{data.product.description}</p>
<p>${data.product.price}</p>

<!-- Client-side enhancement -->
<section class="recommendations">
	<h2>You Might Also Like</h2>

	{#await recommendationsPromise}
		<div class="recommendations-skeleton">
			{#each Array(4) as _}
				<div class="product-skeleton"></div>
			{/each}
		</div>
	{:then recommendations}
		<div class="recommendations-grid">
			{#each recommendations as product}
				<a href="/products/{product.slug}" class="product-card">
					<img src={product.image} alt={product.name} />
					<h3>{product.name}</h3>
					<p>${product.price}</p>
				</a>
			{/each}
		</div>
	{:catch}
		<!-- Silently fail - recommendations are nice-to-have -->
	{/await}
</section>

Integração com TypeScript

Para operações assíncronas com tipagem segura:

<script lang="ts">
	interface User {
		id: number
		name: string
		email: string
	}

	interface ApiError {
		message: string
		code: string
		status: number
	}

	async function fetchUser(id: number): Promise<User> {
		const response = await fetch(`/api/users/${id}`)
		if (!response.ok) {
			const error: ApiError = await response.json()
			throw error
		}
		return response.json()
	}

	let userId = $state(1)
	let userPromise: Promise<User> = $derived(fetchUser(userId))
</script>

{#await userPromise}
	<p>Loading...</p>
{:then user}
	<!-- user is typed as User -->
	<p>{user.name} - {user.email}</p>
{:catch error}
	<!-- error is typed as unknown by default -->
	{#if typeof error === 'object' && error !== null && 'message' in error}
		<p>{(error as ApiError).message}</p>
	{:else}
		<p>Unknown error occurred</p>
	{/if}
{/await}

Tratamento de Erros com Tipagem Segura

<script lang="ts">
	function isApiError(error: unknown): error is ApiError {
		return typeof error === 'object' && error !== null && 'status' in error && 'message' in error
	}
</script>

{#await dataPromise}
	<Loading />
{:then data}
	<DataDisplay {data} />
{:catch error}
	{#if isApiError(error)}
		<ApiErrorDisplay status={error.status} message={error.message} />
	{:else if error instanceof Error}
		<GenericError message={error.message} />
	{:else}
		<UnknownError />
	{/if}
{/await}

Resumo de Boas Práticas

Sempre trate erros — Use o bloco :catch ou envolva em um <svelte:boundary>
Armazene promessas em variáveis — Evite criar novas promessas a cada renderização
Use $derived para promessas reativas — Re-busca automática quando as dependências mudam
Debounce em entradas rápidas — Evite chamadas excessivas à API
Use AbortController — Cancele requisições obsoletas para evitar condições de corrida
Mostre estados de carregamento significativos — Telas skeleton são melhores que spinners
Considere falhas parciais — Use Promise.allSettled quando apropriado
Otimize para performance percebida — Considere atualizações otimistas
Mantenha os dados anteriores visíveis — Use padrões stale-while-revalidate
Trate timeouts — Não deixe os usuários esperando para sempre
Torne acessível — Use atributos ARIA e anúncios adequados
Tipifique suas funções assíncronas — TypeScript melhora a manutenibilidade
Use {@const} para valores computados — Mantenha os templates limpos
Gerencie o tempo dos indicadores de carregamento — Evite flickering em operações rápidas
Use cleanup do $effect para cancelamento — Padrão moderno para evitar vazamentos de memória
Aproveite o $effect.pending() — Rastreie promessas pendentes para uma UI de carregamento granular

Referência Rápida

<!-- Reactive with $derived -->
<script>
	let id = $state(1)
	let dataPromise = $derived(fetchData(id))
</script>

<!-- Full syntax -->
{#await promise}
	<!-- pending -->
{:then value}
	<!-- fulfilled -->
{:catch error}
	<!-- rejected -->
{/await}

<!-- Omit catch -->
{#await promise}
	<!-- pending -->
{:then value}
	<!-- fulfilled -->
{/await}

<!-- Omit pending -->
{#await promise then value}
	<!-- fulfilled -->
{/await}

<!-- Only catch -->
{#await promise catch error}
	<!-- rejected -->
{/await}

<!-- With destructuring -->
{#await promise then { data, meta }}
	<p>{data.title}</p>
{/await}

<!-- Array destructuring -->
{#await promise then [first, second]}
	<p>{first} and {second}</p>
{/await}

<!-- Dynamic import -->
{#await import('./Component.svelte') then { default: Component }}
	<Component />
{/await}

<!-- With @const -->
{#await promise then items}
	{@const total = items.reduce((a, b) => a + b.value, 0)}
	<p>Total: {total}</p>
{/await}

<!-- Track pending count with $effect.pending() -->
{#if $effect.pending()}
	<p>Loading {$effect.pending()} item(s)...</p>
{/if}

Conclusão

O bloco #await representa a resposta declarativa do Svelte ao desafio onipresente do gerenciamento de estado assíncrono em aplicações web modernas. Ao transformar o padrão imperativo de tratamento de promessas — com seus flags manuais de carregamento, rastreamento de estado de erro e preocupações com cleanup — em uma estrutura de template declarativa, o Svelte permite que você expresse fluxos de trabalho assíncronos complexos com notável clareza.

A integração com $effect.pending() para rastrear múltiplas promessas e o suporte à desestruturação de valores resolvidos demonstram como o Svelte 5 desenvolve essa base para lidar com padrões assíncronos cada vez mais sofisticados.

Dominar o #await exige compreender suas diversas formas: a sintaxe completa com três ramificações para estados explícitos de carregamento/sucesso/erro, as formas abreviadas para padrões comuns e a integração com as funções load do servidor do SvelteKit para dados assíncronos compatíveis com SSR.

O segredo está em reconhecer quando o tratamento assíncrono declarativo em nível de template melhora a clareza do código versus quando abordagens programáticas baseadas em $effect se encaixam melhor na sua arquitetura. Ao combinar #await com limites de erro adequados, rastreamento de estado de carregamento e estado derivado reativo, você pode criar interfaces resilientes e amigáveis ao usuário que lidam com elegância com a realidade assíncrona do desenvolvimento web moderno.

Principais Conclusões

Blocos #await tratam estados de promessa de forma declarativa com três ramificações: {#await} para pendente, {:then} para cumprida e {:catch} para promessas rejeitadas
A sintaxe abreviada omite ramificações não utilizadas - {#await promise then value} pula a UI de pendente, e {#await promise catch error} trata apenas erros
A desestruturação extrai valores resolvidos diretamente: {#await promise then { data, meta }} ou {#await promise then [first, second]} para arrays
Promessas são rastreadas automaticamente - quando a referência da promessa muda, #await reinicia para o estado pendente e aguarda a nova promessa
$effect.pending() conta promessas ativas globalmente, habilitando indicadores "carregando N itens" e rastreamento do estado de carregamento em toda a aplicação
Integração com SvelteKit via prop data - funções load retornam promessas resolvidas no servidor durante SSR e transmitidas ao cliente para hidratação
O tratamento de erros requer blocos {:catch} explícitos ou limites de erro pai - rejeições não tratadas não exibem automaticamente uma UI de erro amigável ao usuário
Gerenciamento de promessas no nível do componente com $state para controle programático, $derived para promessas computadas e $effect para efeitos colaterais na resolução

Veja Também

Documentação Oficial do Svelte 5 - {#await}
MDN Web Docs - Promises
Carregamento de Dados no SvelteKit - Carregamento de dados no servidor com funções load
$effect.pending() - Rastreamento de múltiplas promessas pendentes
$state - Estado reativo para gerenciamento de promessas
$derived - Promessas computadas a partir de dependências reativas
JavaScript async/await - Entendendo padrões assíncronos

UI Assíncrona Declarativa no Svelte 5

O Problema

Gerenciando Estados de Promise de Forma Imperativa

Sintaxe Básica

Os Três Estados de uma Promise

Expressões Await em Templates

Atualizações Sincronizadas

Quando Usar Qual

Variações de Sintaxe

Flexibilidade para Diferentes Necessidades

Forma Completa: Todos os Três Estados

Omitindo o Bloco Catch

Omitindo o Bloco Pending

Apenas Capturando Erros

Valores Não-Promise

Desestruturação em Blocos Await

Desestruturação de Objetos

Desestruturação de Arrays

Importações Dinâmicas com Desestruturação

Desestruturação Aninhada com Valores Padrão

Promises Reativas

Re-execução Automática

Tratamento de Condições de Corrida

Usando AbortController

Encapsulando AbortController em um Padrão Reutilizável

Debouncing de Promises Reativas

Mantendo Dados Anteriores Durante o Carregamento

Implementação Avançada de Cache

Blocos Await Aninhados

Dependências Sequenciais

Carregamento Paralelo com Promise.all

Use Promise.allSettled para Falhas Parciais

Blocos #await Independentes

Carregamento Estilo Suspense

Transições com Blocos Await

Tratamento de Timeout

Wrapper Simples de Timeout

Timeout Combinado com AbortController

Estratégias de Tratamento de Erros

1. Exibição de Erros Inline

2. Limites de Erro com <svelte:boundary>

Usando o snippet pending para Carregamento Inicial

Rastreando a Contagem de Pendentes com $effect.pending()

3. Nova Tentativa com Backoff Exponencial e Feedback Visual

4. Objetos de Erro Tipados

Usando @const Dentro de Blocos Await

Padrão de Scroll Infinito

Atualizações Otimistas de UI

Envios de Formulários com Blocos #await

Padrão de Paginação

Considerações de Acessibilidade

Temporização do Estado de Carregamento

Evitando Oscilação da UI

Indicador de Carregamento com Atraso

Armadilhas Comuns e Soluções

1. Criando Novas Promises a Cada Renderização

2. Esquecendo o Tratamento de Erros

3. Condições de Corrida com Atualizações Rápidas

4. Não Exibindo Estado de Carregamento para Operações Rápidas

5. Vazamentos de Memória com Desmontagem de Componentes

6. Não Preservando a Posição de Rolagem

Integração com Funções de Carregamento do SvelteKit

Integração com TypeScript

Tratamento de Erros com Tipagem Segura

Resumo de Boas Práticas

Referência Rápida

Conclusão

Principais Conclusões

Veja Também

Carregamento Paralelo com `Promise.all`

Use `Promise.allSettled` para Falhas Parciais

Blocos `#await` Independentes

2. Limites de Erro com `<svelte:boundary>`

Usando o snippet `pending` para Carregamento Inicial

Rastreando a Contagem de Pendentes com `$effect.pending()`

Usando `@const` Dentro de Blocos Await

Envios de Formulários com Blocos `#await`