Por que o SvelteKit Gera Tipos para Você

Ao longo desta série você viu import type { PageLoad } from './$types', import type { PageProps } from './$types'. Cada arquivo de rota importa seus tipos de um caminho que parece uma importação relativa local, mas esses são gerados no diretório oculto .svelte-kit/types/ do SvelteKit quando a aplicação está em execução.

A geração automática de tipos do SvelteKit é projetada para manter os tipos de rota em sincronia com a estrutura de diretórios e as saídas das funções load. Em vez de definir manualmente os tipos para parâmetros de rota e valores de retorno de funções load, o SvelteKit cria um arquivo $types para cada rota no diretório oculto .svelte-kit/types/. Isso garante que o objeto params, a forma dos dados retornados pelas funções load e a prop data recebida pelos componentes sejam sempre tipados com precisão.

Por exemplo, a rota src/routes/shop/[category]/[productId] terá um tipo params de { category: string; productId: string }, e seu tipo data dependerá do que a função load retorna, como { product, variants }. Em contrapartida, a rota src/routes/blog/[slug] terá um tipo params de { slug: string }, e sua função load pode retornar { post, relatedArticles }, resultando em um tipo data diferente. Os tipos gerados sempre refletem a estrutura exata dos parâmetros de rota e das saídas das funções load.

O arquivo $types gerado é o contrato entre a função load e o componente. Ele garante que se a função load retornar { post } e o componente referenciar data.psot com um erro de digitação, o TypeScript o detecta em tempo de compilação em vez de em tempo de execução. Essa segurança de tipo de ponta a ponta — do parâmetro de URL ao resultado do banco de dados até o template renderizado — é um dos pontos fortes genuínos do SvelteKit, mas só funciona se você usar os tipos corretos de forma consistente.

Este artigo é uma referência de quais tipos existem, em qual arquivo cada um pertence, como os dados mesclados de layout afetam o tipo do componente, como App.Locals se encaixa nisso, e os problemas mais comuns de inferência de tipos e como corrigi-los.

O Modelo de Geração de Tipos

O SvelteKit regenera o diretório .svelte-kit/types/ toda vez que você salva um arquivo e o servidor de desenvolvimento está em execução. Ele percorre o diretório src/routes/, lê os nomes dos segmentos dinâmicos a partir dos nomes de diretório, lê os símbolos exportados dos arquivos de rota e produz um conjunto de arquivos .d.ts que espelham a estrutura de rotas.

A importação ./$types em um arquivo de rota é resolvida pelo TypeScript para o arquivo gerado correspondente àquela rota. Você nunca precisa olhar os arquivos gerados diretamente; eles são um detalhe de implementação. O que importa é conhecer os nomes dos tipos que eles exportam e o que cada um descreve.

Para gerar os tipos sem o servidor em execução, use o comando pnpm exec svelte-kit sync no terminal.

Um bom modelo mental é este: para cada rota, o SvelteKit gera um tipo para a função load e um tipo para o componente que recebe sua saída. Para uma rota em src/routes/blog/[slug]/, os tipos gerados incluem:

Tipo	Usado em	Propósito
`PageLoad`	`+page.ts`	Tipo da função `load`
`PageServerLoad`	`+page.server.ts`	Tipo da função `load` (somente servidor)
`LayoutLoad`	`+layout.ts`	Tipo da função `load`
`LayoutServerLoad`	`+layout.server.ts`	Tipo da função `load` (somente servidor)
`PageProps`	`+page.svelte`	Forma das props para `$props()` — inclui `data` e `form`
`LayoutProps`	`+layout.svelte`	Forma das props para `$props()` — inclui `data` e `children`
`PageData`	qualquer lugar	Forma dos dados mesclados que a página recebe
`LayoutData`	qualquer lugar	Forma dos dados mesclados que o layout recebe
`RouteParams`	qualquer lugar	Forma do objeto `params` para esta rota

Nem todo arquivo precisa de todos esses tipos. A regra é: use o tipo que corresponde ao arquivo que você está escrevendo e ao papel que ele desempenha. As seções abaixo explicam cada um em contexto.

Tipos de Funções Load

PageLoad e PageServerLoad

Os tipos PageLoad e PageServerLoad diferem no que o argumento event contém, porque os dois tipos de arquivo têm acesso a entradas diferentes.

PageLoad

PageLoad é usado em arquivos +page.ts cuja função load é executada tanto no contexto do servidor quanto do cliente. Ele tem acesso a params, url, fetch, depends, route, parent e setHeaders, mas não a cookies, locals ou quaisquer outras propriedades exclusivas do servidor.

