El Problema de Esperar Todo

Considera la página de un artículo de blog. El artículo en sí es la razón por la que el usuario llegó a la página. Necesita el título, el autor y el contenido. La sección de comentarios, la barra lateral de artículos relacionados y el panel de "a los lectores también les gustó" al final son complementarios. Un usuario preferiría ver el artículo de inmediato y esperar un momento a que los comentarios se carguen, antes que mirar una pantalla en blanco o de carga mientras la más lenta de cuatro llamadas a la API se completa.

El comportamiento predeterminado de una función de carga del servidor de SvelteKit es esperar todo antes de enviar cualquier HTML al navegador. Si tu función de carga llama a cuatro APIs y la más lenta tarda 800ms, el navegador no ve nada durante 800ms. La página se siente lenta aunque el contenido crítico estuviera listo en 120ms.

El streaming es el mecanismo para romper ese acoplamiento. Una función de carga del servidor puede retornar algunos datos resueltos y otros como una Promesa sin resolver. SvelteKit envía el HTML inicial de inmediato, usando los datos resueltos para renderizar el esqueleto de la página, y luego transmite los datos restantes al navegador a medida que las Promesas se resuelven. El componente maneja el estado pendiente con bloques {#await}.

Este artículo cubre cómo funciona el streaming en SvelteKit, la mecánica precisa de las Promesas sin resolver en los valores de retorno de las funciones de carga, cómo estructurar los componentes para manejar cada estado correctamente, cómo prevenir que el rechazo de Promesas bloquee el servidor, qué plataformas soportan streaming y cuáles lo almacenan en buffer silenciosamente, y las condiciones en las que el streaming no es la herramienta adecuada.

El Espacio del Problema

El patrón estándar de función de carga en artículos anteriores de esta serie espera todo 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 es buen código. Paraleliza las solicitudes y maneja los fallos de forma elegante. Pero su tiempo total de respuesta del servidor está determinado por la más lenta de las cuatro solicitudes. Si commentsResponse tarda 600ms porque los comentarios están almacenados en un servicio diferente con una caché fría, cada usuario espera 600ms antes de ver cualquier contenido, incluido el artículo en sí que estaba listo en 90ms.

El problema no es que las solicitudes se ejecuten en serie. Se ejecutan en paralelo con Promise.all. El problema es que todo espera en el límite de serialización: el punto donde SvelteKit toma el valor de retorno de la función de carga, lo serializa en la respuesta HTML inicial y lo envía al navegador. Ese límite requiere que todos los valores estén resueltos.

El streaming elimina esa restricción para los datos que no son necesarios para el renderizado inicial.

Cómo Funciona el Streaming en SvelteKit

El modelo de streaming de SvelteKit se basa en una premisa directa: si un valor en el objeto de retorno de la función de carga es una Promesa sin resolver, SvelteKit no la espera. Envía el HTML inicial de inmediato con los valores resueltos en su lugar, y luego transmite el valor resuelto de cada Promesa al navegador a través de la misma conexión HTTP a medida que se establece.

El mecanismo usa la codificación de transferencia por fragmentos HTTP (HTTP chunked transfer encoding), el mismo mecanismo que permite a los servidores enviar cuerpos de respuesta en piezas sin conocer la longitud total de antemano. SvelteKit escribe el HTML inicial como el primer fragmento, luego escribe etiquetas de script adicionales que contienen el valor resuelto de cada Promesa como fragmentos posteriores cuando llegan. El navegador ejecuta esas etiquetas de script a medida que las recibe, actualizando la página sin una navegación completa.

La experiencia del navegador es progresiva. El usuario ve el artículo de inmediato. La barra lateral de artículos relacionados se llena un momento después. La sección de comentarios aparece al final. Cada sección transiciona de su estado de carga a su estado poblado de forma independiente. El tiempo total hasta que la página es completamente interactiva sigue determinado por la solicitud más lenta, pero el tiempo hasta que la página es útil está determinado por la solicitud crítica más rápida.

Retornando Promesas sin Resolver desde Funciones de Carga

La sintaxis para el streaming en una función de carga del servidor es directa: retorna una Promesa en lugar de un valor esperado. No hagas await de la Promesa antes de retornarla.

// 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
	}
}

