As Três Entradas de URL

Uma função load que sempre retorna os mesmos dados independentemente do contexto não é particularmente útil. Aplicações reais precisam responder à URL atual: qual post de blog está sendo lido, qual página de uma listagem de produtos está ativa, qual categoria está selecionada, qual consulta de busca foi inserida. Todas essas informações já estão presentes na URL — o papel do SvelteKit é entregá-las à sua função load de forma estruturada e tipada.

Toda função load recebe várias APIs de requisição/evento (como fetch, parent, depends e untrack) mais três entradas específicas de URL. Este artigo foca nessas entradas específicas de URL porque cada uma responde a uma pergunta diferente:

qual recurso está sendo solicitado
como o usuário deseja visualizá-lo
qual tipo de rota está ativo no momento

Compreender as três, e saber qual usar em cada situação, é o que separa funções load que meramente funcionam de funções load que funcionam de forma eficiente e correta em todas as condições de navegação.

Para as APIs de load não relacionadas à URL, consulte Fetch em Funções Load, Usando Dados do Pai em Funções Load, Cookies e Headers em Server Load e Reexecução de Funções Load e Rastreamento de Dependências.

Este artigo apresenta cada entrada, explica uma restrição sutil mas importante em torno de fragmentos hash que pega os desenvolvedores de surpresa, e une tudo em uma listagem completa de produtos com filtragem por categoria e paginação. Você verá por que o estado orientado por URL é preferível à memória de componente para qualquer coisa que deva ser compartilhável, favoritável ou renderizada no servidor.

A URL como Entrada

Imagine construir uma página de listagem de produtos onde os usuários podem filtrar por categoria e navegar pelos resultados. A questão não é se usar estado reativo para rastrear a seleção de filtro atual — é claro que você vai usar. A questão é onde esse estado vive.

O estado reativo no nível do componente é o lugar certo para interações de UI efêmeras e locais à sessão: se um dropdown está aberto, qual painel de acordeão está expandido, o que o usuário digitou mas ainda não enviou. Esse tipo de estado não tem significado fora da sessão atual e nenhuma razão para existir em uma URL.

Seleções de filtro e posições de paginação são uma categoria de estado completamente diferente. Elas definem uma visão específica e significativa dos seus dados que deve sobreviver a uma atualização de página, que um colega deve conseguir abrir diretamente a partir de um link compartilhado, que o botão voltar do navegador deve conseguir restaurar, e que os mecanismos de busca devem conseguir indexar como uma URL distinta.

Quando um estado como esse vive apenas na memória do componente, ele falha em todos esses requisitos silenciosamente. O usuário atualiza: o filtro desaparece. Ele compartilha a URL: o destinatário vê a visão padrão. Ele pressiona voltar: a paginação é redefinida. Bots rastreiam: apenas a primeira página sem filtro é descoberta.

A solução é codificar o estado que define a visão na URL desde o início, e então lê-lo de volta na função load a cada navegação. Uma URL como /products?category=tools&page=2 é favoritável, compartilhável, visível para rastreadores e consciente do histórico sem custo adicional algum. Essas propriedades vêm gratuitamente do tratamento de URLs pelo navegador, não de nenhuma mágica do framework.

O único trabalho necessário é saber como ler parâmetros de consulta corretamente dentro de uma função load, que é exatamente o que este artigo aborda.

As Três Entradas

Toda função load recebe três entradas relacionadas à URL, todas derivadas da mesma fonte — a URL da requisição atual —, mas cada uma expondo uma fatia diferente dela.

params

params responde à pergunta: qual recurso específico está sendo solicitado?

Ele contém os valores resolvidos de cada segmento dinâmico na rota. Quando uma rota é definida como src/routes/blog/[slug] e o usuário visita /blog/my-first-post, o SvelteKit extrai slug da URL e o coloca em params como params.slug = 'my-first-post'. O tipo de params é gerado automaticamente a partir dos nomes dos diretórios da rota, então o TypeScript sabe exatamente quais chaves são válidas para qualquer rota.

url

url responde à pergunta: como o usuário deseja visualizá-lo?

É uma instância padrão URL da web — a URL completa já analisada, com propriedades tipadas para pathname, origin, hostname e parâmetros de busca. Você nunca divide strings ou chama new URL() manualmente; ela chega pronta para leitura. A propriedade mais importante para carregamento de dados é url.searchParams, que fornece acesso estruturado à string de consulta.