Isso significa que se você tentar acessar cookies em um arquivo +page.ts, o TypeScript lançará um erro porque sabe que essa propriedade não existe naquele contexto. Mais importante ainda, seria um erro em tempo de execução porque o código de +page.ts é executado no navegador, onde não há objeto cookies no evento.

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

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

export const load: PageLoad = async ({ params, url, fetch }) => {
	// params is typed as { slug: string } from the route structure
	const res = await fetch(`/api/posts/${params.slug}`)
	const post = await res.json()

	return { post }
}

PageServerLoad

PageServerLoad é usado em arquivos +page.server.ts cuja função load é executada somente no servidor. Ele tem acesso a tudo que PageLoad tem — params, url, fetch, depends, route, parent e setHeaders — além de cookies, locals e platform para contexto exclusivo do servidor, como autenticação, sessões e bindings específicos de implantação.

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

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

export const load: PageServerLoad = async ({ params, cookies, locals, fetch }) => {
	// cookies and locals are available here, not in PageLoad
	if (!locals.user) error(401, 'Authentication required')

	const res = await fetch(`/api/posts/${params.slug}`)
	if (res.status === 404) error(404, 'Post not found')

	const post = await res.json()
	return { post, user: locals.user }
}

Uma restrição importante: como +page.server.ts é executado apenas no servidor e seu valor de retorno é serializado e enviado ao cliente, você só pode retornar dados serializáveis — objetos simples, arrays, strings, números e datas. Retornar instâncias de classes ou funções falhará em tempo de execução; o TypeScript não impõe isso para você.

A propriedade platform é tipada pela interface App.Platform em app.d.ts, que os adaptadores de plataforma estendem para expor APIs específicas de implantação. Com @sveltejs/adapter-cloudflare, por exemplo, platform dá acesso aos bindings do Cloudflare Workers:

// src/app.d.ts (declared by the Cloudflare adapter)
declare global {
	namespace App {
		interface Platform {
			env: {
				MY_KV_NAMESPACE: KVNamespace
				MY_D1_DATABASE: D1Database
			}
			context: ExecutionContext
			caches: CacheStorage
		}
	}
}

Em seguida, na função load do servidor:

export const load: PageServerLoad = async ({ platform }) => {
	// platform.env is typed as Cloudflare bindings
	const value = await platform?.env.MY_KV_NAMESPACE.get('some-key')
	return { value }
}

Com adapter-node ou adapter-static, App.Platform permanece vazio ({}), então platform é undefined em tempo de execução. O tipo se restringe de acordo com o que o adaptador instalado declara.

LayoutLoad e LayoutServerLoad

LayoutLoad e LayoutServerLoad são os tipos equivalentes para +layout.ts e +layout.server.ts, respectivamente. Eles têm a mesma distinção de capacidades que as variantes de página.

A única propriedade exclusiva dos tipos de load de layout é a propriedade children do event, embora essa se refira aos dados das funções load filhas, não ao snippet children do Svelte. Na prática, a maioria dos loads de layout não precisa dela diretamente.

// src/routes/blog/+layout.server.ts

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

export const load: LayoutServerLoad = async ({ locals, fetch }) => {
	const res = await fetch('/api/posts/index')
	const posts = await res.json()

	return {
		posts,
		currentUser: locals.user
	}
}

Usar LayoutLoad ou PageServerLoad em um arquivo +layout.server.ts são ambos erros que produzirão erros do TypeScript quando você tentar usar propriedades exclusivas do servidor; portanto, os tipos gerados ajudam a detectar isso em tempo de compilação.

Tipos de Dados de Componente

PageData e PageProps

PageData é o tipo do objeto data mesclado que +page.svelte recebe. Ele combina o tipo de retorno da função load da própria página com os tipos de dados retornados por todas as funções load de layout ancestrais. Este é um ponto significativo: PageData em uma rota profundamente aninhada inclui dados do load do layout raiz, de cada load de layout intermediário e do load da página em si.

PageProps, introduzido no SvelteKit 2.16.0, é um nível acima de PageData: ele encapsula PageData no objeto props real que o componente recebe e adiciona quaisquer outras props junto com data. Pense em PageData como a forma do objeto data — PageProps é a forma da desestruturação completa de $props().

Para uma página que possui actions de formulário, PageProps se parece com isto internamente:

type PageProps = {
	data: PageData
	form: ActionData // only present when the route has form actions
}

