Por Que as Funções Load Existem

Toda aplicação web eventualmente precisa buscar dados antes de renderizar algo significativo para o usuário. Uma página de produto precisa do produto. Um painel precisa das métricas. Um perfil de usuário precisa dos detalhes da conta. A questão não é se você vai buscar dados — é onde e quando você vai fazer isso, e o que acontece enquanto você espera.

O SvelteKit tem uma resposta específica e bem fundamentada para essa questão: a função load. Antes que um componente de página seja renderizado, o SvelteKit oferece um lugar dedicado para buscar tudo o que a página precisa, e garante que os dados estarão prontos antes que qualquer marcação apareça na tela. Isso não é um middleware adicionado à força ou um hook de ciclo de vida que você precisa lembrar de chamar — é uma parte de primeira classe de como as rotas do SvelteKit funcionam.

Este artigo aborda o que são as funções load, por que o framework foi projetado em torno delas e como escrever uma corretamente desde o início. Ao final, você terá uma compreensão completa das convenções de arquivo envolvidas, como os dados fluem de uma função load para o componente de página e como os tipos TypeScript gerados pelo SvelteKit tornam tudo completamente seguro em termos de tipos sem nenhum esforço manual.

Uma escolha deliberada se aplica a todos os artigos desta série: nenhum ORM, nenhum query builder, nenhuma biblioteca de cliente de banco de dados aparece em qualquer lugar nos exemplos de código. Todo acesso a dados é expresso por meio de chamadas fetch do SvelteKit para endpoints de API.

Isso mantém cada exemplo agnóstico em relação ao banco de dados — os padrões funcionam de forma idêntica, seja seu backend usando PostgreSQL, SQLite, MongoDB, uma API REST de terceiros ou qualquer outra coisa. O foco é em como as funções load do SvelteKit funcionam, não em qualquer camada de dados específica por trás delas.

Se você está usando Prisma, Drizzle ou uma ferramenta similar em sua própria aplicação, a estrutura da função load é idêntica; a única diferença é o que fica dentro do corpo da função.

O Problema

Para apreciar o que as funções load resolvem, é útil pensar nas alternativas.

A abordagem mais óbvia, e a que os desenvolvedores vindos de frameworks client-side costumam buscar primeiro, é buscar dados dentro do próprio componente. Você define algum estado reativo, inicia uma requisição fetch quando o componente é montado e atualiza o estado quando os dados chegam. Enquanto isso, você renderiza um spinner de carregamento ou uma tela esqueleto.

<!-- src/routes/articles/[slug]/+page.svelte -->
<!-- This pattern works, but it has real costs. -->

<script lang="ts">
	import { onMount } from 'svelte'

	let article = $state<Article | null>(null)
	let loading = $state(true)
	let error = $state<string | null>(null)

	onMount(async () => {
		try {
			const res = await fetch(`/api/articles/${slug}`)
			article = await res.json()
		} catch (e) {
			error = 'Failed to load article'
		} finally {
			loading = false
		}
	})
</script>