route

route responde à pergunta: que tipo de página é esta?

Ele carrega informações sobre a estrutura da rota em si, independente dos valores específicos na URL atual. Sua propriedade route.id é o padrão da rota relativo a src/routes, com os nomes dos segmentos dinâmicos em sua forma original com colchetes. Para a mesma URL acima, route.id seria /blog/[slug], enquanto params.slug seria 'my-first-post'. A distinção importa quando você precisa raciocinar sobre qual tipo de página está ativa — para análises, logs ou lógica condicional — em vez de qual recurso específico.

Juntando esses três, uma URL como /shop/tools?page=2&q=hammer#featured mapeia para as entradas assim:

/shop/tools?page=2&q=hammer#featured
      │      │             │
      │      │             └── url.hash → "#featured"
      │      │                 (empty string on server — browser only)
      │      └── url.searchParams.get('page') → "2"
      │          url.searchParams.get('q')    → "hammer"
      └── params.category → "tools"
          (from route pattern /shop/[category])

url.pathname  → "/shop/tools"
route.id      → "/shop/[category]"   (the pattern, not the value)

Uma coisa a notar imediatamente: url.hash está anotado como vazio no servidor. Fragmentos hash — tudo após o # em uma URL — são removidos pelo navegador antes que a requisição HTTP seja enviada. O servidor simplesmente nunca os recebe. Como as funções load são executadas no servidor durante o SSR, url.hash sempre será uma string vazia nesse contexto. Isso não é uma limitação do SvelteKit; é como o protocolo web funciona. As implicações práticas e a solução correta são abordadas no Passo 4 da seção de implementação.

Antes das etapas de implementação, uma orientação rápida sobre qual entrada usar:

Implementação

Passo 1: Lendo Segmentos de Rota Dinâmicos com params

O uso mais comum de dados de URL em uma função load é a leitura de parâmetros de rota. Qualquer nome de diretório em src/routes cercado por colchetes define um segmento dinâmico, e seu valor atual está disponível em params com o mesmo nome.

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

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// params.slug is typed as string because the route directory
	// is named [slug]. SvelteKit generates this type for you from
	// the route structure; no manual type annotation is needed.
	const response = await fetch(`/api/posts/${params.slug}`)

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

	const post = await response.json()

	return { post }
}

O tipo TypeScript de params é gerado pelo SvelteKit com base nos nomes dos diretórios da rota. Para src/routes/blog/[slug], é { slug: string }. Para src/routes/shop/[category]/[productId], é { category: string; productId: string }. Essa segurança de tipos está disponível imediatamente através da importação ./$types e não requer nenhum trabalho manual da sua parte.

O SvelteKit também suporta parâmetros rest para rotas que precisam capturar múltiplos segmentos de caminho como um único valor. Um diretório chamado [...path] irá corresponder a qualquer número de segmentos após esse ponto na URL e os coletará como uma única string.

// src/routes/docs/[...path]/+page.server.ts

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// For the URL /docs/sveltekit/routing/overview,
	// params.path would be 'sveltekit/routing/overview'.
	// Splitting on '/' gives the individual segments.
	const segments = params.path.split('/')

	// The path is passed as a query string so the API endpoint
	// can handle variable-depth routes without its own routing logic.
	const response = await fetch(`/api/docs?path=${encodeURIComponent(params.path)}`)

	if (!response.ok) {
		error(404, `Documentation page not found: ${params.path}`)
	}

	const page = await response.json()

	return {
		page,
		// Pass the segments back so the component can render breadcrumbs.
		breadcrumbs: segments
	}
}

Parâmetros rest são particularmente úteis para sistemas de documentação, navegadores de arquivos e qualquer rota onde a profundidade da hierarquia de URL é variável em vez de fixa.

Passo 2: Lendo Parâmetros de Consulta com url.searchParams

Enquanto params representa a identidade do recurso sendo solicitado, os parâmetros de consulta representam a configuração opcional de como você deseja visualizá-lo. Filtros, ordens de classificação, números de página e termos de busca são todos candidatos naturais para parâmetros de consulta.