Sempre use PageProps para $props() em +page.svelte. Ele tipifica corretamente tanto data quanto form em uma única importação:

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

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

	let { data }: PageProps = $props()

	// data.post comes from the page's own load function
	// data.posts comes from the blog section layout load (if it exists)
	// data.currentUser might come from the root layout load
</script>

<article>
	<h1>{data.post.title}</h1>
</article>

Se a rota tiver actions de formulário, PageProps fornece form automaticamente:

<!-- src/routes/contact/+page.svelte — route with a form action -->
<script lang="ts">
	import type { PageProps } from './$types'

	let { data, form }: PageProps = $props()
	// form is typed as ActionData — the result of the last form submission
</script>

Com a abordagem antiga de PageData, você teria que tipar form manualmente. PageProps elimina isso.

LayoutData e LayoutProps

LayoutData tipifica os dados disponíveis para um +layout.svelte. Inclui o valor de retorno da função load do próprio layout mesclado com todos os dados de layout ancestrais. Não inclui dados da página filha, porque os layouts não recebem dados da página através de data; eles os acessam através de page.data em $app/state se precisarem.

LayoutProps estende LayoutData com o tipo children: Snippet:

type LayoutProps = {
	data: LayoutData
	children: Snippet // always present — used to render nested routes
}

Todo +layout.svelte deve usar LayoutProps porque o snippet children é o mecanismo para renderizar conteúdo aninhado:

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

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

	let { data, children }: LayoutProps = $props()
	// children is the Snippet that renders the matched child route
</script>

