Dois Arquivos, Dois Ambientes

Os dois artigos anteriores usaram +page.ts e +layout.ts para todas as funções de carregamento, o que é o ponto de partida correto para entender como o sistema funciona. Mas o SvelteKit na verdade fornece dois tipos distintos de funções de carregamento, e o arquivo em que você as coloca determina algo fundamental sobre como e onde elas são executadas.

O primeiro tipo, o que você viu até agora, é a função de carregamento universal. Ela vive em +page.ts ou +layout.ts. O segundo tipo é a função de carregamento de servidor. Ela vive em +page.server.ts ou +layout.server.ts. Os nomes sugerem a diferença, mas as implicações vão além de simplesmente "uma roda no servidor". Ambos os tipos podem rodar no servidor. O que os separa é o que cada um pode acessar, o que podem retornar e onde são executados durante a navegação do lado do cliente após o carregamento inicial da página.

Entender corretamente essa distinção é uma das decisões arquiteturais mais importantes em uma aplicação SvelteKit. Coloque lógica privada de banco de dados em uma função de carregamento universal e você pode acidentalmente expô-la ao bundle do navegador. Coloque uma função que precisa retornar um construtor de componente Svelte em uma função de carregamento de servidor e você descobrirá que ela não pode ser serializada para ser enviada pela rede. Entender por que cada tipo existe, não apenas qual arquivo usar, é o que permite fazer a escolha certa com confiança sempre.

Por Que Existem Dois Tipos de Arquivo

Para entender por que existem dois tipos, você primeiro precisa entender o que o SvelteKit faz quando um usuário acessa uma página.

Quando um usuário navega diretamente para uma URL (digitando-a na barra de endereços ou seguindo um link de outro site), o SvelteKit renderiza a página no servidor e envia HTML completamente formado ao navegador. A função de carregamento roda no servidor, o componente é renderizado como uma string, e o navegador recebe um documento completo. Isso é renderização do lado do servidor (SSR).

Quando o mesmo usuário clica em um link dentro da aplicação (navegando de uma página para outra sem um recarregamento completo da página), o SvelteKit lida com essa navegação inteiramente no navegador. Ele chama a função de carregamento novamente, mas desta vez no navegador, busca apenas os novos dados e atualiza a página sem uma ida e volta ao servidor para obter HTML. Isso é navegação do lado do cliente.

Uma função de carregamento universal participa de ambos os cenários. Ela roda no servidor na primeira visita e no navegador para as navegações subsequentes. Essa execução em dois ambientes é o que "universal" significa; a mesma função roda em ambos os contextos.

Uma função de carregamento de servidor, por outro lado, sempre roda no servidor. Ela roda no servidor na primeira visita e também roda no servidor durante a navegação do lado do cliente; o SvelteKit faz uma requisição de rede a um endpoint interno especial para chamá-la, serializa o resultado e o envia pela rede ao navegador. O navegador recebe os dados, mas nunca executa a função em si.

Essa distinção tem consequências profundas. O código de uma função de carregamento universal é empacotado para o navegador, o que significa que nunca deve conter nada que não possa existir com segurança no navegador: sem conexões diretas com banco de dados, sem variáveis de ambiente secretas, sem APIs exclusivas do Node.js. O código de uma função de carregamento de servidor nunca chega ao navegador, portanto pode fazer todas essas coisas com segurança.

O Modelo de Fronteira de Confiança

Pense nos dois tipos de funções de carregamento como ocupando fronteiras de confiança diferentes.

Funções de Carregamento Universais

A fronteira de confiança em uma função de carregamento universal está na fronteira de confiança pública. Ela é visível para qualquer pessoa que possa acessar o bundle JavaScript da página, o que é essencialmente qualquer pessoa que possa carregar a página. Isso significa que qualquer código em uma função de carregamento universal deve ser seguro para rodar no navegador e não deve conter segredos ou acessos privilegiados. É adequada para lógica que não tem segredos, sem acesso privilegiado e sem dependências exclusivas do servidor, como buscar dados de uma API pública, transformar dados já públicos e ler variáveis de ambiente explicitamente marcadas como públicas.

Uma função de carregamento universal roda em ambos os ambientes. Durante o SSR, ela roda no servidor e seu valor de retorno é embutido no HTML enviado ao navegador. Durante a navegação do lado do cliente, ela roda no navegador e pode buscar dados diretamente de APIs públicas sem envolver o servidor. Por rodar no navegador, ela pode retornar valores não serializáveis como construtores de componentes Svelte, instâncias de classes ou Maps e Sets que você deseja usar diretamente no componente. A função de carregamento de servidor não pode fazer isso porque seu valor de retorno precisa ser serializado para ser enviado pela rede.