O SvelteKit os expõe através de url.searchParams, que é uma instância padrão de URLSearchParams. O método principal é .get(name), que retorna o valor em string daquele parâmetro ou null se estiver ausente da URL.

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

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

export const load: PageServerLoad = async ({ url, fetch }) => {
	// .get() returns string | null. Use nullish coalescing to supply
	// a safe default when the parameter is not present in the URL.
	const category = url.searchParams.get('category')
	const search = url.searchParams.get('q')
	const page = parseInt(url.searchParams.get('page') ?? '1', 10)
	const pageSize = 24

	// Forward the validated query parameters to the API endpoint.
	// The API is responsible for filtering, pagination, and counting.
	const apiParams = new URLSearchParams()
	if (category) apiParams.set('category', category)
	if (search) apiParams.set('q', search)
	apiParams.set('page', String(page))
	apiParams.set('pageSize', String(pageSize))

	const response = await fetch(`/api/products?${apiParams}`)
	const { products, totalCount } = await response.json()

	return {
		products,
		pagination: {
			page,
			pageSize,
			totalCount,
			totalPages: Math.ceil(totalCount / pageSize)
		},
		// Return the active filter values so the component can reflect
		// them in its UI without re-parsing the URL on the client side.
		activeFilters: { category, search }
	}
}

Há uma nuance importante em como o SvelteKit rastreia o acesso a parâmetros de consulta para seu sistema de reexecução de funções load. Quando sua função load chama url.searchParams.get('category'), o SvelteKit registra uma dependência naquele parâmetro específico. Se o usuário mudar a categoria e navegar para uma nova URL, o SvelteKit sabe que deve reexecutar essa função load porque algo de que ela depende mudou. Se o usuário mudar um parâmetro não relacionado que essa função load nunca lê, o SvelteKit não a reexecutará desnecessariamente.

Essa precisão só é possível quando você usa searchParams.get(), searchParams.getAll() ou searchParams.has() para parâmetros individuais. Se em vez disso você ler url.search como uma string bruta e analisá-la manualmente, o SvelteKit cria uma dependência ampla em toda a string de consulta, o que significa que qualquer alteração de parâmetro de consulta aciona uma reexecução mesmo para aqueles com que essa função não se preocupa. Sempre use searchParams.get() para parâmetros individuais; é tanto mais legível quanto mais eficiente.

Passo 3: Usando route.id para Analytics e Lógica Condicional

O objeto route carrega informações sobre a estrutura da rota em vez dos valores específicos da URL. Sua propriedade route.id é o caminho da rota relativo a src/routes, expresso com os nomes dos segmentos dinâmicos em sua forma original com colchetes.

// src/routes/admin/[section]/[itemId]/+page.server.ts

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

export const load: PageServerLoad = async ({ route, params }) => {
	// For the URL /admin/users/42:
	// route.id is '/admin/[section]/[itemId]'
	// params.section is 'users'
	// params.itemId is '42'
	console.log(route.id) // '/admin/[section]/[itemId]'
	console.log(params.section) // 'users'
	console.log(params.itemId) // '42'

	return {}
}

O valor prático de route.id está em utilitários compartilhados que precisam identificar qual rota está ativa sem se preocupar com os valores específicos nessa rota. Analytics e logs são os exemplos mais claros. Quando você rastreia visualizações de página, normalmente quer dois dados: a rota estrutural (que indica o tipo de página visitada, como um post de blog ou uma página de produto) e o recurso específico (que indica exatamente qual post ou produto). Agregar por route.id permite responder "quantas vezes a visão de post de blog foi acessada no total", porque todo post de blog compartilha o mesmo route.id de /blog/[slug], mesmo que cada um tenha um params.slug diferente.

// src/lib/server/analytics.ts

// A thin wrapper that posts view events to an internal analytics endpoint.
// Keeping this in $lib/server/ ensures it is never bundled for the browser.
export async function trackView(
	fetch: typeof globalThis.fetch,
	routeId: string | null,
	params: Record<string, string>
): Promise<void> {
	// routeId identifies the type of page: '/blog/[slug]', '/products/[id]', etc.
	// params records which specific resource was viewed.
	await fetch('/api/analytics/views', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({
			route: routeId ?? 'unknown',
			params,
			visitedAt: new Date().toISOString()
		})
	})
}

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