<aside>
	{#each data.posts as post (post.slug)}
		<a href="/blog/{post.slug}">{post.title}</a>
	{/each}
</aside>

<main>
	{@render children()}
</main>

Esquecer children em um layout resulta em uma tela em branco em tempo de execução sem nenhum erro. Usar LayoutProps transforma isso em uma omissão detectada em tempo de compilação em vez de um mistério.

Quando ainda usar PageData e LayoutData

PageData e LayoutData ainda são os tipos corretos em qualquer lugar onde você precise diretamente da forma dos dados, fora da chamada $props() — em funções auxiliares, variáveis tipadas ou tipos de props de componentes filhos:

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

	function buildOpenGraphTags(data: PageData): Record<string, string> {
		return {
			'og:title': data.post.title,
			'og:description': data.post.excerpt
		}
	}
</script>

<!-- ArticleHeader.svelte — accepts PageData.post shape, not PageProps -->
<script lang="ts">
	import type { PageData } from '../routes/blog/[slug]/$types'

	let { post }: { post: PageData['post'] } = $props()
</script>

A regra é simples: PageProps / LayoutProps vão na chamada $props() no topo do componente. PageData / LayoutData vão em todo o resto.

Como Funcionam os Tipos de Dados Mesclados

A mesclagem de tipos TypeScript de dados de layout e página é um dos aspectos mais sutis do sistema de tipos do SvelteKit. Entendê-la é importante porque é a fonte de vários erros de tipo comuns.

Quando uma função load de página e uma função load de layout ambas retornam dados, o tipo PageData do SvelteKit é uma interseção de ambos os tipos de retorno. Se o load do layout raiz retornar { user: User | null } e o load do layout de blog retornar { posts: Post[] } e o load da página retornar { post: Post }, então PageData para essa página é efetivamente { user: User | null, posts: Post[], post: Post }.

Essa interseção é calculada pelo gerador de tipos do SvelteKit, não manualmente. A implicação é que se você adicionar um novo campo a qualquer função load na cadeia, PageData para todas as páginas dentro do escopo daquele layout é atualizado automaticamente na próxima vez que o servidor de desenvolvimento regenerar os tipos.

Onde fica complicado é na colisão de chaves. Se tanto o load do layout raiz quanto o load da página retornarem uma chave chamada title, o TypeScript usará a definição do load da página, mas o tipo gerado pode não refletir o que você espera. A abordagem mais segura é evitar colisões de chaves nos valores de retorno das funções load por completo, usando nomes distintos ou objetos com namespace.

// This creates a collision between layout and page

// src/routes/+layout.server.ts
export const load = async () => ({ title: 'My Site' })

// src/routes/blog/[slug]/+page.server.ts
export const load = async ({ params }) => ({ title: 'Post Title', post: {} })
// PageData.title is ambiguous; the page version wins at runtime
// but the type generator may produce a union type

// Preferred: use distinct, specific names to avoid collisions

// src/routes/+layout.server.ts
export const load = async () => ({ siteName: 'My Site', user: null })

// src/routes/blog/[slug]/+page.server.ts
export const load = async ({ params }) => ({ pageTitle: 'Post Title', post: {} })
// PageData has both siteName and pageTitle with no ambiguity

RouteParams e Params Tipados

RouteParams é um alias de tipo gerado para o objeto params de cada rota específica. O SvelteKit o deriva diretamente do nome do diretório: cada [segment] se torna uma propriedade string. Para src/routes/blog/[slug], o tipo gerado é:

// .svelte-kit/types/src/routes/blog/[slug]/$types.d.ts (generated)
export type RouteParams = {
	slug: string
}

Para uma rota com múltiplos segmentos como src/routes/shop/[category]/[productId]:

export type RouteParams = {
	category: string
	productId: string
}

Parâmetros rest e parâmetros opcionais produzem formatos ligeiramente diferentes. Um segmento rest [...path] se torna path: string, enquanto um segmento opcional [[lang]] se torna lang?: string:

// src/routes/[[lang]]/about — optional segment
export type RouteParams = { lang?: string }

// src/routes/files/[...path] — rest segment
export type RouteParams = { path: string } // value is the full path string, e.g. "a/b/c"

Por que você raramente precisa disso diretamente

PageLoad e PageServerLoad já utilizam RouteParams internamente. Quando você tipifica sua função de carregamento, params já é reduzido ao formato correto da rota — você obtém params.slug: string sem importar nada extra:

// params.slug is string — RouteParams is already applied under the hood
export const load: PageLoad = async ({ params }) => {
	const res = await fetch(`/api/posts/${params.slug}`)
	return { post: await res.json() }
}

Quando você precisa disso explicitamente

O caso em que você precisa de RouteParams diretamente é quando código fora de uma função de carregamento precisa aceitar ou trabalhar com parâmetros de rota — uma função utilitária em src/lib, um helper de servidor, ou um componente que constrói uma URL a partir de parâmetros passados como prop.

Observe o caminho de importação em todos os exemplos abaixo: fora do diretório da rota, você deve importar do arquivo $types da rota específica usando um caminho relativo ao arquivo que está fazendo a importação, não de ./$types.

Vejamos alguns exemplos práticos disso:

1: Utilitário de servidor que constrói uma URL canônica:

// src/lib/server/seo.ts
import type { RouteParams } from '../../routes/blog/[slug]/$types'

export function buildCanonicalUrl(params: RouteParams): string {
	return `https://example.com/blog/${params.slug}`
}

2: Helper de consulta ao banco de dados que aceita params como argumento — evita repetir o tipo inline { slug: string } em múltiplas funções de consulta:

// src/lib/server/db.ts
import type { RouteParams } from '../../routes/blog/[slug]/$types'
import { db } from './client'

export async function getPostByParams(params: RouteParams) {
	return db.post.findUnique({ where: { slug: params.slug } })
}

export async function getRelatedPosts(params: RouteParams) {
	return db.post.findMany({ where: { slug: { not: params.slug } }, take: 3 })
}

Ambas as funções permanecem sincronizadas automaticamente: se a rota ganhar um segundo segmento (ex.: [slug]/[version]), RouteParams é atualizado e o TypeScript sinaliza cada ponto de chamada que passa apenas { slug }.

3: Componente Svelte que recebe params como prop — útil quando um componente renderiza um link ou breadcrumb baseado na rota atual e recebe params propagados da página:

<!-- src/lib/components/PostBreadcrumb.svelte -->
<script lang="ts">
	import type { RouteParams } from '../../routes/blog/[slug]/$types'

	let { params }: { params: RouteParams } = $props()
</script>

<nav>
	<a href="/blog">Blog</a>
	<span>/</span>
	<a href="/blog/{params.slug}">{params.slug}</a>
</nav>

Sem RouteParams, você tipificaria a prop manualmente como { slug: string }. Com ele, o componente fica vinculado à estrutura real da rota e falhará em tempo de compilação se a rota renomear o segmento.

App.Locals e Tipos de Funções de Carregamento

A propriedade locals em PageServerLoad e LayoutServerLoad é tipificada por App.Locals de src/app.d.ts. Essa conexão entre a declaração de tipo e os tipos das funções de carregamento é automática: os tipos gerados pelo SvelteKit referenciam App.Locals diretamente, de modo que qualquer alteração na interface App.Locals é imediatamente refletida em todo lugar onde locals é utilizado.

// src/app.d.ts
declare global {
	namespace App {
		interface Locals {
			user: { id: string; email: string; role: string } | null
		}
	}
}
export {}

// src/routes/account/+page.server.ts
import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = ({ locals }) => {
	// locals.user is typed as { id: string; email: string; role: string } | null
	// because of App.Locals above
	if (!locals.user) error(401, 'Sign in required')

	return { account: locals.user }
}

O mesmo se aplica a App.PageData. Se você declarar essa interface em app.d.ts, ela se torna o tipo de page.data quando lida de $app/state, fornecendo ao layout raiz informações de tipo sobre o que qualquer página pode fornecer:

// src/app.d.ts
declare global {
	namespace App {
		interface Locals {
			user: { id: string; email: string; role: string } | null
		}
		interface PageData {
			// Optional properties any page might provide
			title?: string
			description?: string
		}
	}
}
export {}

Falhas Comuns na Inferência de Tipos

Valores de Retorno de Funções de Carregamento Sem Tipagem

Se você omitir PageLoad ou PageServerLoad e escrever a função de carregamento como uma função assíncrona sem tipagem, o TypeScript ainda infere tipos a partir do valor de retorno, mas o objeto params será tipado como Record<string, string> em vez do formato preciso específico da rota. Mais importante, o tipo de data do componente não será conectado ao tipo de retorno da função de carregamento; eles se tornam duas inferências independentes que podem divergir silenciosamente.

// Wrong: Weakly typed, params is Record<string, string>

export async function load({ params, fetch }) {
	const res = await fetch(`/api/posts/${params.slug}`)
	return { post: await res.json() }
}

// Correct: Strongly typed, params.slug is string and tracked

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

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

Sempre anote a função de carregamento com o tipo correto de ./$types.

Usando PageServerLoad em um Arquivo .ts

PageLoad é para +page.ts. PageServerLoad é para +page.server.ts. Os tipos em si têm formato semelhante, mas usar o errado produzirá erros de TypeScript ao tentar usar propriedades de evento exclusivas do servidor como cookies ou locals em um arquivo +page.ts, ou ao tentar retornar valores não serializáveis de um arquivo +page.server.ts.

// Wrong: PageServerLoad in a universal load file

// src/routes/blog/[slug]/+page.ts ← note: not .server.ts
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ params, cookies }) => {
	// TypeScript error: cookies does not exist on the universal load event
	const theme = cookies.get('theme')
	return { theme }
}

