Por que o Evento Load Fornece Seu Próprio fetch

Toda função load do SvelteKit recebe um objeto de evento, e entre suas propriedades há uma que parece familiar demais para merecer uma segunda olhada: fetch. É uma função que faz requisições HTTP. Você já sabe como usá-la. O que poderia haver para explicar?

Bastante coisa, na verdade.

O fetch fornecido pelo evento load não é o fetch nativo do navegador. É uma versão especializada construída pelo SvelteKit que possui cinco capacidades distintas não presentes na versão global. Usar o fetch global dentro de uma função load não é apenas um erro estilístico. Em alguns cenários produz comportamento incorreto. Em outros, compromete silenciosamente exatamente o que o SvelteKit está tentando fazer por você: entregar uma página totalmente renderizada na primeira requisição sem atividade de rede redundante.

Este artigo constrói uma compreensão precisa de por que o SvelteKit substitui o fetch, o que cada uma dessas cinco capacidades faz, e como elas interagem em uma aplicação real. Também aborda a distinção entre buscar dados de APIs externas e de suas próprias rotas internas +server.ts, porque esses dois cenários têm características diferentes que vale a pena entender. Ao final, você terá um modelo mental claro do que acontece com uma chamada fetch desde o momento em que uma função load é executada no servidor até o momento em que a mesma página se torna interativa no navegador.

O que o fetch Global Não Consegue Fazer

Para entender por que o SvelteKit precisa de seu próprio fetch, considere o que acontece quando um usuário navega para uma página que carrega dados.

No servidor, o SvelteKit executa sua função load, chama quaisquer requisições fetch dentro dela, monta os dados resultantes, renderiza a árvore de componentes em HTML e envia o resultado para o navegador. O navegador recebe uma página completamente formada e a exibe imediatamente. Essa é a promessa do SSR: primeiro paint rápido, conteúdo visível antes da execução do JavaScript.

Então o pacote JavaScript chega. O SvelteKit precisa hidratar a página, transformando o HTML estático em uma aplicação Svelte interativa e viva. A hidratação requer que a árvore de componentes do lado do cliente corresponda exatamente ao HTML renderizado pelo servidor. Se os dados usados durante a hidratação diferirem dos dados usados durante a renderização no servidor, você obtém uma incompatibilidade.

Agora considere o que acontece se sua função load usa o fetch global nativo durante o SSR. O servidor busca dados, renderiza HTML com eles e envia esse HTML para o navegador. Quando o pacote do cliente é executado e tenta hidratar, ele precisa desses mesmos dados. Se ele reexecutar a função load para obtê-los, isso significa outra requisição de rede do navegador. Duas requisições para os mesmos dados: uma no servidor, outra no cliente. Esse é o problema do double-fetch.

Mesmo ignorando a hidratação, o fetch nativo no servidor não sabe nada sobre o roteamento interno do SvelteKit. Uma URL relativa como /api/products não significa nada no Node.js, onde não há conceito de origem atual. Você teria que codificar uma URL absoluta, o que é frágil em desenvolvimento ou requer a injeção de variáveis de ambiente para o host atual. E se esse endpoint /api/products for um de seus próprios arquivos +server.ts, você estaria fazendo uma requisição HTTP real para si mesmo quando o SvelteKit poderia simplesmente chamar o handler diretamente sem jamais tocar na rede.

Esses são os problemas que o fetch do SvelteKit resolve. Cada um corresponde a uma capacidade distinta.

Como Funciona

Antes de percorrer cada capacidade, é útil entender onde o fetch se encaixa no ciclo de vida da função load.

Uma função load é fundamentalmente uma função de aquisição de dados. O SvelteKit a chama no momento certo, no contexto certo, com as ferramentas certas. O objeto de evento load agrupa tudo o que a função precisa: parâmetros de rota, informações de URL, cookies, dados do layout pai, o ambiente da plataforma e o fetch. Você não importa o fetch nem o instancia. Você o desestrutura do evento.