import type { PageServerLoad } from './$types'
import { trackView } from '$lib/server/analytics'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ route, params, fetch }) => {
	// Run analytics tracking and the post query concurrently.
	// Neither depends on the result of the other, so there is no
	// reason to wait for one before starting the other.
	const [postResponse] = await Promise.all([
		fetch(`/api/posts/${params.slug}`),
		trackView(fetch, route.id, params)
	])

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

	const post = await postResponse.json()

	return { post }
}

Executar o rastreamento de analytics em paralelo com a busca principal de dados mantém o tempo de carregamento da página sem ser afetado pela escrita de analytics. A consulta do post e a inserção de analytics começam ao mesmo tempo, e a função load aguarda a conclusão de ambas antes de retornar.

Passo 4: Por que url.hash Não Está Disponível no Servidor

Antes de construir o exemplo completo, vale a pena entender explicitamente a restrição do hash em vez de descobri-la através de um bug desconcertante.

Quando um navegador faz uma requisição HTTP, a parte hash da URL — tudo após o caractere # — é intencionalmente removida antes que a requisição seja enviada. Este é um comportamento especificado que remonta ao design original do HTTP. O servidor nunca recebe o hash; ele só existe no navegador. O propósito original dos hashes era apontar para elementos âncora dentro de um documento já carregado, então não havia necessidade de enviá-los ao servidor.

Como as funções load do SvelteKit são executadas no servidor durante o SSR, url.hash sempre será uma string vazia nesse contexto. Ela é populada corretamente quando a função load é executada no navegador durante a navegação do lado do cliente, mas você não pode depender dela durante a primeira renderização.

// AVOID: This will silently return '' during SSR.
// The tab will appear correct after client-side hydration but not
// during the initial server render, causing a hydration mismatch.

export const load: PageLoad = async ({ url }) => {
	const activeTab = url.hash.replace('#', '') || 'overview'
	return { activeTab }
}

A abordagem correta é converter o estado baseado em hash para um parâmetro de consulta (que o servidor pode ver) ou lidar com o hash no componente após a montagem usando $app/state.

<!-- PREFERRED: Read hash state in the component using $app/state.
     page.url.hash is reactive and updates on client-side navigation.
     It will be empty during SSR, so provide a sensible default. -->

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

	let { data }: PageProps = $props()

	// $derived keeps activeTab in sync with navigation changes.
	// On the server and on first render it defaults to 'overview'.
	let activeTab = $derived(page.url.hash.replace('#', '') || 'overview')
</script>

<div class="tabs">
	<a href="#overview" class:active={activeTab === 'overview'}>Overview</a>
	<a href="#reviews" class:active={activeTab === 'reviews'}>Reviews</a>
	<a href="#specs" class:active={activeTab === 'specs'}>Specs</a>
</div>

Se a seleção de aba controla quais dados são carregados do servidor em vez de apenas qual seção do conteúdo já carregado é exibida, use um parâmetro de consulta (?tab=reviews) em vez de um hash, para que o servidor possa lê-lo durante o SSR.

Passo 5: Uma Listagem de Produtos Filtrável Completa

Com as três entradas compreendidas, aqui está um exemplo completo que as une. A rota é /products, e ela suporta filtragem por categoria e navegação por resultados paginados. Todo o estado vive na URL para que cada visão seja compartilhável e cada navegação seja rastreada pelo sistema de dependências do SvelteKit.

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

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

// Validation helpers keep the load function readable and
// protect against arbitrary user input reaching the API.
const VALID_SORT_FIELDS = ['name', 'price', 'rating'] as const
type SortField = (typeof VALID_SORT_FIELDS)[number]

function parseSortField(value: string | null): SortField {
	if (value && (VALID_SORT_FIELDS as readonly string[]).includes(value)) {
		return value as SortField
	}
	return 'name'
}

function parsePage(value: string | null): number {
	const parsed = parseInt(value ?? '1', 10)
	// Guard against NaN, zero, and negative page numbers
	// that could arise from malformed or manipulated URLs.
	return Number.isFinite(parsed) && parsed > 0 ? parsed : 1
}

const PAGE_SIZE = 24