// Correct: PageLoad for universal, PageServerLoad for server

// src/routes/blog/[slug]/+page.ts
import type { PageLoad } from './$types'

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

O Tipo de Retorno `any` de Respostas de API Não Validadas

Uma fraqueza de tipagem comum em aplicações SvelteKit é que await res.json() retorna any. Isso significa que data.post no componente é tipado como any, o que anula completamente o propósito do sistema de tipos. O TypeScript não detectará erros de digitação como data.post.athuor se o tipo for any.

A correção é afirmar o tipo da resposta com uma conversão de tipo ou, melhor ainda, validar a resposta usando uma biblioteca de esquemas:

// Weak: post is any

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

// Better: post is typed with a cast (no runtime validation)

type Post = {
	id: string
	title: string
	content: string
	publishedAt: string
}

export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/posts/${params.slug}`)
	const post = (await res.json()) as Post
	return { post }
}

// Best: post is typed and validated at runtime using valibot

import * as v from 'valibot'
import { error } from '@sveltejs/kit'

const PostSchema = v.object({
	id: v.string(),
	title: v.string(),
	content: v.string(),
	publishedAt: v.string()
})

export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/posts/${params.slug}`)
	const raw = await res.json()

	const result = v.safeParse(PostSchema, raw)
	if (!result.success) error(500, 'Invalid API response shape')

	return { post: result.output }
}

A validação em tempo de execução nem sempre é necessária, especialmente para APIs internas que você controla e confia. Mas a conversão as Type com uma interface escrita manualmente é um meio-termo razoável que pelo menos torna os erros de tipo visíveis no nível do componente.

Confusão entre PageData e PageProps

PageData é o tipo do próprio objeto data. PageProps é o tipo das props do componente, que envolve data dentro de um objeto. São tipos diferentes usados em lugares diferentes:

<!-- Wrong: Using PageData where PageProps is needed -->

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

	let { data }: PageData = $props()
	// TypeScript error: PageData is the data shape, not the props shape
</script>