{#if loading}
	<p>Loading...</p>
{:else if error}
	<p>{error}</p>
{:else}
	<h1>{article?.title}</h1>
{/if}

Esse padrão funciona, mas tem custos reais em uma aplicação com renderização no servidor. onMount nunca é executado durante o SSR, ele só é executado no browser. Isso significa que o servidor inicialmente retorna HTML sem o conteúdo do artigo, o cliente renderiza um estado de carregamento e somente após a hidratação é que o fetch acontece e a página finalmente é preenchida.

Você acaba com uma experiência pior para os usuários (uma transição visível de "vazio → carregando → conteúdo") e resultados piores para SEO e pré-visualizações em redes sociais (o HTML inicial não tem o conteúdo significativo). Você também paga latência extra porque os dados são recuperados depois que a página já foi entregue.

Um "próximo passo" comum é introduzir endpoints +server.ts e fazer fetch deles no componente. Isso pode ser apropriado quando você realmente precisa de uma API pública, mas como estratégia padrão de carregamento de dados, frequentemente é overhead desnecessário: você está construindo e mantendo um endpoint HTTP principalmente para que seu próprio frontend possa chamar de volta para seu próprio backend. Em outras palavras, você criou um salto extra — browser → seu servidor → fonte de dados upstream — mesmo que o servidor pudesse ter carregado os dados antes de renderizar.

Ambas as abordagens compartilham o mesmo problema subjacente: os dados são buscados reativamente (depois que o componente foi montado) em vez de declarativamente (como pré-requisito para a renderização).

reativamente: O componente renderiza primeiro, depois busca dados e se atualiza quando eles chegam. Esse é o padrão padrão em frameworks client-side e funciona bem para aplicações puramente renderizadas no cliente. Porém, isso pode parecer lento e brusco, especialmente em conexões mais lentas. Também significa que o HTML inicial enviado pelo servidor está incompleto, o que prejudica o SEO e as pré-visualizações em redes sociais.

declarativamente: O componente declara quais dados precisa, e o framework garante que esses dados estejam disponíveis antes que o componente seja renderizado. Esse é o padrão que o SvelteKit incentiva com as funções load. Isso leva a uma performance percebida mais rápida, melhor SEO e uma experiência de usuário mais fluida.

As funções load do SvelteKit buscam o que a rota precisa antecipadamente, depois renderizam a página com dados completos desde o início.

Princípios

O SvelteKit organiza sua aplicação em rotas, e cada rota é um diretório sob src/routes. Um diretório de rota pode conter vários arquivos especiais que o SvelteKit trata com significado específico. Você provavelmente já está familiarizado com +page.svelte, que contém o componente que é renderizado para aquela rota.

A percepção fundamental é que +page.svelte não é o único arquivo que uma rota pode ter. O SvelteKit suporta um arquivo complementar chamado +page.js (ou +page.ts para TypeScript) que fica ao seu lado. Esse arquivo tem uma única função: exportar uma função load que busca ou deriva quaisquer dados que a página precisa. O SvelteKit chamará essa função antes de renderizar o componente, aguardará sua resolução e então passará seu valor de retorno para o componente como uma prop data.

O fluxo funciona assim:

Não há configuração manual. Você não chama a função load por conta própria, não assina nenhuma store nem passa dados por props através dos limites de componentes. O SvelteKit cuida da conexão entre a função load e o componente automaticamente, usando a convenção de nomenclatura de arquivos como contrato.

Esse modelo tem uma consequência importante para a renderização no servidor. Quando um usuário carrega uma página pela primeira vez, a função load é executada no servidor. O componente recebe dados totalmente resolvidos e renderiza HTML completo. Quando o usuário navega para outra página dentro da aplicação, a função load é executada no browser, buscando apenas os dados necessários para aquela nova rota sem um recarregamento completo da página. Você escreve a função uma vez, e o SvelteKit decide onde executá-la com base no contexto.

Implementação

Passo 1: Criar a Estrutura da Rota

A convenção de pareamento de arquivos é o que faz tudo funcionar, então vale ser preciso sobre ela. Para uma rota em /articles/[slug], você precisa de dois arquivos no mesmo diretório:

src/
└── routes/
    └── articles/
        └── [slug]/
            ├── +page.ts       ← the load function lives here
            └── +page.svelte   ← the component renders here

A relação entre os dois arquivos é simples: +page.ts é executado primeiro e passa seus dados para +page.svelte. O SvelteKit os conecta automaticamente por meio da nomenclatura de arquivos — sem import, sem chamada explícita, sem assinatura de store.

O nome do diretório [slug] é um segmento dinâmico. O SvelteKit capturará o que aparecer naquela posição na URL e o disponibilizará dentro da sua função load por meio do objeto params. Se a URL for /articles/building-with-sveltekit, então params.slug será 'building-with-sveltekit'.

Passo 2: Escrever a Função Load

Uma função load é uma exportação nomeada do arquivo +page.ts. Ela recebe um único argumento que o SvelteKit preenche com contexto sobre a requisição atual, e retorna um objeto simples contendo quaisquer dados que a página precisa.

Aqui está um primeiro exemplo realista de busca de um artigo em uma API de CMS:

// src/routes/articles/[slug]/+page.ts

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

export const load: PageLoad = async ({ params, fetch }) => {
	const response = await fetch(`https://cms.example.com/api/articles/${params.slug}`)

	if (!response.ok) {
		// We will cover proper error handling in a later article.
		// error() signals a controlled failure and renders the nearest +error.svelte.
		error(response.status, `Failed to fetch article: ${response.status}`)
	}

	const article = await response.json()

	return {
		article
	}
}

Há várias coisas que vale examinar cuidadosamente neste código.

params

O objeto params é tipado com base nos segmentos dinâmicos da sua rota. Para esta rota, o TypeScript informará que params.slug é uma string. Se você tivesse uma rota como /shop/[category]/[productId], tanto params.category quanto params.productId estariam disponíveis e tipados.

O valor de retorno é um objeto simples. Tudo o que você colocar aqui fica disponível no componente de página. Você não está limitado a uma única chave; retornar múltiplos valores é comum e incentivado em vez de criar múltiplas funções load separadas.

fetch

O fetch usado aqui não é o fetch nativo do browser. É uma versão especial fornecida pelo SvelteKit através do argumento do evento load. Você deve sempre usar esta em vez de chamar o fetch global diretamente.

A versão do SvelteKit pode fazer requisições relativas no servidor (o fetch nativo não consegue), herda os cookies do usuário atual para que requisições com credenciais funcionem corretamente, e durante a renderização no servidor captura a resposta e a incorpora no HTML para que o browser não precise fazer a mesma requisição novamente durante a hidratação.

Usar o fetch global em vez do fornecido pelo SvelteKit é um erro comum no código SvelteKit inicial, e quebra a consistência da hidratação de maneiras que podem ser sutis de depurar.

Passo 3: Acessar os Dados no Componente de Página

Assim que a função load retorna, o SvelteKit disponibiliza seu valor de retorno para +page.svelte por meio de uma prop chamada data. Você a acessa usando $props(), que é a rune do Svelte 5 para declarar props.

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

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

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

<article>
	<h1>{data.article.title}</h1>
	<p class="meta">Published {data.article.publishedAt}</p>
	<div class="content">
		<!-- data.article.content is sanitised server-side before storage -->
		{@html data.article.content}
	</div>
</article>

O tipo PageProps é gerado automaticamente pelo SvelteKit a partir do seu arquivo +page.ts. Ele sabe exatamente qual formato data tem porque pode ver o que sua função load retorna. Isso significa que data.article é totalmente tipado — você obtém autocomplete, verificação de tipos e suporte a refatoração para toda a cadeia, da função load ao template, tudo sem escrever uma única interface manual para o formato dos dados.

Essa geração de tipos acontece por meio da importação ./$types, que aponta para um arquivo no diretório oculto .svelte-kit/types do SvelteKit. Você nunca precisa olhar ou editar este arquivo. O SvelteKit o regenera toda vez que você salva, e seu IDE o lê automaticamente.

Passo 4: Entendendo o Sistema de Tipos

O SvelteKit gera vários aliases de tipo para cada rota, e saber qual usar em cada situação merece um momento de atenção.

PageLoad

PageLoad é o tipo da própria função load. Você o usa para tipar a exportação load em +page.ts. Ele garante que os argumentos que o SvelteKit passa — params, fetch, url e os demais — sejam todos corretamente tipados para sua rota específica.

// src/routes/articles/[slug]/+page.ts

// PageLoad types the load function and its arguments
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params }) => {
	// params.slug is typed as string because of the [slug] route segment
	return { slug: params.slug }
}