// The fetch you use comes from the event, not from the global scope.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/articles/${params.slug}`)
	const article = await response.json()
	return { article }
}

Isso é intencional. O SvelteKit controla o tempo de vida dessa instância de fetch. Ele sabe quando a função load foi chamada, se está sendo executada no servidor ou no cliente, e quais requisições já foram feitas. Esse contexto é o que habilita as cinco capacidades.

Quando o navegador recebe a página, os dados serializados já estão embutidos no HTML. O runtime SvelteKit do lado do cliente lê esses dados da página em vez de buscá-los novamente. As funções load são executadas apenas uma vez para a requisição inicial.

Os Cinco Superpoderes do event.fetch

As cinco capacidades dos Superpoderes são suficientemente distintas para que cada uma mereça sua própria seção, mas ajuda vê-las juntas primeiro antes de mergulhar em cada uma.

SP1: URLs Relativas Resolvem Corretamente

No servidor, não há conceito de origem da página atual. O Node.js não sabe em qual hostname sua aplicação está sendo executada. Se você usar o fetch nativo com uma URL relativa dentro de uma função load durante o SSR, você obtém um erro porque o fetch nativo do Node requer URLs absolutas.

O fetch do SvelteKit resolve URLs relativas em relação à origem da requisição atual automaticamente. A URL /api/products se torna http://localhost:5173/api/products em desenvolvimento e https://yourdomain.com/api/products em produção, sem nenhuma configuração da sua parte.

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

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

export const load: PageServerLoad = async ({ fetch }) => {
	// This works on the server. SvelteKit resolves it against
	// the current request origin. Native fetch would throw here
	// because '/api/products' is not a valid absolute URL in Node.
	const response = await fetch('/api/products')

	if (!response.ok) {
		error(response.status, 'Failed to load products')
	}

	const products = await response.json()
	return { products }
}

Isso significa que você escreve a mesma URL em desenvolvimento e produção. Você nunca concatena process.env.ORIGIN com um caminho. A URL que você escreve na função load é a mesma URL que um navegador usaria para acessar o mesmo endpoint, o que é um modelo mental natural e consistente.

SP2: Credenciais Fluem Automaticamente

A autenticação no SvelteKit normalmente envolve um cookie de sessão. O navegador envia esse cookie com cada requisição automaticamente, mas no servidor, quando você está fazendo uma chamada fetch dentro de uma função load, esse cookie não está presente na chamada fetch a menos que você o encaminhe explicitamente.

O fetch do SvelteKit encaminha cookies e cabeçalhos de autorização da requisição recebida para chamadas fetch de mesma origem dentro de funções load. Isso significa que seus endpoints de API recebem o mesmo contexto de autenticação que a requisição de página original, sem necessidade de extração manual de cookies ou encaminhamento de cabeçalhos.

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

import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ fetch }) => {
	// SvelteKit forwards the session cookie from the original
	// browser request to this fetch call automatically.
	// The /api/account endpoint can read it and verify the session.
	const response = await fetch('/api/account/profile')

	if (response.status === 401) {
		// Session missing or expired. Return null rather than throwing
		// here so the page can render a login prompt.
		return { profile: null }
	}

	const profile = await response.json()
	return { profile }
}

Esse encaminhamento automático de credenciais se aplica apenas a requisições de mesma origem. Quando você busca dados de uma API externa em um domínio diferente, nenhum cookie ou cabeçalho de autorização é encaminhado. Esse é o comportamento correto: você não gostaria que seus cookies de sessão fossem enviados para um serviço de terceiros.

Se você precisar autenticar uma requisição de origem cruzada, você fornece as credenciais explicitamente na chamada fetch, exatamente como faria com o fetch nativo.

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

import type { PageServerLoad } from './$types'
import { WEATHER_API_KEY } from '$env/static/private'