Funções de Carregamento de Servidor

A fronteira de confiança em uma função de carregamento de servidor está na fronteira de confiança privada. Ela nunca é enviada ao navegador e só pode ser lida por desenvolvedores com acesso ao código do servidor. Isso significa que qualquer código em uma função de carregamento de servidor pode conter com segurança segredos e acessos privilegiados, como consultas a banco de dados, variáveis de ambiente privadas e APIs internas que exigem autenticação. É adequada para qualquer coisa que deva permanecer confidencial ou que tenha requisitos exclusivos do servidor, como consultar um banco de dados, ler variáveis $env/static/private, inspecionar cookies HTTP ou chamar um serviço interno com uma chave de API privada.

É adequada para qualquer coisa que deva permanecer confidencial ou que tenha requisitos exclusivos do servidor, como consultar um banco de dados, ler variáveis $env/static/private, inspecionar cookies HTTP ou chamar um serviço interno com uma chave de API privada.

A fronteira é imposta estruturalmente pelo sistema de módulos do SvelteKit. Qualquer importação dentro de +page.server.ts que venha de $lib/server/ ou use $env/static/private é automaticamente bloqueada se tentar rodar em um contexto de navegador. Você não precisa garantir manualmente essa separação, porque a convenção de nomenclatura dos arquivos é o mecanismo de imposição.

O Padrão Combinado

Há um terceiro cenário que a documentação oficial aborda, mas que é fácil de ignorar: você pode usar ambos os arquivos para a mesma rota simultaneamente. Quando +page.server.ts e +page.ts existem ao mesmo tempo, o SvelteKit executa primeiro o carregamento de servidor e passa seu valor de retorno como a propriedade data do argumento de evento do carregamento universal. O carregamento universal pode então combinar os dados do servidor com processamento adicional do lado do cliente antes de passar o resultado final ao componente. Isso é território avançado abordado mais adiante neste artigo, mas vale saber que essa capacidade existe.

Implementação

Passo 1: A Função de Carregamento Universal

Uma função de carregamento universal em +page.ts roda em ambos os ambientes. Seu caso de uso mais adequado é buscar dados de uma API externa onde nenhuma credencial é necessária e onde o navegador poderia teoricamente fazer a mesma requisição por conta própria.

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

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

export const load: PageLoad = async ({ params, fetch }) => {
	// This is a public API; no secret credentials required.
	// The browser could call this URL directly. We are just doing it
	// earlier, in the load function, so the page renders with data ready.
	const response = await fetch(`https://api.storefront.example.com/products/${params.id}`)

	if (!response.ok) {
		error(response.status, `Product not found: ${params.id}`)
	}

	const product = await response.json()

	return { product }
}

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

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

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

<h1>{data.product.name}</h1>
<p class="price">${data.product.price}</p>
<p>{data.product.description}</p>

Não há nada secreto aqui. A URL da API, o ID do produto e a resposta seriam todos visíveis para qualquer pessoa que abrisse o painel de rede do navegador. Usar uma função de carregamento universal para esse caso é correto e eficiente: durante o SSR, o SvelteKit chama a API no servidor e incorpora a resposta no HTML; durante a navegação do lado do cliente, o navegador chama a mesma URL e atualiza a página diretamente. Nenhuma passagem intermediária pelo servidor é necessária.

A função de carregamento universal também tem acesso a capacidades que as funções de carregamento de servidor não têm. O mais notável é que ela pode retornar valores não serializáveis, como construtores de componentes Svelte, instâncias de classes ou Maps e Sets que você deseja usar diretamente no componente. Como o carregamento universal roda no mesmo ambiente JavaScript que o componente, ele pode passar valores ricos sem serialização.

Passo 2: A Função de Carregamento de Servidor

Uma função de carregamento de servidor em +page.server.ts sempre roda no servidor. É a escolha certa sempre que a função de carregamento precisa de acesso privilegiado ou deve trabalhar com recursos exclusivos do servidor.

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