PageProps

PageProps é o tipo das props que +page.svelte recebe. Inclui uma propriedade data cujo tipo é inferido a partir do que sua função PageLoad retorna. Você o usa para tipar as props desestruturadas na chamada $props() do seu componente.

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

<script lang="ts">
	// PageProps types the component's incoming data prop
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
	// data.slug is typed as string — inferred from the load function's return
</script>

Se você estiver usando uma versão mais antiga do SvelteKit (anterior à 2.16.0), PageProps não existia e você tinha que tipar data separadamente usando PageData. O padrão ficava assim: let { data }: { data: PageData } = $props(). Se você encontrar isso em código mais antigo, é funcionalmente equivalente — apenas mais verboso.

Erros Comuns e Anti-Padrões

Usar o fetch Global em Vez do fetch da Função Load

Este é de longe o erro mais frequente no código SvelteKit inicial. O fetch global e o fetch de load do SvelteKit parecem idênticos no ponto de chamada, o que torna o erro fácil de não perceber.

// src/routes/products/[id]/+page.ts

// AVOID: Using the global fetch
export const load: PageLoad = async ({ params }) => {
	const res = await fetch(`/api/products/${params.id}`)
	return { product: await res.json() }
}

// src/routes/products/[id]/+page.ts

// PREFERRED: Using the fetch provided by the load event
export const load: PageLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/products/${params.id}`)
	return { product: await res.json() }
}

O fetch global tem três problemas no contexto de uma função load.

Ele não pode fazer requisições com URL relativa no servidor — você precisaria fornecer a origem completa, o que é difícil de construir corretamente.
Ele não herda os cookies de sessão do usuário, então qualquer requisição autenticada falhará ou retornará dados para um usuário anônimo.
O SvelteKit não consegue interceptá-lo para incorporar a resposta no HTML renderizado no servidor, o que significa que o browser fará uma segunda requisição idêntica durante a hidratação. O fetch fornecido lida com todos os três casos corretamente sem configuração adicional.

Buscar Dados no Componente em Vez da Função Load

É tentador fazer um fetch secundário pequeno dentro do próprio componente, especialmente para dados que parecem "menos importantes" — como uma barra lateral de artigos relacionados, uma contagem de comentários ou uma bio do autor. O problema é que qualquer fetch dentro do componente é executado após o componente ser montado, o que significa que um estado de carregamento é inevitável e os dados não estão disponíveis para a renderização no servidor.

<!-- AVOID: Fetching inside the component -->

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

	let { data }: PageProps = $props()

	// This will not render on the server and creates a loading flash
	let relatedArticles = $state<Article[]>([])
	onMount(async () => {
		const res = await fetch(`/api/articles/related/${data.article.id}`)
		relatedArticles = await res.json()
	})
</script>

// PREFERRED: Return everything from the load function

// src/routes/articles/[slug]/+page.ts
export const load: PageLoad = async ({ params, fetch }) => {
	const [articleRes, relatedRes] = await Promise.all([
		fetch(`https://cms.example.com/api/articles/${params.slug}`),
		fetch(`https://cms.example.com/api/articles/${params.slug}/related`)
	])

	return {
		article: await articleRes.json(),
		relatedArticles: await relatedRes.json()
	}
}