export const load: PageServerLoad = async ({ params, fetch }) => {
	// Cross-origin request to an external API.
	// No cookies are forwarded. Credentials are supplied explicitly.
	const weatherUrl = new URL('https://api.openweathermap.org/data/2.5/weather')
	weatherUrl.searchParams.set('q', params.city)
	weatherUrl.searchParams.set('appid', WEATHER_API_KEY)

	const response = await fetch(weatherUrl.toString())

	if (!response.ok) {
		return { weather: null }
	}

	const weather = await response.json()
	return { weather }
}

SP3: Rotas Internas São Ignoradas

Quando você busca uma URL que corresponde a um de seus próprios endpoints +server.ts do SvelteKit, o SvelteKit não faz uma requisição HTTP real. Ele chama a função handler da rota diretamente, em processo, sem tocar na rede.

Isso importa de duas formas. Primeiro, elimina uma ida e volta de rede desnecessária: a serialização, transmissão e desserialização de dados que já estavam na memória. Segundo, significa que seus endpoints de API internos podem usar importações exclusivas do servidor como $env/static/private e utilitários internos, e essas importações permanecem seguras mesmo quando a chamada fetch parece uma requisição de rede de fora.

// src/routes/api/articles/[slug]/+server.ts

import type { RequestHandler } from './$types'
import { json, error } from '@sveltejs/kit'
import { CMS_TOKEN } from '$env/static/private'

export const GET: RequestHandler = async ({ params }) => {
	// This handler is called directly when fetched from within the app.
	// It is also callable as a real HTTP endpoint from external clients.
	const response = await fetch(`https://cms.example.com/api/articles/${params.slug}`, {
		headers: { Authorization: `Bearer ${CMS_TOKEN}` }
	})

	if (!response.ok) {
		error(404, 'Article not found')
	}

	const article = await response.json()
	return json(article)
}

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

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// SvelteKit calls the +server.ts handler directly.
	// No HTTP request is made. The handler runs as a function call.
	const response = await fetch(`/api/articles/${params.slug}`)

	if (!response.ok) {
		error(404, 'Article not found')
	}

	const article = await response.json()
	return { article }
}

Esse design permite que você construa suas próprias rotas de API como endpoints HTTP reais e chamáveis que clientes externos ou aplicativos móveis podem usar, enquanto também os usa internamente a partir de funções load sem nenhuma penalidade de desempenho. Você obtém uma superfície de API limpa e acesso eficiente a dados internos a partir do mesmo arquivo de handler de rota.

SP4: Respostas São Capturadas para Hidratação

Essa é a capacidade que previne o problema do double-fetch.

Quando uma função load é executada durante o SSR e chama event.fetch, o SvelteKit captura a resposta. Ele serializa os dados da resposta e os embute na página HTML enviada ao navegador, dentro de um bloco de script que o SvelteKit lê durante a hidratação.

Quando o navegador carrega a página e o pacote JavaScript é executado, o runtime do lado do cliente do SvelteKit intercepta quaisquer chamadas event.fetch que reproduziriam uma requisição já feita no servidor. Em vez de fazer uma requisição de rede real, ele lê a resposta capturada dos dados da página embutida.

A consequência prática é que o código da sua função load é o mesmo em ambos os ambientes. Você não escreve caminhos separados de busca de dados para o servidor e para o cliente. Você escreve uma função load, e o SvelteKit lida com a diferença de forma transparente.

// src/routes/blog/[slug]/+page.ts
// This is a universal load function (no .server). It runs on the server
// for the initial request and on the client during subsequent navigations.

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

export const load: PageLoad = async ({ params, fetch }) => {
	// During SSR: SvelteKit makes the request and captures the response.
	// During client navigation: SvelteKit makes the request from the browser.
	// During hydration of an SSR page: SvelteKit uses the captured response.
	// The code here is identical in all three scenarios.
	const response = await fetch(`/api/articles/${params.slug}`)

	if (!response.ok) {
		error(404, 'Article not found')
	}

	const article = await response.json()
	return { article }
}