export const load: PageServerLoad = async ({ url, fetch }) => {
	// Read and validate all relevant parameters using get() for precise
	// dependency tracking on each individual parameter.
	const category = url.searchParams.get('category')
	const search = url.searchParams.get('q')
	const sortBy = parseSortField(url.searchParams.get('sort'))
	const page = parsePage(url.searchParams.get('page'))

	// Build the outgoing API params from the validated values only.
	// This means the API never receives raw, unvalidated user input.
	const apiParams = new URLSearchParams()
	if (category) apiParams.set('category', category)
	if (search && search.trim().length >= 2) apiParams.set('q', search.trim())
	apiParams.set('sort', sortBy)
	apiParams.set('page', String(page))
	apiParams.set('pageSize', String(PAGE_SIZE))

	// Fetch the product list and the category list for the filter UI
	// in parallel — neither depends on the other.
	const [productsRes, categoriesRes] = await Promise.all([
		fetch(`/api/products?${apiParams}`),
		fetch('/api/categories')
	])

	const { products, totalCount } = await productsRes.json()
	const categories = await categoriesRes.json()

	return {
		products,
		categories,
		pagination: {
			page,
			pageSize: PAGE_SIZE,
			totalCount,
			totalPages: Math.ceil(totalCount / PAGE_SIZE)
		},
		// Returning the parsed and validated filter values means the
		// component does not need to re-read or re-parse the URL itself.
		activeFilters: { category, search, sortBy }
	}
}

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

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

	let { data }: PageProps = $props()

	// Build a URL for a target page number while preserving the
	// current filter state. Because the function closes over
	// the reactive data prop, it always reflects the latest values.
	function buildPageUrl(targetPage: number): string {
		const params = new URLSearchParams()

		if (data.activeFilters.category) {
			params.set('category', data.activeFilters.category)
		}
		if (data.activeFilters.search) {
			params.set('q', data.activeFilters.search)
		}

		params.set('sort', data.activeFilters.sortBy)
		params.set('page', String(targetPage))

		return `/products?${params.toString()}`
	}
</script>

