O Que É Prefetching e Por Que Ele Importa

A navegação do lado do cliente no SvelteKit já é rápida em comparação com carregamentos completos de página. Quando um usuário clica em um link, o SvelteKit não recarrega o navegador; ele executa a função load da rota de destino, recebe os dados e re-renderiza apenas os componentes que mudaram. Isso economiza o custo de recarregar JavaScript, CSS e componentes de layout compartilhados.

Mas a função load ainda precisa ser executada quando o usuário clica. Se essa função load faz uma requisição de rede, há uma lacuna de latência entre o clique e o aparecimento do conteúdo, mesmo em conexões rápidas. Em redes móveis ou por trás de APIs lentas, essa lacuna se torna perceptível.

O prefetching fecha essa lacuna ao iniciar a função load antes de o usuário clicar, enquanto ele está passando o cursor sobre o link, ou enquanto o link está entrando na viewport, e armazenando o resultado em cache para que, quando a navegação real acontecer, os dados já estejam disponíveis. Para aplicações com padrões de navegação previsíveis, páginas de listagem com muito conteúdo e caminhos quentes conhecidos, isso pode fazer a navegação parecer genuinamente instantânea.

O SvelteKit oferece duas formas de prefetching: prefetching de dados (executar funções load antecipadamente e armazenar os resultados em cache) e prefetching de código (baixar o JavaScript de uma rota antes de ser necessário). Ambos podem ser aplicados de forma declarativa via atributos HTML em elementos âncora, ou programaticamente via funções de $app/navigation.

A Lacuna de Latência na Navegação

Considere um blog com uma lista de posts em /blog. Cada post tem um título, trecho e um link para /blog/[slug]. Um leitor percorre a lista, encontra um post de interesse e clica no link. A função load do post busca o artigo completo em uma API. Com um round trip de 100ms, o usuário aguarda pelo menos 100ms após clicar antes que qualquer coisa mude. Em uma rede móvel com um round trip de 400ms, a espera se torna claramente perceptível.

Essa latência tem dois componentes: tempo de rede (aguardando o servidor responder) e tempo de código (aguardando o bundle JavaScript da rota ser baixado, caso ainda não tenha sido obtido). Ambos contribuem para a lacuna entre a intenção do usuário e o aparecimento do conteúdo.

Agora imagine que o usuário pausa o mouse sobre o título do post por 150ms antes de clicar, o que é um comportamento humano típico. Sem prefetching, esses 150ms são tempo desperdiçado. Com prefetching, o SvelteKit pode iniciar a função load no hover e ter os dados prontos antes mesmo de o clique ser registrado. O usuário experimenta zero atraso perceptível.

Este é o valor central do prefetching: ele converte o tempo ocioso que o usuário gasta apontando e pensando em trabalho produtivo que o navegador realiza buscando dados e código. É uma das poucas otimizações de performance que fornece um benefício proporcional à velocidade normal de navegação humana, não apenas a condições de rede artificialmente lentas.

data-sveltekit-preload-data: A Abordagem Declarativa

A forma mais simples de habilitar o prefetching é com o atributo data-sveltekit-preload-data em um elemento âncora ou em um contêiner pai. O SvelteKit iniciará o prefetching da função load da rota de destino quando a condição de gatilho for atendida.

O atributo aceita dois valores: hover e tap.

hover

Com hover, o SvelteKit inicia o prefetching quando o usuário move o ponteiro sobre o link, ou quando o link recebe foco via teclado. Este é o gatilho mais agressivo e fornece mais tempo para fazer o prefetch antes de um clique.

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

<script lang="ts">
	import type { PageProps } from './$types'
	let { data }: PageProps = $props()
</script>