Se você usasse o fetch global aqui em vez de event.fetch, a interceptação de hidratação não ocorreria. O cliente faria uma requisição de rede real, a página seria momentaneamente rerenderizada com dados recém-buscados, e se esses dados diferirem do que foi renderizado no servidor, você obtém uma incompatibilidade de hidratação. O fetch global ignora todo o mecanismo de captura do SSR.

SP5: Fetch É Consciente do Ambiente

A quinta capacidade é menos dramática, mas vale a pena nomear explicitamente: o fetch do SvelteKit funciona corretamente em todos os ambientes onde as funções load são executadas, sem qualquer modificação.

No Node.js executando um servidor de produção, ele lida com a ausência de um fetch global nativo. No navegador, ele delega ao fetch nativo do navegador, mas com a camada de interceptação para hidratação. No Vitest ou em testes com Playwright, ele pode ser mockado ou interceptado uniformemente. Em Cloudflare Workers ou outros ambientes edge, ele respeita a implementação de fetch da plataforma.

Você não precisa detectar o ambiente, importar polyfills ou escrever lógica condicional. A mesma chamada event.fetch funciona em todos os lugares onde sua função load é executada.

Buscando de APIs Externas vs Rotas Internas

A distinção entre buscar dados de uma API externa e buscar de suas próprias rotas SvelteKit merece atenção explícita porque os dois cenários têm características diferentes.

APIs externas são endpoints HTTP reais em servidores diferentes. Toda a pilha de rede está envolvida: resolução de DNS, conexões TCP, handshakes TLS, serialização de requisição, transmissão, desserialização de resposta. Para chamadas de API externas, você gerencia a autenticação com cabeçalhos explícitos, lida com limitação de taxa, trata erros de rede e analisa o formato de resposta que o proprietário da API define.

Rotas internas são seus próprios handlers +server.ts. Como descrito anteriormente em SP3, o SvelteKit ignora a rede para elas. A função handler é chamada diretamente. Os objetos de requisição e resposta são construídos na memória. A única serialização envolvida é a codificação e decodificação JSON que você realiza no próprio handler.

Uma consequência prática dessa distinção: quando você precisa de dados de um serviço externo, colocar uma rota +server.ts na frente dele cria uma camada útil onde você pode normalizar a resposta, tratar erros uniformemente, injetar autenticação sem expor chaves de API ao cliente e armazenar resultados em cache.

// src/routes/api/github/repos/+server.ts
// Acts as a thin adapter between external GitHub API and internal consumers.

import type { RequestHandler } from './$types'
import { json, error } from '@sveltejs/kit'
import { GITHUB_TOKEN } from '$env/static/private'

interface GitHubRepo {
	id: number
	name: string
	full_name: string
	description: string | null
	stargazers_count: number
	language: string | null
	html_url: string
}

interface NormalizedRepo {
	id: number
	name: string
	description: string
	stars: number
	language: string
	url: string
}

export const GET: RequestHandler = async ({ url }) => {
	const username = url.searchParams.get('username')

	if (!username) {
		error(400, 'username query parameter is required')
	}

	const response = await fetch(
		`https://api.github.com/users/${username}/repos?per_page=10&sort=stars`,
		{
			headers: {
				Authorization: `Bearer ${GITHUB_TOKEN}`,
				Accept: 'application/vnd.github.v3+json'
			}
		}
	)

	if (!response.ok) {
		error(response.status, `GitHub API error: ${response.statusText}`)
	}

	const repos: GitHubRepo[] = await response.json()

	// Normalize to a stable internal shape. If GitHub changes their API,
	// only this file needs to change.
	const normalized: NormalizedRepo[] = repos.map((repo) => ({
		id: repo.id,
		name: repo.name,
		description: repo.description ?? 'No description provided',
		stars: repo.stargazers_count,
		language: repo.language ?? 'Unknown',
		url: repo.html_url
	}))

	return json(normalized)
}

// src/routes/profile/[username]/+page.server.ts

import type { PageServerLoad } from './$types'
import type { NormalizedRepo } from '$lib/types'