El tipo de retorno de comments y related aquí es Promise<SomeType[]>. SvelteKit acepta Promesas en los objetos de retorno de funciones de carga desde funciones de carga del servidor, y esto es lo que activa el streaming. Los tipos de TypeScript generados en ./$types reflejan esto: data.comments en el componente tendrá el tipo Promise<Comment[]>, no Comment[].

El invariante crítico que hay que entender: el HTML inicial se envía tan pronto como todos los valores que no son Promesas en el objeto de retorno están resueltos. La función de carga no se completa en el sentido tradicional antes de que el primer HTML llegue al navegador. SvelteKit comienza la respuesta anticipadamente y los datos en streaming se añaden a la misma respuesta con el tiempo.

El Truco del Orden: Los Datos Críticos Primero

La estructura correcta para una función de carga con streaming sigue un principio de ordenamiento claro. Solicita y espera los datos sin los cuales la página no puede renderizarse. Retorna el resto como Promesas. La división entre crítico y diferido no es arbitraria. Refleja la pregunta: ¿qué debe estar en pantalla para que la página sea útil en absoluto?

Para la página de un artículo de blog, el artículo en sí es crítico. La URL apunta a este artículo específico, y si no existe o no puede cargarse, la página debería mostrar un error, no un esqueleto. Los comentarios y los artículos relacionados son complementarios. La página es útil sin ellos.

// 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
	}
}

El momento preciso de esta estructura importa. Las solicitudes diferidas comienzan en la Fase 2, inmediatamente después de que los datos críticos se resuelven. No comienzan después del retorno. Para cuando SvelteKit empieza a escribir el fragmento HTML inicial, las solicitudes diferidas ya están en vuelo en el servidor. La brecha entre "HTML inicial enviado" y "datos diferidos llegan" es solo tan larga como tarden las solicitudes diferidas, no tan larga como esas solicitudes más el tiempo de enviar el HTML inicial.

Si las solicitudes diferidas se iniciaran de forma perezosa, el beneficio del streaming se reduciría. Iniciarlas antes del retorno garantiza que se ejecuten de forma concurrente con la transmisión de red del HTML inicial.

Manejo de los Estados de Streaming en Componentes

El contraparte en el componente de una Promesa en streaming es el bloque {#await}. El bloque {#await} de Svelte maneja tres estados:

Estado pendiente - mientras la Promesa está sin resolver
Estado de éxito - con el valor resuelto
Estado de error - si la Promesa es rechazada.

<!-- 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>

El bloque {:catch} en cada {#await} no es opcional cuando te importa la fiabilidad. Si una Promesa en streaming es rechazada y no hay un bloque {:catch}, Svelte silenciosamente no hace nada en el área del estado pendiente. La UI esqueleto permanece visible indefinidamente, lo cual es una experiencia confusa que parece un estado de carga atascado. Siempre incluye {:catch} para las Promesas en streaming, aunque el mensaje sea breve.

El UI del estado pendiente merece un esfuerzo de diseño genuino. Un esqueleto que coincida con la forma del contenido que está esperando es mucho mejor que un spinner o un área en blanco. El ojo del usuario se posa en el esqueleto mientras lee el artículo, y la transición del esqueleto al contenido es suave y poco sorpresiva. Un spinner en una barra lateral crea un punto focal que compite con el contenido que el usuario vino a leer.

Manejo Seguro de los Rechazos

Los rechazos de Promesas no manejados en un contexto de streaming tienen consecuencias más allá de mostrar una UI rota. Si una Promesa rechazada se propaga a la capa de streaming de SvelteKit sin ser capturada, puede resultar en un error de rechazo no manejado del lado del servidor. Dependiendo de tu versión de Node.js y la configuración de despliegue, los rechazos no manejados pueden terminar el proceso o disparar un evento de error que tu sistema de monitoreo alertará.

La regla es simple: cada Promesa retornada desde una función de carga con streaming debe tener un manejador .catch() adjunto antes de ser retornada. El manejador .catch() convierte el rechazo en un valor resuelto, un fallback seguro que el componente puede renderizar limpiamente.

// 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 []
	})