<div class="products-page">
	<!--
		Using method="GET" means the browser navigates to a new URL
		when the form is submitted, updating the query string.
		SvelteKit intercepts this navigation, sees that the URL changed,
		and reruns the load function with the new searchParams values.
		No custom JavaScript is needed for the filter mechanism itself.
	-->
	<form method="GET" class="filters">
		<select name="category">
			<option value="">All Categories</option>
			{#each data.categories as cat (cat.slug)}
				<option value={cat.slug} selected={cat.slug === data.activeFilters.category}>
					{cat.name}
				</option>
			{/each}
		</select>

		<input
			type="search"
			name="q"
			placeholder="Search products..."
			value={data.activeFilters.search ?? ''}
		/>

		<select name="sort">
			<option value="name" selected={data.activeFilters.sortBy === 'name'}> Name </option>
			<option value="price" selected={data.activeFilters.sortBy === 'price'}> Price </option>
			<option value="rating" selected={data.activeFilters.sortBy === 'rating'}> Rating </option>
		</select>

		<button type="submit">Apply Filters</button>
	</form>

	<div class="product-grid">
		{#each data.products as product (product.id)}
			<a href="/products/{product.slug}" class="product-card">
				<img src={product.thumbnailUrl} alt={product.name} />
				<h2>{product.name}</h2>
				<p class="price">${product.price}</p>
				<p class="rating">{product.rating} stars</p>
			</a>
		{/each}

		{#if data.products.length === 0}
			<p class="empty-state">
				No products match your current filters. Try adjusting your search or category.
			</p>
		{/if}
	</div>

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

			<span>
				Page {data.pagination.page} of {data.pagination.totalPages}
				({data.pagination.totalCount} products)
			</span>

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

O formulário de filtro usa method="GET" para que ao submetê-lo seja realizada uma navegação padrão do navegador para a mesma rota com parâmetros de consulta atualizados. O SvelteKit intercepta essa navegação, detecta que url.searchParams mudou e reexecuta a função load. A página é atualizada com novos dados sem um recarregamento completo da página e sem nenhum manipulador de eventos JavaScript personalizado gerenciando o estado do filtro.

Os links de paginação funcionam da mesma forma: cada um é uma âncora simples apontando para uma URL que codifica os filtros atuais mais o novo número de página, então cada página de resultados é sua própria URL distinta e navegável.

Erros Comuns e Anti-Padrões

Passar Valores Brutos de URL Diretamente para o Banco de Dados

Todo parâmetro de consulta na URL pode ser definido para qualquer string arbitrária por qualquer usuário. Passar esses valores sem validação diretamente para uma consulta ao banco de dados permite que entradas inesperadas cheguem à sua camada de dados.

// AVOID: sortBy could be anything the user puts in the URL.
// Forwarding it directly to the API without validation is unsafe —
// the server receiving it may trust the value implicitly.

export const load: PageServerLoad = async ({ url, fetch }) => {
	const sortBy = url.searchParams.get('sort')
	const res = await fetch(`/api/products?sort=${sortBy}`)
	return { products: await res.json() }
}

// PREFERRED: Validate against an explicit allowlist first.
// The API only ever receives one of three known-safe sort values.

const VALID_SORT_FIELDS = ['name', 'price', 'rating'] as const
type SortField = (typeof VALID_SORT_FIELDS)[number]

function parseSortField(value: string | null): SortField {
	if (value && (VALID_SORT_FIELDS as readonly string[]).includes(value)) {
		return value as SortField
	}
	return 'name'
}

export const load: PageServerLoad = async ({ url, fetch }) => {
	const sortBy = parseSortField(url.searchParams.get('sort'))
	const res = await fetch(`/api/products?sort=${sortBy}`)
	return { products: await res.json() }
}

Pequenas funções utilitárias de validação como parseSortField e parsePage também tornam as funções load mais fáceis de testar unitariamente, uma vez que a lógica de análise é isolada e pode ser exercitada independentemente do restante da função load.

Lendo url.search em Vez de url.searchParams.get()

Ler url.search como uma string bruta cria uma dependência em toda a query string; usar url.searchParams.get('key') cria uma dependência apenas naquela chave específica. Em aplicações onde múltiplas funções de carregamento ou componentes atualizam diferentes parâmetros de query, dependências imprecisas fazem com que as funções de carregamento sejam reexecutadas com mais frequência do que o necessário.

// AVOID: Any query parameter change triggers a rerun of this
// load function, even parameters it never uses.

export const load: PageLoad = async ({ url }) => {
	const allParams = new URLSearchParams(url.search) // broad dependency
	const category = allParams.get('category')
	return { category }
}

// PREFERRED: Only a change to 'category' triggers a rerun.
// Changes to 'sort', 'page', or anything else are ignored.

export const load: PageLoad = async ({ url }) => {
	const category = url.searchParams.get('category') // precise dependency
	return { category }
}

Esperar que url.hash Funcione em uma Função de Carregamento

Esse erro se manifesta como uma inconsistência sutil de SSR. A função de carregamento retorna um valor padrão para o estado dependente de hash no servidor porque url.hash é sempre vazio lá; após a hidratação, o cliente reexecuta a função de carregamento e obtém um valor diferente porque url.hash agora está preenchido. O resultado é um flash de conteúdo incorreto e um aviso de hidratação no console do navegador.

A solução é mover a lógica dependente de hash para fora da função de carregamento completamente e tratá-la no componente usando o objeto reativo page do $app/state, ou converter o estado baseado em hash para um parâmetro de query que o servidor possa ler.

Considerações de Performance e Escalabilidade

O rastreamento de dependências refinado do SvelteKit para url.searchParams é um de seus recursos de performance mais discretos, mas mais úteis. Como cada chamada a searchParams.get() registra uma dependência apenas naquela chave específica, o SvelteKit tem informações precisas sobre o que cada função de carregamento necessita. Durante a navegação no lado do cliente, ele pode comparar apenas as partes relevantes da URL para decidir se uma função de carregamento precisa ser reexecutada, em vez de comparar strings de URL inteiras.

Isso significa que em uma página com várias funções de carregamento independentes, cada uma será reexecutada apenas quando os parâmetros específicos que ela lê realmente mudarem. Uma função de carregamento de paginação que lê apenas page não será reexecutada quando o usuário alterar o termo de busca; uma função de carregamento de filtro de categoria que lê apenas category não será reexecutada quando o usuário alterar a ordem de classificação. Para páginas complexas com múltiplas dependências de dados, essa precisão mantém a navegação rápida e evita requisições redundantes ao servidor.

O padrão Promise.all mostrado no exemplo completo merece destaque como uma consideração de performance separada. Buscar produtos, contagem total e lista de categorias em uma única chamada Promise.all envia as três consultas ao banco de dados simultaneamente, em vez de sequencialmente. O tempo de espera total é determinado pela mais lenta das três consultas, e não pela soma de todas elas. Esse padrão deve ser o padrão adotado sempre que múltiplas requisições de dados independentes forem necessárias em uma única função de carregamento.

Quando NÃO Usar Este Padrão

O estado orientado por URL é a ferramenta certa para dados que definem uma visualização significativa e compartilhável: qual página, qual categoria, qual termo de busca. Não é a ferramenta certa para estado de UI efêmero que só importa para a sessão atual e não tem significado para mais ninguém. Se um dropdown está aberto, se um painel de acordeão está expandido ou qual texto um usuário digitou mas ainda não enviou são exemplos de estado que pertence ao componente como variáveis reativas, não à URL.

O teste prático é verificar se uma URL contendo esse estado seria útil para outra pessoa. Uma URL codificando a página 3 de uma busca de produtos filtrados é genuinamente útil para outro usuário. Uma URL codificando qual seção do acordeão um usuário abriu é apenas ruído.

Para entradas de busca especificamente, disparar uma navegação completa pela URL e a reexecução da função de carregamento a cada tecla pressionada produziria uma experiência incômoda. A solução convencional é usar um formulário method="GET" com um botão de envio, como no exemplo acima, para que a navegação ocorra apenas quando o usuário aplicar explicitamente sua busca. Alternativamente, aplique debounce na entrada para que a navegação só seja disparada após uma breve pausa na digitação.

Conclusão

Os inputs params, url e route fornecem às funções de carregamento tudo o que é necessário para responder de forma inteligente à URL atual. Os parâmetros de rota em params identificam o recurso específico sendo solicitado, tipados com precisão a partir da estrutura de diretórios da rota. Os parâmetros de query por meio de url.searchParams carregam configurações de visualização opcionais como filtros e números de página, com rastreamento preciso de dependências por parâmetro. A propriedade route.id em route expõe o padrão de rota estrutural para análises e lógica condicional que precisa raciocinar sobre qual tipo de página está ativa, em vez de qual recurso específico.

A disciplina mais importante é tratar todos os valores de URL como entrada de usuário não confiável e validá-los antes que cheguem ao banco de dados. Além disso, usar searchParams.get() em vez de ler url.search como uma string bruta é um pequeno hábito que mantém o rastreamento de dependências do SvelteKit preciso e a navegação eficiente.

Principais Conclusões

params contém os valores resolvidos dos segmentos de rota dinâmicos, tipados com precisão a partir da estrutura de diretórios da rota; é o lugar certo para ler a identidade do recurso. url.searchParams.get() lê parâmetros de query individuais e registra dependências precisas por chave; ler url.search como uma string bruta cria uma dependência mais ampla e deve ser evitado. url.hash é sempre uma string vazia durante o SSR porque os navegadores removem os fragmentos de hash antes de enviar requisições HTTP; a lógica dependente de hash pertence ao componente, não à função de carregamento. route.id expõe o padrão de rota em notação de colchetes, independente dos valores específicos da URL, sendo útil para análises e logging. Todos os valores provenientes da URL são entradas de usuário não confiáveis e devem ser validados antes de chegarem a consultas ao banco de dados ou à lógica de negócios.

O Que Vem a Seguir

Agora que você tem uma compreensão sólida do que as funções de carregamento recebem como entrada, é hora de examinar com atenção como elas fazem requisições de saída. O fetch fornecido pelo evento de carregamento não é o mesmo que o fetch global do navegador; ele possui melhorias significativas que resolvem problemas reais em aplicações com renderização no servidor, desde o encaminhamento de credenciais até a consistência de hidratação. O próximo artigo, Fetch em Funções de Carregamento, aborda exatamente quais são essas melhorias e como utilizá-las corretamente.

Leitura Adicional

Roteamento Avançado do SvelteKit — parâmetros rest, parâmetros opcionais e prioridade de correspondência
URLSearchParams no MDN — a referência completa da API para o objeto searchParams
Documentação Oficial de Load do SvelteKit — a referência autoritativa para todos os inputs de funções de carregamento