export const load: PageServerLoad = async ({ params, fetch }) => {
	// Fetches from our internal adapter route, not directly from GitHub.
	// GITHUB_TOKEN never reaches this file or the browser.
	// The response is the NormalizedRepo shape we control.
	const response = await fetch(`/api/github/repos?username=${params.username}`)

	if (!response.ok) {
		return { repos: [] as NormalizedRepo[] }
	}

	const repos: NormalizedRepo[] = await response.json()
	return { repos }
}

Esse padrão mantém as chaves de API exclusivas do servidor, fornece um único lugar para atualizar quando a API externa muda, e permite que a função load trabalhe com um formato que você projetou em vez de um formato imposto por terceiros.

Exemplo Prático: Buscando uma API JSON Tipada

A seguir está um exemplo completo e funcional que combina todas as cinco capacidades. Ele modela uma página de listagem de produtos que busca dados de uma rota interna, tipifica a resposta corretamente usando TypeScript, trata erros de forma elegante e funciona corretamente em SSR, hidratação e navegação do cliente.

Definindo os tipos compartilhados

// src/lib/types/product.ts

export interface Product {
	id: string
	name: string
	price: number
	category: string
	inStock: boolean
	imageUrl: string
}

export interface ProductListResponse {
	products: Product[]
	total: number
	page: number
	pageSize: number
}

A rota de API interna

// src/routes/api/products/+server.ts

import type { RequestHandler } from './$types'
import { json, error } from '@sveltejs/kit'
import type { Product, ProductListResponse } from '$lib/types/product'

// Simulates a data source. In a real application this would query
// whatever data store your application uses.
const PRODUCTS: Product[] = [
	{
		id: '1',
		name: 'Mechanical Keyboard',
		price: 149,
		category: 'peripherals',
		inStock: true,
		imageUrl: '/images/keyboard.jpg'
	},
	{
		id: '2',
		name: 'Curved Monitor',
		price: 549,
		category: 'displays',
		inStock: true,
		imageUrl: '/images/monitor.jpg'
	},
	{
		id: '3',
		name: 'Ergonomic Chair',
		price: 399,
		category: 'furniture',
		inStock: false,
		imageUrl: '/images/chair.jpg'
	},
	{
		id: '4',
		name: 'USB-C Hub',
		price: 79,
		category: 'peripherals',
		inStock: true,
		imageUrl: '/images/hub.jpg'
	},
	{
		id: '5',
		name: 'Webcam 4K',
		price: 199,
		category: 'peripherals',
		inStock: true,
		imageUrl: '/images/webcam.jpg'
	},
	{
		id: '6',
		name: 'Standing Desk',
		price: 699,
		category: 'furniture',
		inStock: true,
		imageUrl: '/images/desk.jpg'
	}
]

const PAGE_SIZE = 3

export const GET: RequestHandler = async ({ url }) => {
	const category = url.searchParams.get('category')
	const pageParam = url.searchParams.get('page')
	const page = Math.max(1, parseInt(pageParam ?? '1', 10) || 1)

	let filtered = category ? PRODUCTS.filter((p) => p.category === category) : PRODUCTS

	const total = filtered.length
	const start = (page - 1) * PAGE_SIZE
	const products = filtered.slice(start, start + PAGE_SIZE)

	if (page > 1 && products.length === 0) {
		error(404, 'No products found for this page')
	}

	const result: ProductListResponse = {
		products,
		total,
		page,
		pageSize: PAGE_SIZE
	}

	return json(result)
}

A função load

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

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

export const load: PageServerLoad = async ({ url, fetch }) => {
	const category = url.searchParams.get('category')
	const page = url.searchParams.get('page') ?? '1'

	// Build the internal API URL, forwarding the same query parameters
	// the user supplied to the page URL.
	const apiUrl = new URL('/api/products', url.origin)
	if (category) apiUrl.searchParams.set('category', category)
	apiUrl.searchParams.set('page', page)

	const response = await fetch(apiUrl.toString())

	if (!response.ok) {
		error(response.status, 'Failed to load products')
	}

	const data: ProductListResponse = await response.json()

	return {
		products: data.products,
		total: data.total,
		page: data.page,
		pageSize: data.pageSize,
		selectedCategory: category
	}
}