El doble catch aquí (verificar response.ok antes de .json() y un .catch() separado para fallos a nivel de red) maneja ambas categorías de fallo. La verificación de response.ok captura errores HTTP como 500 o 503. El .catch() captura errores de red como fallos de DNS, restablecimientos de conexión y tiempos de espera agotados. Ambos son reales en producción.

Algunos equipos prefieren envolver cada solicitud diferida en un helper que estandariza el comportamiento 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 }
}

El helper streamFetch hace explícita la intención en el lugar de la llamada: esta solicitud es diferida, su modo de fallo es un fallback conocido, y el fallo se registrará con una etiqueta que lo identifica en tu sistema de logging. El componente no necesita un bloque {:catch} que sea alcanzable en la práctica, porque streamFetch garantiza la resolución, pero incluir {:catch} como medida defensiva sigue siendo una buena práctica.

Ejemplo Práctico: Un Panel de Usuario con Streaming por Capas

Un panel de usuario es un caso de uso canónico para el streaming. Los paneles típicamente combinan una pequeña cantidad de información de identidad crítica (quién es el usuario, el estado de su cuenta) con varios paneles de datos secundarios (feed de actividad, notificaciones, recomendaciones, estadísticas de uso). Los datos críticos son rápidos. Los datos secundarios varían ampliamente en latencia dependiendo de su fuente.

Definiciones de tipos

// 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
}

La carga del servidor del panel

// 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
	}
}

El componente del panel

<!-- 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>

La llamada a $derived en isProOrEnterprise funciona correctamente aquí porque data.account es un valor resuelto, no una Promesa. Las derivaciones reactivas de datos resueltos funcionan exactamente igual que en cualquier otra página. Las derivaciones reactivas de datos de Promesa requieren anidar el $derived dentro de un bloque {:then} resuelto o almacenar el valor resuelto en una variable $state, lo que complica las cosas.