<!-- Correct: Use PageProps for the $props() call -->

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

	let { data }: PageProps = $props()
	// data is now correctly typed as PageData
</script>

PageProps foi introduzido no SvelteKit 2.16.0. Antes dessa versão, o padrão correto era:

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

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

Ambos os padrões funcionam; PageProps é simplesmente a forma abreviada mais limpa.

Considerações de Desempenho e Escalabilidade

Os arquivos $types gerados contêm declarações simples de interface e alias de tipo TypeScript. Eles não são computacionalmente custosos para o compilador TypeScript processar. Mesmo uma aplicação grande com centenas de rotas não experimentará lentidões significativas na verificação de tipos apenas pela geração de tipos de rotas.

A principal preocupação de escalabilidade é a contaminação pelo tipo any descrita acima. À medida que uma aplicação cresce, tipos any nos valores de retorno de funções de carregamento se propagam para os templates de componentes e removem silenciosamente a segurança de tipos que torna a refatoração segura. Auditorias periódicas em busca de any nos valores de retorno de funções de carregamento, especialmente em torno de chamadas fetch, são úteis em bases de código grandes.

Uma preocupação menos óbvia é o tamanho dos valores de retorno das funções de carregamento. Tudo que uma função de carregamento retorna é serializado no payload HTML da página quando retornado de um +page.server.ts. Não há imposição pelo TypeScript aqui; uma função de carregamento pode retornar um objeto de 10MB e o TypeScript não reclamará. O sistema de tipos não impõe o tamanho do payload, portanto monitoramento em tempo de execução e disciplina dos desenvolvedores são as ferramentas adequadas para essa preocupação.

Conclusão

O sistema $types do SvelteKit elimina o código repetitivo de declarar manualmente os formatos de dados para cada rota. Os tipos gerados conectam o valor de retorno da função de carregamento à prop de dados do componente, a estrutura de diretórios da rota ao tipo de params, e a declaração App.Locals a todas as funções de carregamento do servidor. Usado de forma consistente, o resultado é uma base de código onde erros de tipo na camada de dados surgem em tempo de compilação, e não em tempo de execução.

As regras são simples: PageLoad para +page.ts, PageServerLoad para +page.server.ts, LayoutLoad para +layout.ts, LayoutServerLoad para +layout.server.ts. PageProps para $props() do componente em páginas, LayoutProps para layouts. Sempre importe de ./$types. Sempre tipifique o formato da resposta ao usar fetch.

Principais Conclusões

O SvelteKit gera um arquivo $types para cada rota que exporta PageLoad, PageServerLoad, LayoutLoad, LayoutServerLoad, PageData, PageProps, LayoutData, LayoutProps e RouteParams. Importe de ./$types em cada arquivo de rota para obter tipos precisos e mantidos automaticamente.

PageData é o tipo de dados mesclado, incluindo todos os valores de retorno das funções de carregamento de layouts ancestrais. Adicionar um campo a qualquer função de carregamento de layout automaticamente o adiciona ao PageData de todas as páginas dentro do escopo daquele layout.

App.Locals em src/app.d.ts tipifica event.locals em todo lugar. App.PageData tipifica page.data quando lido de $app/state. Ambos são aumentos de tipo globais que se propagam automaticamente.

A conversão await res.json() as Type impede a contaminação por any proveniente de respostas de API sem tipagem. Bibliotecas de validação de esquemas como o Zod adicionam segurança em tempo de execução sobre a afirmação de tipo do TypeScript.

O Que Vem a Seguir

Com a base TypeScript totalmente estabelecida, a série avança para os tópicos avançados de desempenho. O streaming permite que você retorne dados lentos como promises não resolvidas em vez de bloquear a renderização inicial neles. O próximo artigo, Streaming de Dados com Promises, aborda o padrão, a sintaxe {#await} para lidar com estados transmitidos em componentes, ressalvas de plataforma, e quando o streaming é ou não a ferramenta certa.

Leitura Adicional

Documentação de Tipos Gerados do SvelteKit — referência oficial para todas as exportações de tipos gerados de $types
Referência App.d.ts do SvelteKit — a lista completa de interfaces do namespace App, incluindo Locals, PageData, Error e Platform
locals e o Ciclo de Vida dos Hooks — como App.Locals é populado em hooks.server.ts antes das funções de carregamento serem executadas
Funções de Carregamento Universais vs. de Servidor — o artigo fundamental sobre quando cada tipo de arquivo de carregamento é apropriado, o que determina qual tipo de carregamento você importa