import type { PageServerLoad } from './$types'
import { METRICS_API_URL, METRICS_API_KEY } from '$env/static/private'
import { error, redirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, fetch }) => {
	// locals.user is populated by the authentication hook in src/hooks.server.ts.
	// Only server load functions can read locals — universal load functions cannot.
	if (!locals.user) {
		redirect(307, '/login')
	}

	// Calling a private internal service using a secret environment variable.
	// METRICS_API_KEY never reaches the browser — it is server-only.
	const metricsRes = await fetch(`${METRICS_API_URL}/users/${locals.user.id}`, {
		headers: { Authorization: `Bearer ${METRICS_API_KEY}` }
	})

	if (!metricsRes.ok) {
		error(502, 'Metrics service unavailable')
	}

	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			email: locals.user.email,
			plan: locals.user.plan
		},
		metrics: await metricsRes.json()
	}
}

Várias capacidades usadas aqui são exclusivas das funções de carregamento de servidor. locals está disponível apenas em +page.server.ts e +layout.server.ts; funções de carregamento universais não podem lê-lo. $env/static/private só pode ser importado em contextos exclusivos do servidor — o bundler impõe isso em tempo de build. Nenhum desse código toca o navegador.

locals é um objeto tipado populado pelos hooks de servidor do SvelteKit em src/hooks.server.ts. O hook roda em cada requisição antes de qualquer função de carregamento, autentica a sessão e anexa o usuário resolvido a locals. As funções de carregamento de servidor então leem locals.user diretamente — sem necessidade de uma requisição secundária. Esse é o padrão padrão do SvelteKit para autenticação: os hooks lidam com a resolução de identidade e as funções de carregamento de servidor consomem o resultado.

O valor de retorno de uma função de carregamento de servidor deve ser serializável usando a biblioteca devalue, que é um superconjunto de JSON que também lida com Date, Map, Set, BigInt, RegExp e referências circulares. Instâncias de classe com métodos, construtores de componentes Svelte e funções arbitrárias não podem ser serializadas e, portanto, não podem ser retornadas de uma função de carregamento de servidor. Se você precisar retornar algo não serializável, isso é um sinal de que uma função de carregamento universal, possivelmente combinada com uma função de carregamento de servidor, é a arquitetura correta.

Passo 3: Reconhecendo o Que Você Não Pode Fazer em Cada Contexto

A maneira prática de internalizar a distinção é entender o que vai falhar em cada contexto. Funções de carregamento universais falharão se tentarem importar módulos exclusivos do servidor. Funções de carregamento de servidor falharão se tentarem retornar valores não serializáveis. Essas falhas se manifestam como erros TypeScript ou erros de tempo de execução que o SvelteKit torna explícitos, o que os torna mais fáceis de detectar do que erros lógicos silenciosos.

Aqui está uma tabela das principais capacidades e qual tipo de carregamento as suporta:

Capacidade	Universal (`+page.ts`)	Servidor (`+page.server.ts`)
Roda no servidor (SSR)	Sim	Sim
Roda no navegador (navegação)	Sim	Não (dados buscados via API interna)
Acesso a `cookies`	Não	Sim
Acesso a `locals`	Não	Sim
Acesso a `$env/static/private`	Não	Sim
Módulos `$lib/server/`	Não	Sim
Retornar valores não serializáveis	Sim	Não
Código aparece no bundle do navegador	Sim	Não

Se uma função de carregamento não precisa de nada na coluna direita, um carregamento universal em +page.ts é suficiente. Se precisar de qualquer coisa na coluna direita, deve ir em +page.server.ts.

Passo 4: Combinando Ambos na Mesma Rota

Há situações em que nenhum dos tipos isoladamente é suficiente. O caso mais comum é uma rota que precisa de dados exclusivos do servidor (por exemplo, um objeto de usuário do banco de dados) e também precisa retornar algo não serializável (por exemplo, um componente Svelte selecionado dinamicamente com base no papel do usuário).

O SvelteKit suporta isso permitindo que +page.server.ts e +page.ts coexistam para a mesma rota. Quando ambos existem, o SvelteKit executa primeiro o carregamento de servidor, depois passa seu valor de retorno como data no argumento de evento do carregamento universal. O carregamento universal combina os dados do servidor com qualquer processamento do lado do cliente que precisar e retorna o resultado final ao componente.

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

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

export const load: PageServerLoad = async ({ locals }) => {
	// locals.user is set by the auth hook — only readable in server load functions.
	if (!locals.user) redirect(307, '/login')

	return {
		userId: locals.user.id,
		role: locals.user.role as 'admin' | 'editor' | 'viewer',
		displayName: locals.user.displayName
	}
}

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