A versão correta usa Promise.all para buscar ambos os dados simultaneamente, de modo que não haja penalidade de cascata. Ambos os conjuntos de dados estão disponíveis imediatamente quando o componente renderiza, inclusive durante a renderização no servidor. Abordaremos os detalhes do carregamento paralelo em um artigo posterior.

Esquecendo de Usar $types para Segurança de Tipos

É possível escrever uma função de load sem importar PageLoad de forma alguma — o TypeScript inferirá alguns tipos e o código funcionará. Mas você perde a garantia de que o tipo de retorno da sua função de load corresponde ao que o componente espera, e perde a tipagem precisa nos argumentos do evento de load, como params.

// src/routes/articles/[slug]/+page.ts

// WEAK: No explicit typing — TypeScript will infer loosely
export async function load({ params, fetch }) {
	const res = await fetch(`/api/articles/${params.slug}`)
	return { article: await res.json() }
}

// src/routes/articles/[slug]/+page.ts

// PREFERRED: Explicit PageLoad type — params.slug is typed, return is tracked
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/articles/${params.slug}`)
	return { article: await res.json() }
}

Sempre importe de ./$types. Ele é gerado para sua rota específica e fornece a tipagem mais precisa possível. Pular essa etapa pode parecer um atalho pequeno, mas quebra a cadeia de segurança de tipos ponta a ponta que torna a refatoração e a manutenção significativamente mais seguras em aplicações maiores.

Considerações de Performance e Escalabilidade

As funções de load são projetadas para performance desde o início, mas há alguns padrões a serem observados conforme sua aplicação cresce.

O SvelteKit rastreia o que cada função de load acessa — especificamente quais propriedades de params e url ela lê — e usa essas informações para decidir se a função precisa ser executada novamente durante a navegação no lado do cliente. Se você navegar de um post de blog para outro, o SvelteKit sabe que params.slug mudou, então ele re-executa a função de load da página.

Mas se você navegar entre diferentes seções do site que compartilham o mesmo layout, a função de load do layout só será re-executada se os dados dos quais ela depende tiverem mudado. Esse rastreamento de dependências é automático e não requer configuração, mas significa que você deve acessar exatamente as propriedades de params e url de que precisa. Não desestruture tudo de url se você só precisar de url.pathname, pois leituras desnecessárias criam dependências desnecessárias.

Para as chamadas de fetch em si, o SvelteKit elimina duplicatas de requisições durante a renderização no lado do servidor. Se sua função de load e a função de load de um layout buscarem a mesma URL, o SvelteKit fará apenas uma requisição de rede. Essa deduplicação depende do uso consistente do fetch aprimorado, o que significa mais um motivo pelo qual o fetch global é problemático.

À medida que suas funções de load se tornam mais complexas e retornam mais dados, a inferência do TypeScript através do limite do $types permanece rápida porque os tipos gerados são tipos de objeto simples, não genéricos condicionais complexos. Mesmo objetos de retorno muito grandes são verificados de tipo com eficiência.

Quando NÃO Usar Este Padrão

As funções de load são a ferramenta certa para dados que a página precisa antes de poder renderizar seu conteúdo principal. Elas nem sempre são a ferramenta certa para cada dado em uma aplicação.

Dados que mudam em tempo real — como um ticker de ações ao vivo, um feed de mensagens de chat ou um indicador de presença — não pertencem a uma função de load, pois as funções de load são executadas uma vez por navegação, não continuamente. Esse tipo de dado é melhor servido por uma conexão WebSocket ou um fluxo de Server-Sent Events gerenciado dentro do componente.

Dados que dependem de interação do usuário em vez de parâmetros de rota também são um encaixe ruim. Se o usuário estiver filtrando uma lista clicando em chips, aplicar esse filtro por meio de uma função de load exigiria um evento de navegação a cada clique. Isso é pesado demais — a filtragem no lado do cliente de dados já carregados, ou uma API de busca chamada de dentro do componente, lida com isso de forma mais natural.

Há também uma distinção significativa entre +page.ts e +page.server.ts que este artigo intencionalmente adiou. A função de load mostrada aqui é executada tanto no servidor quanto no navegador, o que é adequado para APIs públicas que não requerem credenciais ou variáveis de ambiente privadas. Se sua função de load precisar acessar um banco de dados diretamente, ler um segredo exclusivo do servidor ou inspecionar um cookie de sessão, ela pertence a +page.server.ts. Essa distinção entre load universal versus load de servidor é o tema do próximo artigo desta série.

Conclusão

As funções de load são a resposta do SvelteKit a uma pergunta que toda aplicação web precisa responder: quando e onde os dados são buscados? Ao tornar a função de load uma companheira do componente de página — com um contrato claro entre eles e geração automática de tipos conectando os dois — o SvelteKit transforma a busca de dados de um efeito colateral imperativo em um pré-requisito declarativo da renderização.

O resultado prático são páginas que chegam totalmente renderizadas, sem flashes de carregamento na primeira visita, sem incompatibilidades de hidratação, e com um sistema de tipos que valida todo o pipeline de dados do servidor ao template sem nenhuma escrita manual de tipos. A convenção de arquivo do +page.ts ao lado do +page.svelte torna o relacionamento visível de relance em qualquer explorador de arquivos.

Compreender bem essa base torna cada tópico mais avançado no sistema de carregamento de dados do SvelteKit mais fácil de raciocinar, porque tudo se constrói sobre o mesmo modelo básico: funções que são executadas antes da página renderizar, retornam objetos simples e entregam esses dados diretamente ao componente.

Principais Conclusões

A função de load é uma exportação nomeada de +page.ts (ou +page.js) que o SvelteKit chama automaticamente antes de renderizar o componente +page.svelte associado. Seu valor de retorno se torna a prop data do componente, tipada ponta a ponta pelos tipos gerados PageLoad e PageProps de ./$types.

Sempre use o fetch fornecido pelo argumento do evento de load em vez do fetch global. A versão fornecida lida com URLs relativas no servidor, herda os cookies do usuário para requisições autenticadas e se integra ao sistema de hidratação do SvelteKit para evitar requisições de rede duplicadas.

As funções de load são executadas no servidor durante o SSR e no navegador durante a navegação no lado do cliente. Essa execução em ambiente duplo é o que faz o padrão funcionar — ou seja, o mesmo código produz HTML renderizado no servidor para primeiras visitas e atualizações rápidas, apenas com dados, para navegações subsequentes.

O Que Vem a Seguir

Agora que você entende como uma única página carrega seus dados, a próxima pergunta natural é sobre escopo. O que acontece quando múltiplas páginas em uma seção do seu aplicativo precisam dos mesmos dados — como um menu de navegação, um objeto de usuário, um conjunto de permissões? É isso que as funções de load de layout resolvem, e elas seguem exatamente o mesmo padrão que as funções de load de página, com uma diferença importante em como seus dados são compartilhados. O próximo artigo desta série, Dados de Página vs Dados de Layout, aborda exatamente isso.

Leitura Adicional

Roteamento SvelteKit — entendendo as convenções de arquivo das quais as funções de load fazem parte
Documentação Oficial de Load do SvelteKit — a referência autoritativa para todas as opções de função de load