O Problema de Esperar por Tudo

Considere uma página de post de blog. O próprio post é o motivo pelo qual o usuário acessou a página. Ele precisa do título, do autor, do conteúdo. A seção de comentários, a barra lateral de artigos relacionados, o painel "os leitores também gostaram" na parte inferior: esses são suplementares. Um usuário prefere ver o artigo imediatamente e esperar um momento para os comentários carregarem do que ficar olhando para uma tela em branco ou de carregamento enquanto a mais lenta de quatro chamadas de API é concluída.

O comportamento padrão de uma função de carregamento do servidor no SvelteKit é aguardar tudo antes de enviar qualquer HTML ao navegador. Se sua função de carregamento chamar quatro APIs e a mais lenta levar 800ms, o navegador não vê nada por 800ms. A página parece lenta mesmo que o conteúdo crítico estivesse pronto em 120ms.

O streaming é o mecanismo para quebrar esse acoplamento. Uma função de carregamento do servidor pode retornar alguns dados resolvidos e outros como uma Promise não resolvida. O SvelteKit envia o HTML inicial imediatamente, usando os dados resolvidos para renderizar o esqueleto da página, e então transmite os dados restantes ao navegador conforme as Promises são resolvidas. O componente lida com o estado pendente com blocos {#await}.

Este artigo aborda como o streaming funciona no SvelteKit, a mecânica precisa de Promises não resolvidas em valores de retorno de funções de carregamento, como estruturar componentes para tratar cada estado corretamente, como evitar que rejeições de Promise derrubem o servidor, quais plataformas suportam streaming e quais o bufferizam silenciosamente, e as condições em que o streaming é a ferramenta errada.

O Espaço do Problema

O padrão padrão de função de carregamento nos artigos anteriores desta série aguarda tudo antes de retornar:

// src/routes/blog/[slug]/+page.server.ts
// Standard pattern: nothing reaches the browser until all four fetches complete.

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, fetch }) => {
	const [postResponse, commentsResponse, relatedResponse, analyticsResponse] = await Promise.all([
		fetch(`/api/blog/posts/${params.slug}`),
		fetch(`/api/blog/posts/${params.slug}/comments`),
		fetch(`/api/blog/posts/${params.slug}/related`),
		fetch(`/api/analytics/post-views/${params.slug}`)
	])

	if (!postResponse.ok) {
		error(404, 'Post not found')
	}

	const [post, comments, related, analytics] = await Promise.all([
		postResponse.json(),
		commentsResponse.ok ? commentsResponse.json() : Promise.resolve([]),
		relatedResponse.ok ? relatedResponse.json() : Promise.resolve([]),
		analyticsResponse.ok ? analyticsResponse.json() : Promise.resolve(null)
	])

	return { post, comments, related, analytics }
}

Este é um bom código. Ele paraleliza as buscas e trata falhas com elegância. Mas seu tempo total de resposta do servidor é determinado pela mais lenta das quatro buscas. Se commentsResponse leva 600ms porque os comentários são armazenados em um serviço diferente com cache frio, cada usuário espera 600ms antes de ver qualquer conteúdo, incluindo o próprio post que estava pronto em 90ms.

O problema não é que as requisições sejam executadas em série. Elas são executadas em paralelo com Promise.all. O problema é que tudo espera na fronteira de serialização: o ponto onde o SvelteKit pega o valor de retorno da função de carregamento, o serializa no HTML da resposta inicial e o envia ao navegador. Essa fronteira exige que todos os valores estejam resolvidos.

O streaming remove essa restrição para dados que não são necessários para a renderização inicial.

Como o Streaming Funciona no SvelteKit

O modelo de streaming do SvelteKit se baseia em uma premissa direta: se um valor no objeto de retorno da função de carregamento for uma Promise não resolvida, o SvelteKit não espera por ela. Ele envia o HTML inicial imediatamente com os valores resolvidos no lugar, e então transmite o valor resolvido de cada Promise ao navegador pela mesma conexão HTTP conforme ela se resolve.

O mecanismo usa codificação de transferência fragmentada HTTP (chunked transfer encoding), o mesmo mecanismo que permite aos servidores enviar corpos de resposta em partes sem saber o comprimento total antecipadamente. O SvelteKit escreve o HTML inicial como o primeiro fragmento, depois escreve tags de script adicionais contendo o valor resolvido de cada Promise como fragmentos subsequentes quando eles chegam. O navegador executa essas tags de script conforme as recebe, atualizando a página sem uma navegação completa.

A experiência no navegador é progressiva. O usuário vê o post imediatamente. A barra lateral de artigos relacionados se preenche um momento depois. A seção de comentários aparece por último. Cada seção faz a transição do seu estado de carregamento para o estado preenchido de forma independente. O tempo total até a página estar totalmente interativa ainda é determinado pela busca mais lenta, mas o tempo até a página ser útil é determinado pela busca crítica mais rápida.