import type { PageLoad } from './$types'
// These are Svelte component constructors; non-serialisable.
// They can only be passed through a universal load function.
import AdminDashboard from '$lib/components/AdminDashboard.svelte'
import EditorDashboard from '$lib/components/EditorDashboard.svelte'
import ViewerDashboard from '$lib/components/ViewerDashboard.svelte'

const DASHBOARD_COMPONENTS = {
	admin: AdminDashboard,
	editor: EditorDashboard,
	viewer: ViewerDashboard
}

export const load: PageLoad = async ({ data }) => {
	// `data` here is the return value of +page.server.ts.
	// The universal load receives it and can extend or transform it.
	const DashboardComponent = DASHBOARD_COMPONENTS[data.role]

	return {
		// Spread the server data through so the component receives it all.
		...data,
		// Add the component constructor (something the server load cannot return).
		DashboardComponent
	}
}

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

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

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

<h1>Welcome, {data.displayName}</h1>

<!-- Dynamically render whichever dashboard component the user's role requires. -->
{@const DashboardComponent = data.DashboardComponent}
<DashboardComponent userId={data.userId} />

Esse padrão mantém a fronteira de privilégio limpa: o carregamento de servidor lida com tudo que precisa de acesso exclusivo ao servidor, o carregamento universal lida com tudo que precisa de valores não serializáveis, e o componente recebe um resultado mesclado e limpo de ambos. O valor de retorno do carregamento de servidor é a propriedade data do evento do carregamento universal; ele flui pelo carregamento universal, mas não é automaticamente passado ao componente. O carregamento universal é responsável por incluir em seu próprio valor de retorno quaisquer dados do servidor que o componente precise, tipicamente usando spread com ...data.

Erros Comuns e Anti-Padrões

Usar Importações Exclusivas do Servidor em uma Função de Carregamento Universal

Este é o erro mais perigoso nessa área. Ele nem sempre falha imediatamente — pode funcionar em desenvolvimento e depois expor credenciais privadas no bundle do navegador em produção, ou travar quando código exclusivo do Node.js roda em um contexto de navegador.

// src/routes/profile/+page.ts

// AVOID: Importing a private environment variable in a universal load function.
// This file is bundled for the browser. PRIVATE_API_KEY would be visible
// to anyone who inspects the JavaScript bundle.
import { PRIVATE_API_KEY } from '$env/static/private'
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/users/${params.id}`, {
		headers: { Authorization: `Bearer ${PRIVATE_API_KEY}` } // key exposed!
	})
	return { user: await res.json() }
}

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

// PREFERRED: Private credentials belong in a server load function.
// This file never reaches the browser bundle.
import type { PageServerLoad } from './$types'
import { PRIVATE_API_KEY } from '$env/static/private'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/users/${params.id}`, {
		headers: { Authorization: `Bearer ${PRIVATE_API_KEY}` } // safe, server-only
	})
	if (!res.ok) error(404, 'User not found')
	return { user: await res.json() }
}

O SvelteKit lança um erro em tempo de build se você importar $env/static/private ou qualquer coisa de $lib/server/ em uma função de carregamento universal — o bundler reconhece esses como módulos exclusivos do servidor e se recusa a incluí-los no bundle do cliente. A proteção depende da convenção de caminho: qualquer arquivo sob $lib/server/ é tratado como exclusivo do servidor automaticamente. Mantenha toda a lógica privilegiada lá para que as ferramentas possam impor a fronteira em seu nome.

Tentar Retornar uma Instância de Classe de uma Função de Carregamento de Servidor

Quando uma função de carregamento de servidor retorna dados, o SvelteKit os serializa usando devalue antes de enviá-los pela rede ao navegador. Instâncias de classe com métodos, cadeias de protótipos e propriedades não enumeráveis não sobrevivem à serialização. O que chega ao navegador é um objeto simples com as mesmas chaves enumeráveis; os métodos e o protótipo desaparecem.

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

class ShoppingCart {
	items: CartItem[]
	constructor(items: CartItem[]) {
		this.items = items
	}
	get total() {
		return this.items.reduce((sum, item) => sum + item.price, 0)
	}
	addItem(item: CartItem) {
		/* ... */
	}
}

// AVOID: The ShoppingCart class instance cannot be serialised.
// The browser will receive { items: [...] } with no methods.
export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) redirect(307, '/login')
	const res = await fetch(`/api/cart/${locals.user.id}`)
	const items: CartItem[] = await res.json()
	return { cart: new ShoppingCart(items) }
}