Mantén los datos resueltos y los datos en streaming como preocupaciones separadas cuando sea posible: deriva de datos resueltos en el bloque script, y deja que {#await} maneje todo el renderizado dependiente de Promesas.

Soporte de Plataformas: Dónde Funciona Realmente el Streaming

El streaming mediante codificación de transferencia por fragmentos requiere que la conexión HTTP entre el navegador y el servidor permanezca abierta mientras el servidor envía datos en piezas. Este es el comportamiento estándar en despliegues directos con Node.js o Deno. No es universal en todas las plataformas de despliegue y configuraciones de proxy.

Adaptador de Node.js (@sveltejs/adapter-node): Soporte completo. La codificación de transferencia por fragmentos es nativa en el HTTP de Node.js. El streaming funciona como se describe.

Cloudflare Workers (@sveltejs/adapter-cloudflare): Soporte completo. El runtime de Cloudflare Workers soporta la Web Streams API, que SvelteKit usa en plataformas edge. El streaming funciona.

Vercel (@sveltejs/adapter-vercel): Soportado con la opción streaming: true en la configuración del adaptador. Sin este flag, el adaptador almacena la respuesta en buffer. Configúralo explícitamente:

// 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 (mediante @sveltejs/adapter-node detrás de API Gateway o Lambda Function URLs): Problemático. API Gateway históricamente ha almacenado las respuestas en buffer, impidiendo que la codificación de transferencia por fragmentos funcione de extremo a extremo. Las Lambda Function URLs tienen mejor soporte para streaming de respuestas cuando se usa el modo de invocación RESPONSE_STREAM, pero esto requiere configuración explícita y no es el predeterminado. Cuando se despliega en Lambda detrás de API Gateway, prueba el comportamiento del streaming explícitamente y asume que puede estar almacenado en buffer.

Firebase Hosting con Cloud Functions: Firebase Hosting actúa como una CDN que almacena en buffer las respuestas de las funciones antes de entregarlas. El streaming de datos desde Cloud Functions a través de Firebase Hosting no funciona. La CDN recopila la respuesta completa antes de reenviarla. Si usas Firebase Functions directamente (eludiendo Hosting para las rutas API), el streaming es técnicamente posible pero requiere una configuración cuidadosa.

NGINX como proxy inverso: NGINX almacena en buffer las respuestas del upstream de forma predeterminada. La directiva proxy_buffering off debe configurarse para el bloque de ubicación específico para permitir que el streaming pase a través:

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

Sin proxy_buffering off, NGINX recopila la respuesta completa del servidor SvelteKit antes de reenviarla al navegador. La experiencia del usuario es idéntica a no usar streaming en absoluto. Las Promesas diferidas siguen resolviéndose y enviándose, pero llegan al navegador todas a la vez después de que la más lenta se establece. El beneficio del streaming se pierde.

La prueba práctica: La forma más confiable de verificar que el streaming realmente funciona de extremo a extremo en tu despliegue es añadir una Promesa diferida con un retraso conocido y observar si el HTML inicial llega antes de que el retraso se complete:

// 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 y el Bloque `{#await}` Durante la Navegación del Cliente

Una distinción de comportamiento importante: durante la navegación del lado del cliente (cuando el usuario hace clic en un enlace y SvelteKit navega sin una carga de página completa), el streaming se comporta de manera diferente a una solicitud SSR completa.

Durante la navegación del cliente, la función de carga del servidor se ejecuta en el servidor, pero la respuesta se envía al navegador como un objeto JSON en lugar de fragmentos HTML. SvelteKit resuelve todas las Promesas en el servidor antes de enviar la respuesta JSON al cliente. El cliente recibe todos los datos a la vez y los usa para actualizar la página.

Esto significa que el estado pendiente del bloque {#await} no se muestra durante la navegación del cliente cuando está involucrada una función de carga del servidor. El navegador no experimenta latencia para los datos diferidos durante las transiciones porque el servidor resuelve todo antes de responder. El beneficio del streaming es una optimización exclusiva del renderizado del lado del servidor.

Esto no es un defecto. Es el comportamiento apropiado. Las cargas de página completa son la ruta lenta donde el streaming aporta más valor. Las navegaciones del cliente ya son rápidas porque el navegador tiene el shell de la página y el entorno de ejecución de JavaScript cargados. El viaje de ida y vuelta adicional para resolver Promises del lado del servidor antes de enviar el JSON es un costo aceptable por la simplicidad del modelo de navegación del cliente.

La consecuencia para el diseño de componentes: el estado pendiente de cada bloque {#await} es principalmente una preocupación de renderizado en el servidor. Diseña esqueletos y estados de carga pensando en la experiencia de la primera carga, no en la experiencia de transición.

Errores Comunes y Anti-Patrones

Esperar 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 }
}

Transmitir datos críticos que `error()` necesita 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 }
}

Si el recurso que define la página (la publicación, el producto, el perfil de usuario) se transmite mediante streaming y su fetch falla, el componente queda en un estado irrecuperable: no puede mostrar la página porque no hay contenido, y no puede mostrar una página de error adecuada porque error() nunca fue llamado. Siempre espera el recurso del que depende la identidad de la página.