Retornando Promises Não Resolvidas de Funções de Carregamento

A sintaxe para streaming em uma função de carregamento do servidor é direta: retorne uma Promise em vez de um valor aguardado. Não use await na Promise antes de retorná-la.

// src/routes/blog/[slug]/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, fetch }) => {
	// The post fetch is awaited. This data is critical.
	// SvelteKit will not send any HTML until this resolves.
	// If the post does not exist, error() terminates the load function
	// before any streaming begins.
	const postResponse = await fetch(`/api/blog/posts/${params.slug}`)

	if (!postResponse.ok) {
		error(postResponse.status === 404 ? 404 : 500, 'Post not found')
	}

	const post = await postResponse.json()

	// The comments and related fetches are NOT awaited before being returned.
	// They are returned as Promises. SvelteKit will stream their results.
	// The component handles the pending state with {#await}.
	const comments = fetch(`/api/blog/posts/${params.slug}/comments`).then((response) =>
		response.ok ? response.json() : Promise.resolve([])
	)

	const related = fetch(`/api/blog/posts/${params.slug}/related?limit=3`).then((response) =>
		response.ok ? response.json() : Promise.resolve([])
	)

	return {
		post, // resolved value: rendered in initial HTML
		comments, // Promise: streamed when it settles
		related // Promise: streamed when it settles
	}
}

O tipo de retorno de comments e related aqui é Promise<SomeType[]>. O SvelteKit aceita Promises em objetos de retorno de funções de carregamento do servidor, e é isso que ativa o streaming. Os tipos TypeScript gerados em ./$types refletem isso: data.comments no componente será tipado como Promise<Comment[]>, não Comment[].

O invariante crítico a entender: o HTML inicial é enviado assim que todos os valores não-Promise no objeto de retorno estão resolvidos. A função de carregamento não se completa no sentido tradicional antes de o primeiro HTML chegar ao navegador. O SvelteKit inicia a resposta cedo e os dados de streaming são anexados à mesma resposta ao longo do tempo.

O Truque de Ordenação: Dados Críticos Primeiro

A estrutura correta para uma função de carregamento com streaming segue um princípio claro de ordenação. Busque e aguarde os dados sem os quais a página não pode ser renderizada. Retorne o restante como Promises. A divisão entre crítico e adiado não é arbitrária. Ela reflete a pergunta: o que precisa estar na tela para que a página seja útil?

Para uma página de post de blog, o próprio post é crítico. A URL mapeia para este post específico, e se ele não existir ou não puder ser carregado, a página deve mostrar um erro, não um esqueleto. Comentários e artigos relacionados são suplementares. A página é útil sem eles.

// src/routes/blog/[slug]/+page.server.ts
// Full implementation with correct ordering.

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'
import type { BlogPost, Comment, RelatedArticle } from '$lib/types/blog'

export const load: PageServerLoad = async ({ params, locals, fetch }) => {
	// Phase 1: Critical data. Await this before anything else.
	// If this fails, error() stops execution and no HTML is sent.
	const postResponse = await fetch(`/api/blog/posts/${params.slug}`)

	if (postResponse.status === 404) {
		error(404, `The article "${params.slug}" does not exist.`)
	}

	if (!postResponse.ok) {
		error(500, 'Failed to load article.')
	}

	const post: BlogPost = await postResponse.json()

	// Phase 2: Start deferred fetches immediately after the critical data resolves.
	// These run in parallel on the server. The browser receives the initial HTML
	// while these are still in flight. Each resolves and is streamed independently.

	// Attach the error fallback inside the Promise chain here, not in the component.
	// This ensures the component always receives the same shape of data
	// regardless of whether the fetch succeeded or failed.
	const comments: Promise<Comment[]> = fetch(`/api/blog/posts/${params.slug}/comments`)
		.then((response) => {
			if (!response.ok) return []
			return response.json()
		})
		.catch(() => [])

	const related: Promise<RelatedArticle[]> = fetch(`/api/blog/posts/${params.slug}/related?limit=3`)
		.then((response) => {
			if (!response.ok) return []
			return response.json()
		})
		.catch(() => [])

	// Phase 3: Return immediately.
	// 'post' is a resolved value. It becomes part of the initial HTML.
	// 'comments' and 'related' are Promises. They stream when they settle.
	return {
		post,
		comments,
		related
	}
}

O timing desta estrutura importa precisamente. As buscas adiadas iniciam na Fase 2, imediatamente após os dados críticos serem resolvidos. Elas não iniciam após o retorno. No momento em que o SvelteKit começa a escrever o fragmento HTML inicial, as buscas adiadas já estão em andamento no servidor. O intervalo entre "HTML inicial enviado" e "dados adiados chegam" é apenas tão longo quanto as buscas adiadas levam, não tão longo quanto essas buscas mais o tempo para enviar o HTML inicial.