// PREFERRED option A: Return plain data from the server load.
// Reconstruct the class in the universal load if needed.

// +page.server.ts
export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) redirect(307, '/login')
	const res = await fetch(`/api/cart/${locals.user.id}`)
	const cartItems: CartItem[] = await res.json()
	return { cartItems } // plain serialisable data
}

// +page.ts
export const load: PageLoad = async ({ data }) => {
	// Reconstruct the class in the universal load where it can survive.
	const cart = new ShoppingCart(data.cartItems)
	return { cart }
}

O padrão de arquivos divididos existe precisamente para esse cenário. O carregamento de servidor lida com a recuperação de dados privilegiados. O carregamento universal reconstrói objetos ricos que se beneficiam do comportamento de classe. Cada um faz o que é adequado para ele.

Confundir Qual `data` É Qual ao Usar Ambos os Arquivos

Quando +page.server.ts e +page.ts existem para a mesma rota, há duas coisas diferentes chamadas data em proximidade: a propriedade data no argumento de evento do carregamento universal (que contém o valor de retorno do carregamento de servidor) e a prop data no componente (que contém o valor de retorno do carregamento universal). Elas são distintas e podem diferir se o carregamento universal não propagar os dados do servidor.

// +page.server.ts
export const load: PageServerLoad = async () => {
	return { serverMessage: 'hello from server' }
}

// +page.ts (AVOID): Forgetting to include server data in the return value
export const load: PageLoad = async ({ data }) => {
	// data.serverMessage is available here, but we are not returning it.
	return { universalMessage: 'hello from universal' }
	// The component will only see universalMessage.
	// serverMessage is lost because the universal load did not pass it through.
}

// +page.ts (PREFERRED): Spread server data into the universal return value
export const load: PageLoad = async ({ data }) => {
	return {
		...data, // includes serverMessage
		universalMessage: 'hello from universal'
	}
	// The component now sees both serverMessage and universalMessage.
}

Este é um erro puramente mecânico, mas produz sintomas confusos; os tipos TypeScript para data no componente incluem serverMessage (porque o SvelteKit pode ver ambos os tipos de retorno), mas o valor é undefined em tempo de execução porque o carregamento universal nunca o repassou. Sempre use spread com ...data quando quiser que os dados do carregamento de servidor cheguem ao componente.

Considerações de Desempenho e Escalabilidade

A escolha entre funções de carregamento universal e de servidor tem implicações de desempenho significativas que vão além da correção.

Funções de carregamento universais permitem que o SvelteKit potencialmente ignore o servidor completamente durante a navegação do lado do cliente. Se seu carregamento universal busca dados de uma API pública com cache em CDN, o navegador pode atingir esse cache diretamente a cada navegação sem tocar no seu servidor. Funções de carregamento de servidor, por outro lado, sempre envolvem uma ida e volta ao seu servidor durante a navegação do lado do cliente; o SvelteKit faz um fetch a um endpoint interno, seu servidor executa a função de carregamento e o resultado viaja de volta pela rede. Para aplicações de alto tráfego, carregamentos universais que usam APIs públicas bem armazenadas em cache podem reduzir significativamente a carga no servidor.

Funções de carregamento de servidor, no entanto, têm sua própria vantagem de desempenho: elas rodam mais perto de seus dados. Uma função de carregamento de servidor que consulta um banco de dados local tem latência de rede medida em milissegundos. Uma função de carregamento universal chamando uma API externa a partir do navegador pode ter latência medida em centenas de milissegundos, além da sobrecarga de CORS e da transmissão de tokens de autenticação. Para dados que genuinamente requerem acesso do lado do servidor, a proximidade do carregamento de servidor com a fonte de dados é uma vantagem, não apenas uma restrição.

O padrão combinado (carregamento de servidor mais carregamento universal) tem a sobrecarga de ambos: o carregamento de servidor roda no servidor, e depois o carregamento universal roda no ambiente apropriado, usando o resultado do carregamento de servidor. Use o padrão combinado apenas quando você realmente precisar de ambas as capacidades; não o use por padrão por hábito.

Quando NÃO Usar Este Padrão

O padrão combinado de +page.server.ts mais +page.ts é poderoso, mas representa complexidade adicional. A maioria das rotas precisa apenas de um ou do outro. Se você se encontrar recorrendo frequentemente ao padrão combinado, pode ser um sinal de que sua rota está fazendo coisas demais; buscar dados privilegiados do servidor e construir objetos ricos do lado do cliente que seria melhor separar em rotas ou componentes distintos.