O componente de página

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

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

	let { data }: PageProps = $props()

	const categories = ['peripherals', 'displays', 'furniture']

	const totalPages = $derived(Math.ceil(data.total / data.pageSize))

	function buildPageUrl(page: number): string {
		const params = new URLSearchParams()
		if (data.selectedCategory) params.set('category', data.selectedCategory)
		params.set('page', String(page))
		return `/shop?${params.toString()}`
	}

	function buildCategoryUrl(category: string | null): string {
		if (!category) return '/shop'
		return `/shop?category=${category}`
	}
</script>

<section class="shop">
	<h1>Shop</h1>

	<nav class="category-filter" aria-label="Filter by category">
		<a href={buildCategoryUrl(null)} class:active={!data.selectedCategory}>All</a>
		{#each categories as category (category)}
			<a href={buildCategoryUrl(category)} class:active={data.selectedCategory === category}>
				{category}
			</a>
		{/each}
	</nav>

	<p class="result-count">
		Showing {data.products.length} of {data.total} products
		{#if data.selectedCategory}in {data.selectedCategory}{/if}
	</p>

	<ul class="product-grid">
		{#each data.products as product (product.id)}
			<li class="product-card">
				<img src={product.imageUrl} alt={product.name} />
				<h2>{product.name}</h2>
				<p class="price">${product.price}</p>
				{#if !product.inStock}
					<span class="badge out-of-stock">Out of stock</span>
				{/if}
			</li>
		{/each}
	</ul>

	{#if totalPages > 1}
		<nav class="pagination" aria-label="Page navigation">
			{#if data.page > 1}
				<a href={buildPageUrl(data.page - 1)}>Previous</a>
			{/if}

			<span>Page {data.page} of {totalPages}</span>

			{#if data.page < totalPages}
				<a href={buildPageUrl(data.page + 1)}>Next</a>
			{/if}
		</nav>
	{/if}
</section>

Observe que na rota shop o componente +page.svelte não tem chamadas fetch e não tem gerenciamento de estado de carregamento. Os dados chegam através de $props() como um objeto completo e tipado.

A runa $derived computa a contagem total de páginas de forma reativa a partir dos dados sem qualquer lógica manual de recomputação.

A navegação entre páginas e categorias usa links de âncora simples, que acionam a navegação do lado do cliente do SvelteKit e reexecutam a função load no cliente usando event.fetch, com todos os cinco superpoderes ainda em efeito.

Erros Comuns e Anti-Padrões

Usando o fetch global em vez de event.fetch

// Avoid
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params }) => {
	// This uses the global fetch, not SvelteKit's enhanced version.
	// During SSR it may fail with relative URLs. During hydration
	// it bypasses the captured response and makes a second network request.
	const response = await fetch(`/api/articles/${params.slug}`)
	return { article: await response.json() }
}

// Preferred
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	// Destructure fetch from the event. This is SvelteKit's enhanced version.
	const response = await fetch(`/api/articles/${params.slug}`)
	return { article: await response.json() }
}

O fetch global não tem conhecimento do ciclo de vida do SvelteKit. Ele não consegue resolver URLs relativas no servidor, não encaminha credenciais, não chama handlers de rotas internas diretamente e não participa da captura de resposta SSR. A solução é sempre desestruturar fetch do evento de load em vez de chamar o global.

Ignorando o status da resposta

// Wrong
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/products/${params.id}`)
	// If the API returns 404 or 500, response.json() may throw or return
	// an error object. The page renders with garbage data or crashes silently.
	const product = await response.json()
	return { product }
}

// Correct
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/products/${params.id}`)

	if (!response.ok) {
		// Throw a SvelteKit error. This renders the nearest +error.svelte
		// boundary with the appropriate HTTP status code.
		error(response.status, `Product ${params.id} could not be loaded`)
	}

	const product = await response.json()
	return { product }
}

response.ok é verdadeiro para códigos de status 2xx. Qualquer outro status significa que algo deu errado. Chamar error() de @sveltejs/kit encerra o load e renderiza o limite de erro, que é o comportamento correto quando os dados necessários para renderizar a página não estão disponíveis.

Construindo URLs com concatenação de strings

// Wrong: fragile and injection-prone
export const load: PageServerLoad = async ({ url, fetch }) => {
	const search = url.searchParams.get('q')
	// String concatenation does not encode special characters.
	// A search query containing '&' or '?' will corrupt the URL.
	const response = await fetch(`/api/search?q=${search}&page=1`)
	return { results: await response.json() }
}

// Correct: use the URL constructor for safe parameter encoding
export const load: PageServerLoad = async ({ url, fetch }) => {
	const search = url.searchParams.get('q') ?? ''

	const apiUrl = new URL('/api/search', url.origin)
	apiUrl.searchParams.set('q', search)
	apiUrl.searchParams.set('page', '1')

	const response = await fetch(apiUrl.toString())
	return { results: await response.json() }
}

O construtor URL e o URLSearchParams tratam a codificação automaticamente. Caracteres especiais em consultas de busca, slugs com unicode e quaisquer valores fornecidos pelo usuário são tratados corretamente sem codificação manual.

Considerações de Desempenho e Escalabilidade

O mecanismo de captura de resposta SSR funciona por requisição. Cada requisição recebida pela sua aplicação SvelteKit dispara seu próprio conjunto de funções de load, cada uma com sua própria instância de fetch. As respostas capturadas não são compartilhadas entre requisições nem armazenadas em cache além do tempo de vida de uma única requisição.

Se uma função de load busca dados que são caros de computar e idênticos para todos os usuários, como uma lista de categorias de produtos ou uma configuração global do site, buscá-los em cada requisição SSR é um desperdício. A solução é o cache na camada da API, não na função de load. Seu handler de rota +server.ts pode implementar um cache em memória ou usar cabeçalhos de cache HTTP para permitir que intermediários armazenem a resposta em cache.

// src/routes/api/categories/+server.ts

import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

// In-memory cache shared across requests to the same server instance.
// This is appropriate for data that changes rarely and is identical for all users.
let categoriesCache: string[] | null = null
let cacheSetAt = 0
const CACHE_TTL_MS = 60 * 1000 // one minute

export const GET: RequestHandler = async () => {
	const now = Date.now()

	if (categoriesCache && now - cacheSetAt < CACHE_TTL_MS) {
		return json(categoriesCache)
	}

	const response = await fetch('https://api.example.com/categories')
	const categories: string[] = await response.json()

	categoriesCache = categories
	cacheSetAt = now

	return json(categories)
}

Para dados específicos do usuário, o cache no nível do servidor não é adequado, pois a resposta de cada usuário é diferente. O mecanismo de captura SSR já previne a dupla busca para o carregamento de página de qualquer usuário específico, portanto nenhuma otimização adicional é necessária nesse caso.

Quando múltiplas funções de load em uma hierarquia de rotas buscam dados independentes, o SvelteKit executa as funções de load de layout e de página com concorrência sempre que possível. Você não precisa paralelizar manualmente as requisições entre diferentes arquivos de load. Dentro de uma única função de load, se você precisar de múltiplas requisições independentes, use Promise.all para evitar buscas sequenciais.

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

import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ fetch }) => {
	// These requests are independent. Running them in parallel
	// reduces total load time to the duration of the slowest request
	// rather than the sum of all requests.
	const [statsResponse, activityResponse] = await Promise.all([
		fetch('/api/dashboard/stats'),
		fetch('/api/dashboard/activity')
	])

	if (!statsResponse.ok || !activityResponse.ok) {
		return { stats: null, activity: [] }
	}

	const [stats, activity] = await Promise.all([statsResponse.json(), activityResponse.json()])

	return { stats, activity }
}