Se as buscas adiadas fossem iniciadas de forma preguiçosa, o benefício do streaming seria reduzido. Iniciá-las antes do retorno garante que elas estejam sendo executadas de forma concorrente com a transmissão de rede do HTML inicial.

Tratando Estados de Streaming em Componentes

O contraparte do componente para uma Promise transmitida é o bloco {#await}. O bloco {#await} do Svelte trata três estados:

Estado pendente - enquanto a Promise não está resolvida
Estado de sucesso - com o valor resolvido
Estado de erro - se a Promise for rejeitada.

<!-- src/routes/blog/[slug]/+page.svelte -->

<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
</script>

<article class="post">
	<!-- Critical data: rendered in initial HTML, always available synchronously. -->
	<header>
		<h1>{data.post.title}</h1>
		<p class="byline">By {data.post.author.name}</p>
		<time datetime={data.post.publishedAt}>{data.post.publishedAt}</time>
	</header>

	<!-- post.body is sanitized server-side before storage -->
	<div class="post-body">{@html data.post.body}</div>

	<!-- Deferred data: data.comments is a Promise.
	     The three states of {#await} give users a clear progressive experience. -->
	<section class="comments">
		<h2>Comments</h2>

		{#await data.comments}
			<!-- Pending state: shown while the Promise is unresolved.
			     Use skeleton UI rather than a spinner for content-shaped loading states.
			     The user can read the article while this resolves. -->
			<ul class="comment-list skeleton" aria-label="Loading comments">
				{#each [1, 2, 3] as n (n)}
					<li class="comment skeleton-row"></li>
				{/each}
			</ul>
		{:then comments}
			<!-- Success state: the Promise resolved with the comments array. -->
			{#if comments.length === 0}
				<p class="no-comments">No comments yet. Be the first to respond.</p>
			{:else}
				<ul class="comment-list">
					{#each comments as comment (comment.id)}
						<li class="comment">
							<strong class="comment-author">{comment.author}</strong>
							<p class="comment-body">{comment.body}</p>
							<time datetime={comment.createdAt}>{comment.createdAt}</time>
						</li>
					{/each}
				</ul>
			{/if}
		{:catch}
			<!-- Error state: shown if the Promise rejects.
			     This should only appear if the load function's .catch() fallback
			     was not applied, or if you intentionally allow rejections. -->
			<p class="error">Comments could not be loaded. Please refresh to try again.</p>
		{/await}
	</section>

	<aside class="related-sidebar">
		<h2>Related Articles</h2>

		{#await data.related}
			<ul class="related-list skeleton">
				{#each [1, 2, 3] as n (n)}
					<li class="skeleton-row"></li>
				{/each}
			</ul>
		{:then related}
			{#if related.length === 0}
				<p>No related articles found.</p>
			{:else}
				<ul class="related-list">
					{#each related as article (article.slug)}
						<li>
							<a href="/blog/{article.slug}">{article.title}</a>
							<span class="reading-time">{article.readingTimeMinutes} min read</span>
						</li>
					{/each}
				</ul>
			{/if}
		{:catch}
			<p class="error">Related articles could not be loaded.</p>
		{/await}
	</aside>
</article>

O bloco {:catch} em cada {#await} não é opcional quando você se preocupa com confiabilidade. Se uma Promise transmitida for rejeitada e não houver bloco {:catch}, o Svelte silenciosamente não faz nada na área do estado pendente. A UI do esqueleto permanece visível indefinidamente, o que é uma experiência confusa que parece um estado de carregamento travado. Sempre inclua {:catch} para Promises transmitidas, mesmo que a mensagem seja breve.

O UI do estado pendente merece um esforço de design genuíno. Um esqueleto que corresponde à forma do conteúdo que está aguardando é muito melhor do que um spinner ou uma área em branco. O olho do usuário se fixa no esqueleto enquanto lê o artigo, e a transição do esqueleto para o conteúdo é suave e pouco surpreendente. Um spinner em uma barra lateral cria um ponto focal que compete com o conteúdo que o usuário veio ler.

Tratando Rejeições com Segurança

Rejeições de Promise não tratadas em um contexto de streaming têm consequências além de mostrar uma UI quebrada. Se uma Promise rejeitada se propagar para a camada de streaming do SvelteKit sem ser capturada, pode resultar em um erro de rejeição não tratada no lado do servidor. Dependendo da sua versão do Node.js e da configuração de implantação, rejeições não tratadas podem encerrar o processo ou acionar um evento de erro que seu sistema de monitoramento irá alertar.

A regra é simples: toda Promise retornada de uma função de carregamento com streaming deve ter um handler .catch() anexado antes de ser retornada. O handler .catch() converte a rejeição em um valor resolvido, um fallback seguro que o componente pode renderizar corretamente.

// Avoid: returning a raw fetch Promise with no error handling.
// If the API is down or returns a non-200, this rejects.
// The rejection may propagate as an unhandled rejection on the server.

const comments = fetch(`/api/blog/posts/${params.slug}/comments`).then((response) =>
	response.json()
)

// Preferred: chain .catch() to guarantee the Promise always resolves.
// The component receives an empty array on failure, not a rejection.
// The error is logged server-side where it can be acted on.

const comments = fetch(`/api/blog/posts/${params.slug}/comments`)
	.then((response) => {
		if (!response.ok) {
			console.error(`Comments API returned ${response.status} for ${params.slug}`)
			return []
		}
		return response.json()
	})
	.catch((err) => {
		console.error('Comments fetch failed:', err)
		return []
	})

O catch em dois estágios aqui (verificando response.ok antes de .json() e um .catch() separado para falhas no nível de rede) trata ambas as categorias de falha. A verificação de response.ok captura erros HTTP como 500 ou 503. O .catch() captura erros de rede como falhas de DNS, resets de conexão e timeouts. Ambos são reais em produção.

Algumas equipes preferem envolver cada busca adiada em um helper que padroniza o comportamento de fallback:

// src/lib/server/streaming.ts
// A helper for fetches that should stream with a safe fallback on failure.

async function streamFetch<T>(
	fetchPromise: Promise<Response>,
	fallback: T,
	label: string
): Promise<T> {
	return fetchPromise
		.then((response) => {
			if (!response.ok) {
				console.error(`[stream] ${label} returned ${response.status}`)
				return fallback
			}
			return response.json() as Promise<T>
		})
		.catch((err) => {
			console.error(`[stream] ${label} failed:`, err)
			return fallback
		})
}

export { streamFetch }

// src/routes/blog/[slug]/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'
import { streamFetch } from '$lib/server/streaming'
import type { Comment, RelatedArticle } from '$lib/types/blog'

export const load: PageServerLoad = async ({ params, fetch }) => {
	const postResponse = await fetch(`/api/blog/posts/${params.slug}`)

	if (!postResponse.ok) {
		error(postResponse.status === 404 ? 404 : 500, 'Post not found')
	}

	const post = await postResponse.json()

	// streamFetch wraps the fetch Promise with consistent error handling.
	// The type parameter and fallback make the contract explicit.
	const comments = streamFetch<Comment[]>(
		fetch(`/api/blog/posts/${params.slug}/comments`),
		[],
		`comments:${params.slug}`
	)

	const related = streamFetch<RelatedArticle[]>(
		fetch(`/api/blog/posts/${params.slug}/related?limit=3`),
		[],
		`related:${params.slug}`
	)

	return { post, comments, related }
}

O helper streamFetch torna a intenção explícita no local da chamada: esta busca é adiada, seu modo de falha é um fallback conhecido, e a falha será registrada com um rótulo que a identifica no seu sistema de logging. O componente não precisa de um bloco {:catch} que seja acessível na prática, porque streamFetch garante a resolução, mas incluir {:catch} como medida defensiva ainda é uma boa prática.

Exemplo Prático: Um Painel de Usuário com Streaming em Camadas

Um painel de usuário é um caso de uso canônico para streaming. Painéis tipicamente combinam uma pequena quantidade de informações críticas de identidade (quem é o usuário, seu status de conta) com vários painéis de dados secundários (feed de atividade, notificações, recomendações, estatísticas de uso). Os dados críticos são rápidos. Os dados secundários variam amplamente em latência dependendo da sua origem.

Definições de tipo

// src/lib/types/dashboard.ts

export interface Account {
	id: string
	name: string
	email: string
	plan: 'free' | 'pro' | 'enterprise'
	balance: number
}

export interface ActivityItem {
	id: string
	description: string
	occurredAt: string
	type: 'login' | 'purchase' | 'export' | 'update'
}

export interface Notification {
	id: string
	title: string
	body: string
	read: boolean
	createdAt: string
}

export interface Recommendation {
	id: string
	title: string
	url: string
	reason: string
}

export interface UsageStat {
	label: string
	value: number
	unit: string
	percentageOfLimit: number
}

O carregamento do servidor do painel

// src/routes/dashboard/+page.server.ts

import type { PageServerLoad } from './$types'
import { redirect, error } from '@sveltejs/kit'
import type {
	Account,
	ActivityItem,
	Notification,
	Recommendation,
	UsageStat
} from '$lib/types/dashboard'

export const load: PageServerLoad = async ({ locals, fetch }) => {
	// Authentication guard. Not inside a try/catch.
	// See Article 8 on why redirect() must not be wrapped in try/catch.
	if (!locals.user) {
		redirect(303, '/login?returnTo=/dashboard')
	}

	// Phase 1: Critical data.
	// The dashboard cannot render without the account details.
	// Await this before returning anything.
	const accountResponse = await fetch(`/api/users/${locals.user.id}/account`)

	if (!accountResponse.ok) {
		error(500, 'Failed to load account information.')
	}

	const account: Account = await accountResponse.json()

	// Phase 2: Deferred data. Start all deferred fetches immediately
	// so they run concurrently while the initial HTML is being sent.
	// Each one handles its own failure and resolves to a safe fallback.

	const recentActivity: Promise<ActivityItem[]> = fetch(
		`/api/users/${locals.user.id}/activity?limit=10`
	)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	const notifications: Promise<Notification[]> = fetch(
		`/api/users/${locals.user.id}/notifications?unread=true`
	)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	const recommendations: Promise<Recommendation[]> = fetch(
		`/api/users/${locals.user.id}/recommendations`
	)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	const usageStats: Promise<UsageStat[]> = fetch(`/api/users/${locals.user.id}/usage`)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	// Return immediately. 'account' is resolved and in the initial HTML.
	// The four Promise values stream individually as they settle.
	return {
		account,
		recentActivity,
		notifications,
		recommendations,
		usageStats
	}
}

O componente do painel

<!-- src/routes/dashboard/+page.svelte -->

<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()

	// Derived from the resolved account. This is synchronous because
	// 'account' is a resolved value, not a Promise.
	const isProOrEnterprise = $derived(
		data.account.plan === 'pro' || data.account.plan === 'enterprise'
	)
</script>

<div class="dashboard">
	<!-- Critical section: rendered in initial HTML. -->
	<header class="dashboard-header">
		<h1>Welcome back, {data.account.name}</h1>
		<p class="plan-badge">{data.account.plan} plan</p>
	</header>

	<div class="dashboard-grid">
		<!-- Notifications panel -->
		<section class="panel notifications-panel">
			<h2>Notifications</h2>
			{#await data.notifications}
				<div class="panel-loading" aria-label="Loading notifications">
					<div class="skeleton-row"></div>
					<div class="skeleton-row"></div>
				</div>
			{:then notifications}
				{#if notifications.length === 0}
					<p class="empty-state">You are all caught up.</p>
				{:else}
					<ul class="notification-list">
						{#each notifications as notification (notification.id)}
							<li class="notification" class:unread={!notification.read}>
								<strong>{notification.title}</strong>
								<p>{notification.body}</p>
							</li>
						{/each}
					</ul>
				{/if}
			{:catch}
				<p class="panel-error">Notifications unavailable.</p>
			{/await}
		</section>

		<!-- Recent activity panel -->
		<section class="panel activity-panel">
			<h2>Recent Activity</h2>
			{#await data.recentActivity}
				<ul class="activity-list skeleton">
					{#each [1, 2, 3, 4, 5] as n (n)}
						<li class="activity-item skeleton-row"></li>
					{/each}
				</ul>
			{:then items}
				{#if items.length === 0}
					<p class="empty-state">No recent activity to show.</p>
				{:else}
					<ul class="activity-list">
						{#each items as item (item.id)}
							<li class="activity-item activity-type-{item.type}">
								<span class="activity-description">{item.description}</span>
								<time datetime={item.occurredAt}>{item.occurredAt}</time>
							</li>
						{/each}
					</ul>
				{/if}
			{:catch}
				<p class="panel-error">Activity feed unavailable.</p>
			{/await}
		</section>

		<!-- Usage statistics panel (pro/enterprise only) -->
		{#if isProOrEnterprise}
			<section class="panel usage-panel">
				<h2>Usage</h2>
				{#await data.usageStats}
					<div class="usage-skeleton">
						{#each [1, 2, 3] as n (n)}
							<div class="stat-skeleton"></div>
						{/each}
					</div>
				{:then stats}
					<ul class="usage-list">
						{#each stats as stat (stat.label)}
							<li class="usage-stat">
								<span class="stat-label">{stat.label}</span>
								<span class="stat-value">{stat.value} {stat.unit}</span>
								<div class="stat-bar">
									<div
										class="stat-fill"
										style:width="{Math.min(stat.percentageOfLimit, 100)}%"
									></div>
								</div>
							</li>
						{/each}
					</ul>
				{:catch}
					<p class="panel-error">Usage data unavailable.</p>
				{/await}
			</section>
		{/if}

		<!-- Recommendations panel -->
		<section class="panel recommendations-panel">
			<h2>Recommended for You</h2>
			{#await data.recommendations}
				<div class="recommendations-skeleton">
					{#each [1, 2] as n (n)}
						<div class="rec-skeleton"></div>
					{/each}
				</div>
			{:then recs}
				{#if recs.length === 0}
					<p class="empty-state">Check back soon for personalized recommendations.</p>
				{:else}
					<ul class="recommendation-list">
						{#each recs as rec (rec.id)}
							<li class="recommendation">
								<a href={rec.url}>{rec.title}</a>
								<p class="rec-reason">{rec.reason}</p>
							</li>
						{/each}
					</ul>
				{/if}
			{:catch}
				<p class="panel-error">Recommendations unavailable.</p>
			{/await}
		</section>
	</div>
</div>

A chamada $derived em isProOrEnterprise funciona corretamente aqui porque data.account é um valor resolvido, não uma Promise. Derivações reativas de dados resolvidos funcionam exatamente como em qualquer outra página. Derivações reativas de dados de Promise requerem aninhar o $derived dentro de um bloco {:then} resolvido ou armazenar o valor resolvido em uma variável $state, o que complica as coisas.

Mantenha dados resolvidos e dados transmitidos como preocupações separadas quando possível: derive a partir de dados resolvidos no bloco de script, e deixe {#await} tratar toda a renderização dependente de Promise.

Suporte de Plataforma: Onde o Streaming Realmente Funciona

O streaming via codificação de transferência fragmentada requer que a conexão HTTP entre o navegador e o servidor permaneça aberta enquanto o servidor envia dados em partes. Esse é o comportamento padrão em implantações diretas com Node.js ou Deno. Não é universal em todas as plataformas de implantação e configurações de proxy.

Adaptador Node.js (@sveltejs/adapter-node): Suporte completo. A codificação de transferência fragmentada é nativa ao HTTP do Node.js. O streaming funciona conforme descrito.

Cloudflare Workers (@sveltejs/adapter-cloudflare): Suporte completo. O runtime do Cloudflare Workers suporta a API Web Streams, que o SvelteKit usa em plataformas de edge. O streaming funciona.

Vercel (@sveltejs/adapter-vercel): Suportado com a opção streaming: true na configuração do adaptador. Sem essa flag, o adaptador bufferiza a resposta. Defina-a explicitamente:

// svelte.config.js

import adapter from '@sveltejs/adapter-vercel'

const config = {
	kit: {
		adapter: adapter({
			// Enable streaming. Without this, SvelteKit deferred Promises
			// are buffered by the adapter and sent as a single response.
			streaming: true
		})
	}
}

export default config

AWS Lambda (via @sveltejs/adapter-node atrás do API Gateway ou Lambda Function URLs): Problemático. O API Gateway historicamente bufferiza respostas, impedindo que a codificação de transferência fragmentada funcione de ponta a ponta. As Lambda Function URLs têm melhor suporte para streaming de resposta ao usar o modo de invocação RESPONSE_STREAM, mas isso requer configuração explícita e não é o padrão. Ao implantar no Lambda atrás do API Gateway, teste o comportamento de streaming explicitamente e assuma que pode ser bufferizado.

Firebase Hosting com Cloud Functions: O Firebase Hosting atua como uma CDN que bufferiza as respostas de funções antes de entregá-las. O streaming de dados de Cloud Functions através do Firebase Hosting não funciona. A CDN coleta a resposta inteira antes de encaminhá-la. Se você usar Firebase Functions diretamente (contornando o Hosting para rotas de API), o streaming é tecnicamente possível, mas requer configuração cuidadosa.

NGINX como proxy reverso: O NGINX bufferiza respostas upstream por padrão. A diretiva proxy_buffering off deve ser definida para o bloco de localização específico para permitir que o streaming passe:

location / {
    proxy_pass http://sveltekit_upstream;
    proxy_buffering off;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding on;
}

Sem proxy_buffering off, o NGINX coleta a resposta inteira do servidor SvelteKit antes de encaminhá-la ao navegador. A experiência do usuário é idêntica à de não usar streaming. As Promises adiadas ainda são resolvidas e enviadas, mas chegam ao navegador todas de uma vez após a mais lenta se resolver. O benefício do streaming é perdido.

O teste prático: A maneira mais confiável de verificar que o streaming está realmente funcionando de ponta a ponta na sua implantação é adicionar uma Promise adiada com um atraso conhecido e observar se o HTML inicial chega antes que o atraso seja concluído:

// Temporary diagnostic: add a deliberately slow deferred value.
// If streaming works, the page shell appears before the 2-second delay.
// If streaming is buffered, nothing appears until after 2 seconds.

const diagnosticStream = new Promise<string>((resolve) => {
	setTimeout(() => resolve('stream confirmed'), 2000)
})

return {
	post,
	comments,
	related,
	// Remove this before deploying to production.
	diagnosticStream
}

Streaming e o Bloco `{#await}` Durante a Navegação do Cliente

Uma distinção comportamental importante: durante a navegação do lado do cliente (quando o usuário clica em um link e o SvelteKit navega sem um carregamento completo da página), o streaming se comporta de forma diferente de uma requisição SSR completa.

Durante a navegação do cliente, a função de carregamento do servidor é executada no servidor, mas a resposta é enviada ao navegador como um objeto JSON em vez de fragmentos HTML. O SvelteKit resolve todas as Promises no servidor antes de enviar a resposta JSON ao cliente. O cliente recebe todos os dados de uma vez e os usa para atualizar a página.

Isso significa que o estado pendente do bloco {#await} não é exibido durante a navegação do cliente quando uma função de carregamento do servidor está envolvida. O navegador não vê latência para os dados adiados durante as transições porque o servidor resolve tudo antes de responder. O benefício do streaming é uma otimização exclusiva da renderização do lado do servidor.

Isso não é uma falha. É um comportamento adequado. Carregamentos de página completos são o caminho lento onde o streaming oferece mais valor. Navegações do cliente já são rápidas porque o navegador tem o shell da página e o runtime JavaScript carregados. O round trip extra para resolver Promises no servidor antes de enviar o JSON é um custo aceitável pela simplicidade do modelo de navegação do cliente.

A consequência para o design de componentes: o estado pendente de cada bloco {#await} é primariamente uma preocupação de renderização no servidor. Projete skeletons e estados de carregamento pensando na experiência do primeiro carregamento, não na experiência de transição.

Erros Comuns e Anti-Padrões

Aguardar Promises diferidas antes de retornar

// Avoid: awaiting the deferred data before returning eliminates the streaming benefit.
// The load function waits for all four fetches before sending any HTML.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const postResponse = await fetch(`/api/posts/${params.slug}`)
	const post = await postResponse.json()

	// These are awaited. No streaming. Total time = max(comments, related).
	const comments = await fetch(`/api/posts/${params.slug}/comments`).then((response) =>
		response.json()
	)
	const related = await fetch(`/api/posts/${params.slug}/related`).then((response) =>
		response.json()
	)

	return { post, comments, related }
}

// Preferred: return Promises directly. Do not await deferred data.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const postResponse = await fetch(`/api/posts/${params.slug}`)
	const post = await postResponse.json()

	const comments = fetch(`/api/posts/${params.slug}/comments`)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	const related = fetch(`/api/posts/${params.slug}/related`)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	return { post, comments, related }
}

Fazer streaming de dados críticos que `error()` precisa proteger

// Avoid: streaming the post itself.
// If the post does not exist, there is no way to call error() after returning.
// The component will receive a rejected Promise or an empty value
// and have no way to show a 404 page.
export const load: PageServerLoad = async ({ params, fetch }) => {
	// Do not stream the resource that determines whether the page is valid.
	const post = fetch(`/api/posts/${params.slug}`).then((response) => response.json())

	return { post }
}

// Preferred: await critical data so error() can be called if needed.
// Only defer data that is genuinely supplementary.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const postResponse = await fetch(`/api/posts/${params.slug}`)

	if (!postResponse.ok) {
		error(postResponse.status === 404 ? 404 : 500, 'Post not found')
	}

	const post = await postResponse.json()
	const comments = fetch(`/api/posts/${params.slug}/comments`)
		.then((response) => (response.ok ? response.json() : []))
		.catch(() => [])

	return { post, comments }
}

Se o recurso que define a página (o post, o produto, o perfil do usuário) é transmitido via streaming e seu fetch falha, o componente está em um estado irrecuperável: não pode exibir a página porque não há conteúdo, e não pode exibir uma página de erro adequada porque error() nunca foi chamado. Sempre aguarde o recurso do qual a identidade da página depende.

Omitir completamente o `{#await}` ou deixar de fora o `{:catch}`

<!-- Avoid: treating streamed data as if it were resolved. -->
<!-- data.comments is a Promise. Accessing .length on a Promise is undefined. -->

<script lang="ts">
	let { data } = $props()
</script>

<ul>
	{#each data.comments as comment (comment.id)}
		<li>{comment.body}</li>
	{/each}
</ul>

<!-- Preferred: use {#await} to handle all three states. -->
<!-- Including {:catch} protects against stuck loading states. -->

{#await data.comments}
	<p>Loading comments...</p>
{:then comments}
	<ul>
		{#each comments as comment (comment.id)}
			<li>{comment.body}</li>
		{/each}
	</ul>
{:catch}
	<p>Comments could not be loaded.</p>
{/await}

O TypeScript detectará o primeiro erro na maioria dos casos porque data.comments é tipado como Promise<Comment[]>, não Comment[]. O bloco {#each} espera um array e o TypeScript reclamará. Mas o TypeScript não detectará isso se a anotação de tipo for genérica ou estiver ausente, portanto a disciplina com {#await} importa independentemente da cobertura do TypeScript.

Quando NÃO Usar Streaming

Streaming é uma otimização direcionada. Não é apropriado em todas as situações.

Funções de load universais não podem fazer streaming. O streaming requer a capacidade de escrever chunks em uma conexão HTTP, o que só existe em um contexto de servidor. Uma função de load em +page.ts é executada tanto no servidor quanto no cliente. Quando é executada no cliente durante a navegação, não há conexão HTTP para escrever. O SvelteKit ignora Promises não resolvidas retornadas de funções de load universais e não as transmite via streaming. Se você retornar uma Promise de um +page.ts, ela será resolvida antes que os dados cheguem ao componente, mas sem a garantia de timing do streaming. Use +page.server.ts para qualquer função de load que pretenda fazer streaming.

Páginas onde a skeleton UI é pior do que um pequeno atraso não devem usar streaming. Streaming é uma otimização de performance percebida. Ele troca uma latência uniforme por uma revelação progressiva. Se seus dados diferidos resolverem em menos de 100ms, o flash do skeleton (o breve momento em que o skeleton é visível antes do conteúdo real aparecer) é perturbador e mais distrator do que simplesmente esperar. Para dados suplementares rápidos, busca paralela sem streaming é mais limpa.

Páginas onde a mudança de layout causada por dados diferidos é perturbadora devem reconsiderar o streaming. Se a seção de comentários expandindo de um skeleton para comentários reais causar um reflow significativo na página e empurrar outros conteúdos para baixo, o streaming prejudica a experiência. Reserve espaço explícito com CSS para seções diferidas (min-height ou uma altura fixa de placeholder) ou reconsidere se os dados devem ser diferidos.

Páginas com SSR desabilitado (export const ssr = false na página) nunca executam a função de load no servidor. A função de load é executada no navegador, onde não há conexão HTTP para transmitir. O streaming não tem efeito em páginas com SSR desabilitado.

Endpoints e rotas de API não são páginas SvelteKit. Eles não possuem funções de load. Streaming no contexto deste artigo refere-se especificamente a funções de load de servidor para páginas renderizadas.

Considerações de Performance e Escalabilidade

O custo do streaming no lado do servidor é o custo de manter uma conexão HTTP aberta por mais tempo do que um ciclo padrão de requisição/resposta. Em plataformas cobradas por minutos de conexão ou duração da requisição (plataformas serverless como Vercel Functions, AWS Lambda), uma requisição de streaming que mantém uma conexão aberta por 600ms enquanto aguarda a Promise diferida mais lenta é cobrada por essa duração. Requisições sem streaming que aguardam 600ms no servidor antes de responder são cobradas pela mesma duração. O custo de cobrança é equivalente. O benefício de experiência do usuário do streaming é a redução no tempo até o primeiro conteúdo.

Em implantações de servidor tradicionais com processos persistentes, a sobrecarga de conexão é baixa e o streaming é essencialmente gratuito do ponto de vista de recursos. As Promises do lado do servidor são executadas independentemente de os resultados serem transmitidos via streaming ou aguardados. O mecanismo de streaming adiciona uma sobrecarga mínima.

Headers de cache interagem com o streaming de forma sutil. Um header Cache-Control: public, max-age=300 em uma resposta transmitida via streaming significa que o CDN armazena em cache a resposta completa, incluindo os chunks transmitidos, como um corpo completo. Requisições subsequentes servidas a partir do cache do CDN recebem todos os dados de uma vez, sem streaming. O cache do CDN e o streaming são compatíveis no sentido de que a primeira requisição usa streaming e as requisições subsequentes servidas pelo cache do CDN não. Projete seus headers de cache com isso em mente: dados privados e específicos do usuário devem usar Cache-Control: private, no-store e farão streaming em cada requisição. Dados públicos armazenados em cache por um CDN só farão streaming em cache misses.

O Que Vem a Seguir

Streaming é uma estratégia para gerenciar dados lentos: adiá-los e deixar a página renderizar sem bloqueá-la neles. Outra estratégia é garantir que dados rápidos sejam realmente rápidos, executando tudo de forma concorrente e evitando o sequenciamento oculto que await parent() pode introduzir. O próximo artigo, Carregamento Paralelo e Evitando Waterfalls, aborda como o modelo de execução concorrente do SvelteKit funciona, como identificar e corrigir waterfalls de requisições e os padrões com Promise.all que mantêm um dashboard responsivo mesmo quando carrega de múltiplas fontes.

Veja Também

Documentação de Streaming do SvelteKit — referência oficial incluindo a lista de plataformas suportadas e notas específicas de adaptador
Sintaxe de Template {#await} do SvelteKit — referência completa para a sintaxe de três blocos {#await}{:then}{:catch} usada em todo componente com streaming