A função de carregamento universal não é adequada como alternativa para tornar dados do servidor "mais convenientes". Se os dados requerem acesso exclusivo ao servidor, eles pertencem a uma função de carregamento de servidor, ponto final. Usar uma função de carregamento universal e depois proteger manualmente contra a execução no navegador anula a segurança estrutural que a convenção de nomenclatura dos arquivos fornece.

Conclusão

Funções de load universais e de servidor ocupam ambientes diferentes e possuem capacidades distintas. Funções de load universais rodam tanto no servidor quanto no navegador, pertencem ao +page.ts e são adequadas para dados públicos e valores de retorno não serializáveis. Funções de load de servidor sempre rodam no servidor, pertencem ao +page.server.ts e são o lugar correto para qualquer coisa que exija acesso privilegiado, como consultas a banco de dados, variáveis de ambiente privadas e cookies de sessão. A convenção de nomenclatura de arquivos não é apenas organizacional; ela é o mecanismo de aplicação de uma fronteira de segurança significativa.

Quando você entende não apenas qual arquivo usar, mas por que essa distinção existe, a escolha se torna direta: pergunte a quais recursos a função de load precisa ter acesso e deixe a resposta indicar em qual arquivo ela pertence.

Uma Nota sobre os Rumos do Ecossistema

O SvelteKit está desenvolvendo um recurso experimental chamado Remote Functions que aborda a fronteira cliente-servidor de um ângulo diferente. Em vez de estruturar a lógica do servidor em torno de arquivos de rota, as Remote Functions permitem definir funções do lado do servidor em arquivos .remote.ts e chamá-las de qualquer lugar na árvore de componentes, inclusive diretamente da marcação de componentes usando a opção async do compilador Svelte.

As Remote Functions ainda estão sob a flag experimental no momento desta escrita, e a API tem mudado significativamente a cada lançamento. Elas não são abordadas nesta série porque ensinar uma API que pode quebrar entre versões menores do SvelteKit seria um desserviço aos leitores. Quando estabilizarem, merecerão sua própria série dedicada. Enquanto isso, os padrões de função de load abordados aqui são a base pronta para produção sobre a qual as próprias Remote Functions são construídas.

Principais Conclusões

Funções de load universais (+page.ts) rodam no servidor durante o SSR e no navegador durante a navegação do lado do cliente. Elas podem retornar valores não serializáveis, mas nunca devem conter importações exclusivas do servidor ou credenciais privadas, pois seu código é empacotado para o navegador.

Funções de load de servidor (+page.server.ts) sempre rodam no servidor. Elas têm acesso exclusivo a cookies, locals, variáveis de ambiente privadas e módulos exclusivos do servidor. Seus valores de retorno devem ser serializáveis, pois trafegam pela rede até o navegador.

Quando uma rota precisa tanto de acesso privilegiado a dados quanto de valores de retorno não serializáveis, ambos os arquivos podem coexistir. O load de servidor roda primeiro e seu valor de retorno chega como data no argumento de evento do load universal. O load universal é responsável por incluir em seu próprio valor de retorno quaisquer dados do servidor que o componente precise.

A convenção de nomenclatura de arquivos é a fronteira de segurança. Importar módulos $lib/server/ em uma função de load universal é um erro em tempo de build. Retornar valores não serializáveis de uma função de load de servidor é um erro em tempo de execução. Ambas as falhas são explícitas por design.

O Que Vem a Seguir

Com uma compreensão sólida dos dois tipos de função de load, é hora de analisar quais informações uma função de load pode utilizar além de apenas saber qual rota está ativa. A própria URL contém uma riqueza de dados (parâmetros de caminho, query strings e o pathname completo), e o SvelteKit fornece às funções de load acesso estruturado e tipado a todos eles. O próximo artigo, Usando dados de URL em Funções de Load, aborda como usar esses dados de URL de forma eficaz em funções de load universais e de servidor, e como manter a estrutura de URL limpa e intuitiva à medida que sua aplicação cresce.

Leitura Complementar

Módulos Exclusivos do Servidor no SvelteKit (como a fronteira $lib/server/ é aplicada)
Opções de Página do SvelteKit (controle de SSR e pré-renderização, o que afeta quando as funções de load são executadas)
Documentação Oficial de Load do SvelteKit (a referência oficial para todas as opções e tipos de função de load)