Quando NÃO Usar Este Padrão

O padrão event.fetch é a ferramenta certa para carregar dados que uma página precisa antes de poder renderizar. Não é a ferramenta certa para tudo.

Interações exclusivas do cliente não pertencem às funções de load. Se uma ação do usuário dispara uma atualização de dados, como clicar em um botão de atualização ou enviar um formulário de busca, essa interação é tratada pelo componente usando fetch padrão, actions de formulário ou a função invalidate do SvelteKit. A função de load fornece os dados iniciais; as atualizações iniciadas pelo usuário são uma preocupação separada.

Dados em tempo real, como conexões WebSocket ou eventos enviados pelo servidor, não podem ser modelados como uma única chamada fetch em uma função de load. As funções de load são executadas uma vez por navegação. Para recursos em tempo real, estabeleça a conexão em um $effect dentro do componente e gerencie o tempo de vida da conexão lá.

Conjuntos de dados muito grandes não devem ser buscados inteiramente em uma função de load se apenas uma parte será exibida. Use paginação desde o início, conforme demonstrado no exemplo prático, e busque apenas os dados que a visualização atual requer.

Dados opcionais ou secundários que a página pode renderizar sem eles não devem bloquear a renderização inicial ao serem buscados em uma função de load. O SvelteKit suporta streaming de dados adiados usando promises, o que permite que uma página renderize com dados críticos imediatamente enquanto os dados secundários carregam em segundo plano. Esse padrão é abordado em um artigo dedicado nesta série.