<ul>
	{#each data.posts as post}
		<li>
			<a href="/blog/{post.slug}" data-sveltekit-preload-data="hover">
				{post.title}
			</a>
		</li>
	{/each}
</ul>

O atributo também pode ser colocado em um elemento pai para se aplicar a todos os links descendentes:

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

<ul data-sveltekit-preload-data="hover">
	{#each data.posts as post}
		<li>
			<a href="/blog/{post.slug}">{post.title}</a>
		</li>
	{/each}
</ul>

O SvelteKit aplica data-sveltekit-preload-data="hover" ao elemento <body> por padrão em novos projetos, via um atributo data-sveltekit-preload-data na tag <body> raiz em app.html. Isso significa que o prefetching por hover normalmente já está habilitado em toda a sua aplicação sem nenhuma anotação por link.

tap

Com tap, o prefetching é acionado no touchstart (mobile) ou mousedown (desktop), que é o momento em que o dedo do usuário toca a tela ou pressiona o botão do mouse, antes de o evento de clique disparar. Esta é uma janela menor do que hover, mas é mais amigável para dispositivos móveis, já que dispositivos touch não têm estados de hover.

<a href="/blog/{post.slug}" data-sveltekit-preload-data="tap">
	{post.title}
</a>

No desktop, tap é menos eficaz do que hover porque o tempo entre mousedown e click é tipicamente de 100-200ms, em comparação com as várias centenas de milissegundos que um usuário pode passar passando o cursor. Em dispositivos touch, tap é a melhor opção disponível.

Uma Nota sobre o Modo de Economia de Dados

O SvelteKit nunca acionará o prefetching de dados se o usuário tiver habilitado o modo de economia de dados em seu navegador ou SO. Quando navigator.connection.saveData for true, tanto data-sveltekit-preload-data quanto preloadData são silenciosamente ignorados. Este é o comportamento correto: o prefetching é uma sugestão de performance, não um requisito, e deve respeitar as preferências do usuário.

data-sveltekit-preload-code: Prefetching Declarativo de Código

data-sveltekit-preload-code é o equivalente declarativo para prefetching apenas de código. Ao contrário de data-sveltekit-preload-data, ele baixa o bundle JavaScript de uma rota sem executar sua função load. Aceita quatro valores em ordem decrescente de agressividade:

"eager" — faz o preload do código de todos os links na página imediatamente após cada navegação, sem necessidade de interação do usuário
"viewport" — faz o preload do código de links à medida que rolam para dentro da viewport
"hover" — faz o preload no hover do ponteiro ou foco via teclado (mesmo gatilho que data-sveltekit-preload-data="hover")
"tap" — faz o preload no touchstart ou mousedown

Note que "viewport" e "eager" se aplicam apenas a links presentes no DOM imediatamente após a navegação. Links adicionados posteriormente — dentro de blocos {#if}, por exemplo — não são carregados antecipadamente de forma eager; eles recorrem ao comportamento de hover ou tap.

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

<!-- Preload the JavaScript bundle for each post as it enters the viewport -->
<ul data-sveltekit-preload-code="viewport">
	{#each data.posts as post}
		<li>
			<a href="/blog/{post.slug}">{post.title}</a>
		</li>
	{/each}
</ul>

Use data-sveltekit-preload-code quando quiser que o JavaScript da rota esteja disponível antes da navegação, mas não puder prever ou custear a execução da função load com antecedência — por exemplo, se a função load acessa uma API com limite de taxa ou realiza consultas caras ao banco de dados.

preloadData: Prefetching Programático de Dados

A função preloadData de $app/navigation é o equivalente programático de data-sveltekit-preload-data. Chame-a com uma string de URL e o SvelteKit executará as funções load dessa rota e armazenará o resultado em cache, exatamente como se o usuário tivesse passado o cursor sobre o link.

import { preloadData } from '$app/navigation'

// Start prefetching a specific route
await preloadData('/blog/introduction-to-sveltekit')

A função retorna uma promise que resolve com o resultado da execução das funções load da rota. A forma resolvida é uma union discriminada:

type PreloadResult =
	| { type: 'loaded'; status: number; data: Record<string, any> }
	| { type: 'redirect'; location: string }

Na prática, raramente é necessário aguardá-la com await; dispare-a e esqueça quando a intenção for apenas aquecer o cache.

O prefetching programático é útil em situações onde o estado de hover não é significativo, por exemplo, quando um componente é renderizado no servidor e o "gatilho natural" para o prefetching é algo diferente da proximidade do ponteiro.

Prefetching com IntersectionObserver

Um padrão comum é fazer o prefetch de uma rota quando seu link rola para dentro da viewport. Isso é útil para listas paginadas ou de rolagem infinita onde o usuário está claramente se movendo em direção a uma seção da página:

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

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

	let { data }: PageProps = $props()

	function prefetchOnVisible(node: HTMLAnchorElement) {
		const observer = new IntersectionObserver(
			(entries) => {
				for (const entry of entries) {
					if (entry.isIntersecting) {
						const href = node.getAttribute('href')
						if (href) preloadData(href)
						observer.disconnect()
					}
				}
			},
			{ rootMargin: '100px' }
		)

		observer.observe(node)

		return {
			destroy() {
				observer.disconnect()
			}
		}
	}
</script>

<ul>
	{#each data.posts as post}
		<li>
			<a href="/blog/{post.slug}" use:prefetchOnVisible>
				{post.title}
			</a>
		</li>
	{/each}
</ul>

A action Svelte use:prefetchOnVisible anexa um IntersectionObserver a cada link. Quando o link entra na viewport (com uma margem de 100px para que o prefetching inicie ligeiramente antes de o link estar totalmente visível), preloadData é chamado e o observer se desconecta para evitar chamadas repetidas.

Prefetching com Intenção Explícita do Usuário

Outro padrão é fazer o prefetch em resposta a uma intenção clara do usuário, como um resultado de busca sendo destacado ou um cartão sendo focado:

<!-- A search results component -->

<script lang="ts">
	import { preloadData } from '$app/navigation'

	type SearchResult = { title: string; href: string }

	let { results }: { results: SearchResult[] } = $props()

	function handleResultFocus(href: string) {
		preloadData(href)
	}
</script>

{#each results as result (result.href)}
	<a href={result.href} onfocus={() => handleResultFocus(result.href)}>
		{result.title}
	</a>
{/each}

preloadCode: Prefetching do JavaScript da Rota

preloadCode é distinto de preloadData. Onde preloadData executa funções load e armazena os dados em cache, preloadCode apenas baixa o bundle JavaScript de uma rota sem executar sua função load. Ele garante que o código da rota esteja disponível no cache do navegador antes de o usuário navegar para lá.

import { preloadCode } from '$app/navigation'

// Warm the JavaScript cache for all blog post routes
await preloadCode('/blog/*')

preloadCode aceita um pathname ou padrão glob, não um padrão de rota do sistema de arquivos do SvelteKit. Use /blog/* para corresponder a src/routes/blog/[slug]/+page.svelte, ou uma URL concreta como /blog/my-post para corresponder a uma página específica. A notação de colchetes do sistema de arquivos [slug] não é usada aqui.

O prefetching de código é mais valioso em cenários específicos. O primeiro é com bundles de rota grandes, onde o JavaScript de uma página complexa leva um tempo significativo para baixar. Para a maioria das rotas do SvelteKit com divisão de código, os bundles são pequenos o suficiente para que a sobrecarga de download seja negligenciável, mas dashboards com muitos dados e componentes podem ter chunks maiores. O segundo é quando a rota não tem função load, ou os dados da função load não são previsíveis, de modo que o prefetching de dados não é útil, mas colocar o código no cache ainda ajuda.

O padrão típico é usar preloadCode para rotas que o usuário provavelmente visitará em breve, mas onde não é possível prever a URL específica:

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

<script lang="ts">
	import { preloadCode, goto } from '$app/navigation'
	import { onMount } from 'svelte'

	// Preload the blog post bundle as soon as the listing page mounts,
	// since most users landing on the listing will click a post
	onMount(() => {
		preloadCode('/blog/*')
	})
</script>

Como o Cache de Prefetch Funciona

Quando o SvelteKit faz o prefetch dos dados de uma rota, ele executa as funções load e armazena os resultados em um cache em memória indexado por URL. O cache não é persistido entre carregamentos de página; é um cache de nível de sessão que dura enquanto o runtime JavaScript estiver ativo.

Quando o usuário realmente navega para uma URL que foi prefetchada, o SvelteKit verifica o cache primeiro. Se um resultado recente estiver disponível, ele o usa imediatamente, fazendo a navegação parecer síncrona. Se a entrada do cache estiver muito antiga ou tiver sido invalidada, o SvelteKit executa a função load novamente.

A duração do cache é definida pelo tempo que leva para um resultado prefetchado expirar antes de o usuário navegar. O SvelteKit não armazena dados prefetchados em cache por minutos; ele os armazena pelo breve intervalo entre o prefetching e a navegação. Um usuário que passa o cursor por 200ms e depois clica obtém o resultado do cache. Um usuário que passa o cursor por dois minutos e depois clica provavelmente aciona um carregamento novo.

Como o Prefetching Interage com o Rastreamento de Dependências

O cache de prefetch respeita o sistema de rastreamento de dependências do SvelteKit. Se uma função load depende de params.slug e você faz o prefetch de /blog/post-one, o resultado em cache é indexado para /blog/post-one. O prefetch de /blog/post-two é uma entrada de cache separada. Este é o comportamento correto: o cache é específico por URL.

Se uma função load declara um identificador depends() personalizado e esse identificador é invalidado antes de a navegação ser concluída, o resultado do prefetch em cache é tratado como obsoleto e descartado. O SvelteKit re-executa a função load na navegação real. Isso garante a correção: você nunca verá dados prefetchados que um invalidate() subsequente teria limpado.

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

export const load: PageServerLoad = async ({ depends, fetch }) => {
	depends('app:feed')

	const res = await fetch('/api/feed/latest')
	return { items: await res.json() }
}

Se esta rota for prefetchada enquanto o usuário está em outra página, e então invalidate('app:feed') for chamado antes de a navegação ocorrer, o cache de prefetch é limpo e a função load é reexecutada na navegação. O prefetching é uma otimização de performance, não um bypass de consistência de dados.

Erros Comuns e Anti-Padrões

Pré-carregando Todos os Links Incondicionalmente

Pré-carregar todos os links de uma página é tentador, mas desperdiçador. Uma página com vinte links poderia disparar vinte execuções simultâneas de funções de carregamento ao passar o cursor, gerando vinte chamadas de API para as quais a maioria nunca será navegada. Isso desperdiça recursos do servidor, pode acionar limites de taxa e pode sobrecarregar caches de banco de dados compartilhados com dados obsoletos ou irrelevantes.

<!-- Avoid: Blanket prefetching on a large list -->

<ul data-sveltekit-preload-data="hover">
	{#each data.allProducts as product}
		<!-- Each of these prefetches on hover — may trigger hundreds of API calls -->
		<a href="/products/{product.id}">{product.name}</a>
	{/each}
</ul>

<!-- Preferred: Prefetch only high-probability navigation targets -->

<ul>
	{#each data.featuredProducts as product}
		<!-- Featured items are likely to be clicked; prefetch them -->
		<a href="/products/{product.id}" data-sveltekit-preload-data="hover">
			{product.name}
		</a>
	{/each}

	{#each data.otherProducts as product}
		<!-- Long tail items: code-only prefetch or none -->
		<a href="/products/{product.id}">
			{product.name}
		</a>
	{/each}
</ul>

Reserve o pré-carregamento de dados para rotas com alta probabilidade de navegação. Use preloadCode para todo o resto, se o tamanho do bundle justificar.

Chamando preloadData Dentro da Função de Carregamento

O pré-carregamento é uma ferramenta de desempenho de navegação do lado do navegador. Chamar preloadData dentro de uma função de carregamento do servidor ou durante o SSR não terá efeito e pode lançar um erro dependendo do ambiente.

// Wrong: preloadData belongs in component code, not load functions

export const load: PageServerLoad = async ({ params }) => {
	await preloadData(`/blog/${params.slug}/comments`) // ← No effect on the server
	return { post: {} }
}

<!-- Correct: preloadData called in response to user interaction -->

<script lang="ts">
	import { preloadData } from '$app/navigation'
</script>

<a
	href="/blog/{post.slug}/comments"
	onmouseenter={() => preloadData(`/blog/${post.slug}/comments`)}
>
	Read comments
</a>

Ignorando Interações com a Plataforma e CDN

O pré-carregamento faz requisições HTTP. Se suas funções de carregamento chamam APIs protegidas por limites de taxa, geram carga no backend ou disparam consultas caras ao banco de dados, o pré-carregamento agressivo pode ter custos reais de infraestrutura. Páginas acessíveis publicamente também terão suas funções de carregamento executadas para requisições de pré-carregamento provenientes de tráfego não autenticado ou gerado por bots, caso esses bots disparem eventos de hover — embora isso seja raro na prática.

Se a função de carregamento de uma rota for cara e os usuários raramente navegarem até ela a partir de uma página de listagem, prefira preloadCode em vez de preloadData para colocar o bundle no cache sem executar o trabalho do lado do servidor.

Considerações de Desempenho e Escalabilidade

O pré-carregamento baseado em hover oferece mais benefícios em aplicações desktop com navegação acessível por teclado. Em aplicações móveis onde o hover não é significativo, o pré-carregamento baseado em tap oferece um benefício menor, mas ainda real. O pré-carregamento baseado em IntersectionObserver é eficaz para interfaces com muitas listas, onde a direção de rolagem do usuário indica intenção.

O ganho do pré-carregamento é proporcional à latência da sua função de carregamento. Se suas funções de carregamento retornam em 10ms a partir de um cache em memória, o pré-carregamento oferece pouco benefício adicional, pois os dados chegam rapidamente mesmo sem ele. Se suas funções de carregamento levam 200-500ms porque fazem chamadas a APIs externas ou executam consultas complexas ao banco de dados, o pré-carregamento ao passar o cursor pode essencialmente eliminar essa latência percebida para usuários que seguem padrões normais de apontamento.

O pré-carregamento de código com preloadCode tem um cálculo de custo-benefício mais claro. O bundle JavaScript de uma rota é baixado uma vez e armazenado em cache pelo navegador. O custo é a largura de banda; o benefício é que navegações futuras para essa rota não precisam baixar o bundle primeiro. Para rotas com grandes árvores de componentes, bibliotecas específicas da rota ou bundles de editor, isso pode ser significativo.

Conclusão

O pré-carregamento é uma das ferramentas de desempenho mais visíveis ao usuário do SvelteKit, pois afeta diretamente o tempo entre o clique do usuário e a exibição da página. Ao iniciar as funções de carregamento enquanto o usuário ainda está decidindo clicar, o pré-carregamento de dados baseado em hover converte o tempo ocioso do ponteiro em tempo produtivo de rede.

A abordagem declarativa com data-sveltekit-preload-data não requer alterações de código e é adequada para a maioria dos links na maioria das páginas. A função programática preloadData permite um controle mais refinado para gatilhos baseados em viewport, interfaces de busca e sinais explícitos de intenção. preloadCode lida com o caso complementar de aquecer o cache JavaScript sem executar o trabalho da função de carregamento.

Usado de forma cuidadosa, em alvos de navegação com alta probabilidade e latência significativa da função de carregamento, o pré-carregamento pode fazer a diferença entre uma aplicação que parece rápida e uma que parece instantânea.

Principais Conclusões

data-sveltekit-preload-data="hover" em um elemento âncora ou elemento pai dispara o pré-carregamento de dados quando o ponteiro entra no elemento. O SvelteKit aplica isso ao <body> por padrão em novos projetos. tap é disparado em touchstart ou mousedown e é o gatilho correto para interfaces com foco em toque.

preloadData(href) de $app/navigation executa as funções de carregamento de uma rota programaticamente e armazena o resultado em cache. Use-o para gatilhos baseados em viewport ou em intenção via IntersectionObserver ou eventos de foco.

data-sveltekit-preload-code é o equivalente declarativo para pré-carregamento somente de código. Aceita "eager" (todos os links da página imediatamente), "viewport" (à medida que os links entram no viewport), "hover" e "tap". Observe que "eager" e "viewport" se aplicam apenas a links presentes no DOM no momento da navegação, não a links adicionados dinamicamente.

preloadCode(pathname) baixa o bundle JavaScript de uma rota programaticamente sem executar sua função de carregamento. Passe um padrão glob como /blog/* para corresponder a rotas dinâmicas, ou uma URL concreta para uma página específica. Não use a sintaxe de sistema de arquivos [param] — preloadCode usa padrões glob.

Nem data-sveltekit-preload-data nem preloadData serão disparados quando navigator.connection.saveData for true. O SvelteKit respeita automaticamente a preferência de dados reduzidos do usuário.

O cache de pré-carregamento é indexado por URL e tem escopo de sessão. Ele respeita as declarações de depends(): se uma dependência personalizada for invalidada após o pré-carregamento e antes da navegação, o resultado pré-carregado é descartado e a função de carregamento é executada novamente. O pré-carregamento é sempre uma dica de desempenho, nunca uma forma de contornar a consistência de dados.

O Que Vem a Seguir

O pré-carregamento é o último grande tópico de desempenho desta série. O artigo final reúne tudo no contexto de um tópico que depende de quase todos os conceitos abordados até agora: autenticação. O próximo artigo, Padrões de Autenticação em Funções de Carregamento, aborda por que guardas de autenticação no nível de layout não são confiáveis, como locals e hooks.server.ts formam a base correta, e como construir um utilitário requireLogin() reutilizável que funciona em qualquer função de carregamento do servidor da sua aplicação.

Leitura Adicional

Documentação de Opções de Link do SvelteKit — referência oficial para data-sveltekit-preload-data, data-sveltekit-preload-code e todos os outros atributos de comportamento de link
SvelteKit $app/navigation — referência oficial para preloadData, preloadCode, goto e invalidate
Reexecutando Funções de Carregamento e Rastreamento de Dependências — como depends() e invalidate() interagem com o cache de pré-carregamento
Carregamento Paralelo e Evitando Cascatas — o modelo de execução paralela de carregamento que torna o pré-carregamento eficaz: entendendo o que é executado simultaneamente dentro de uma operação de pré-carregamento