Omitir `{#await}` por completo o no incluir `{: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}

TypeScript detectará el primer error en la mayoría de los casos porque data.comments está tipado como Promise<Comment[]>, no como Comment[]. El bloque {#each} espera un arreglo y TypeScript se quejará. Pero TypeScript no lo detectará si la anotación de tipo es genérica o está ausente, por lo que la disciplina con {#await} importa independientemente de la cobertura de TypeScript.

Cuándo NO Usar Streaming

El streaming es una optimización específica. No es apropiado en todas las situaciones.

Las funciones de carga universales no pueden transmitir mediante streaming. El streaming requiere la capacidad de escribir fragmentos en una conexión HTTP, lo cual solo existe en un contexto de servidor. Una función de carga +page.ts se ejecuta tanto en el servidor como en el cliente. Cuando se ejecuta en el cliente durante la navegación, no hay conexión HTTP a la cual escribir. SvelteKit ignora las Promises sin resolver retornadas por funciones de carga universales y no las transmite. Si retornas una Promise desde un +page.ts, se resuelve antes de que los datos lleguen al componente, pero sin la garantía de temporización del streaming. Usa +page.server.ts para cualquier función de carga que tenga intención de transmitir.

Las páginas donde una UI de esqueleto es peor que un pequeño retraso no deberían usar streaming. El streaming es una optimización de rendimiento percibido. Intercambia una latencia uniforme por una revelación progresiva. Si tus datos diferidos se resuelven en menos de 100ms, el destello del esqueleto (el breve momento en que el esqueleto es visible antes de que aparezca el contenido real) resulta molesto y más distractor que simplemente esperar. Para datos complementarios rápidos, la carga paralela sin streaming es más limpia.

Las páginas donde el desplazamiento del diseño causado por datos diferidos es disruptivo deberían reconsiderar el streaming. Si la sección de comentarios que se expande de un esqueleto a comentarios reales provoca que la página se redistribuya significativamente y empuje otro contenido hacia abajo, el streaming perjudica la experiencia. Reserva espacio explícito con CSS para las secciones diferidas (min-height o una altura fija como marcador de posición) o reconsidera si los datos deberían diferirse en absoluto.

Las páginas con SSR deshabilitado (export const ssr = false en la página) nunca ejecutan la función de carga en el servidor. La función de carga se ejecuta en el navegador, donde no hay conexión HTTP sobre la cual transmitir. El streaming no tiene efecto en páginas con SSR deshabilitado.

Los endpoints y rutas de API no son páginas de SvelteKit. No tienen funciones de carga. El streaming en el contexto de este artículo se refiere específicamente a las funciones de carga del servidor para páginas renderizadas.

Consideraciones de Rendimiento y Escalabilidad

El costo del lado del servidor del streaming es el costo de mantener una conexión HTTP abierta por más tiempo que un ciclo estándar de solicitud/respuesta. En plataformas facturadas por minutos de conexión o duración de la solicitud (plataformas serverless como Vercel Functions, AWS Lambda), una solicitud de streaming que mantiene una conexión abierta durante 600ms mientras espera la Promise diferida más lenta se factura por esa duración. Las solicitudes sin streaming que esperan 600ms del lado del servidor antes de responder se facturan por la misma duración. El costo de facturación es equivalente. El beneficio en la experiencia del usuario del streaming es la reducción en el tiempo hasta el primer contenido.

En despliegues de servidor tradicionales con procesos persistentes, la sobrecarga de conexión es baja y el streaming es esencialmente gratuito desde una perspectiva de recursos. Las Promises del lado del servidor se ejecutan independientemente de si los resultados se transmiten o se esperan. El mecanismo de streaming añade una sobrecarga mínima.

Los encabezados de caché interactúan con el streaming de manera matizada. Un encabezado Cache-Control: public, max-age=300 en una respuesta transmitida significa que el CDN almacena en caché la respuesta completa, incluyendo los fragmentos transmitidos, como un cuerpo completo. Las solicitudes posteriores servidas desde la caché del CDN reciben todos los datos a la vez, sin streaming. El almacenamiento en caché del CDN y el streaming son compatibles en el sentido de que la primera solicitud transmite y las solicitudes posteriores servidas desde la caché del CDN no lo hacen. Diseña tus encabezados de caché con esto en mente: los datos privados específicos del usuario deben usar Cache-Control: private, no-store y transmitirán en cada solicitud. Los datos públicos almacenados en caché por un CDN transmitirán solo en los errores de caché.

Qué Sigue

El streaming es una estrategia para gestionar datos lentos: diferirlos y permitir que la página se renderice sin bloquearse en ellos. Otra estrategia es asegurarse de que los datos rápidos sean realmente rápidos, ejecutando todo de forma concurrente y evitando la secuenciación oculta que await parent() puede introducir. El siguiente artículo, Carga Paralela y Cómo Evitar Cascadas, explica cómo funciona el modelo de ejecución concurrente de SvelteKit, cómo detectar y corregir cascadas de solicitudes, y los patrones con Promise.all que mantienen un panel de control ágil incluso cuando carga desde múltiples fuentes.

Ver También

Documentación de Streaming de SvelteKit — referencia oficial que incluye la lista de plataformas compatibles y notas específicas de cada adaptador
Sintaxis de Plantilla {#await} de SvelteKit — referencia completa para la sintaxis de tres bloques {#await}{:then}{:catch} usada en cada componente de streaming