Conclusão

O event.fetch do SvelteKit parece uma função familiar, mas carrega cinco capacidades que mudam fundamentalmente como o carregamento de dados funciona em SSR, hidratação e navegação no cliente. URLs relativas são resolvidas corretamente no Node.js. As credenciais são encaminhadas automaticamente para endpoints de mesma origem. Os handlers de rotas internas são chamados diretamente sem uma viagem de ida e volta pela rede. As respostas são capturadas e incorporadas ao payload da página, eliminando o problema de dupla busca durante a hidratação. E todo o mecanismo é consciente do ambiente, funcionando corretamente no Node, no navegador e em runtimes de borda.

Usar o fetch global em uma função de load ignora todas essas capacidades. Não é uma escolha estilística. É um erro de categoria: usar uma ferramenta que foi projetada para um contexto diferente. O evento de load fornece fetch por uma razão, e essa razão é todo o comportamento de rede da sua aplicação SvelteKit.

As implicações práticas são diretas: sempre desestruture fetch do evento de load, verifique response.ok antes de fazer o parse, use o construtor URL para construir URLs parametrizadas, coloque chamadas de API de origens cruzadas atrás de rotas internas +server.ts para manter as credenciais somente no servidor, e confie em Promise.all para requisições paralelas independentes dentro de uma única função de load.

Principais Conclusões

Principais conclusões:

Sempre desestruture fetch do objeto de evento de load. O fetch global não possui nenhuma das cinco capacidades do SvelteKit.
URLs relativas funcionam em funções de load porque o SvelteKit as resolve automaticamente em relação à origem da requisição atual.
Requisições de mesma origem encaminham cookies e cabeçalhos de autorização da requisição do navegador recebida sem nenhum encaminhamento manual.
Buscar uma rota +server.ts interna ignora completamente a rede. A função handler é chamada diretamente.
A captura de resposta SSR previne o problema de dupla busca. Os dados buscados no servidor são incorporados à página e reutilizados no cliente durante a hidratação.
event.fetch funciona de forma idêntica no Node, no navegador e em runtimes de borda. Nenhuma detecção de ambiente ou polyfills são necessários.
Sempre verifique response.ok e use error() de @sveltejs/kit para tratar respostas com falha corretamente.

Leitura Adicional

Documentação de Roteamento do SvelteKit — referência oficial para handlers de rota +server.ts
Documentação de Load do SvelteKit — referência oficial para propriedades do evento de função de load, incluindo fetch