Segurança de Tipos no SvelteKit

Um dos recursos mais poderosos do SvelteKit é sua geração automática de tipos. Se você estiver usando TypeScript, o SvelteKit garante que os dados retornados pela sua função load sejam exatamente o que seu componente recebe — com IntelliSense completo e verificação de erros em tempo de compilação.

O motivo pelo qual isso é valioso na prática: sem tipos gerados, alterar o formato de retorno de uma função load é silencioso. Você renomeia um campo, e o template do componente ainda referencia o nome antigo. Nada reclama em tempo de build. Você envia o bug para produção e ele aparece como um erro em tempo de execução quando um usuário acessa aquela página.

Com os tipos gerados pelo SvelteKit, renomear um campo em uma função load imediatamente destaca todos os componentes que referenciam o nome antigo. O sistema de tipos se torna um assistente de refatoração — você faz uma mudança e segue os sublinhados vermelhos até que tudo esteja consistente novamente.

Segurança de tipos não é apenas sobre detectar bugs — é sobre a confiança do desenvolvedor. Quando você refatora uma função load, o TypeScript mostrará imediatamente todos os componentes que precisam ser atualizados. Esta é a diferença entre "espero não ter quebrado nada" e "sei exatamente o que mudei."

A Mágica do `$types`

Quando você executa seu servidor de desenvolvimento (npm run dev), o SvelteKit monitora seus arquivos de rota. Toda vez que você salva um +page.js, +page.server.js ou arquivo de layout, ele analisa o que você está retornando e gera definições de tipos automaticamente.

Você acessa esses tipos gerados a partir de um módulo virtual especial: ./$types.

// src/routes/blog/+page.ts
import type { PageLoad } from './$types' // ← Generated by SvelteKit

export const load: PageLoad = async ({ params }) => {
	return {
		title: 'Hello',
		count: 42
	}
}

Por Que Isso Detecta Bugs Reais

Aqui está um cenário concreto. Você tem uma página de blog funcionando:

// +page.ts
export const load: PageLoad = async () => {
	return { posts: await fetchPosts() }
}

<!-- +page.svelte -->
<script lang="ts">
	let { data }: PageProps = $props()
</script>

<h1>{data.posts.length} posts</h1>

Agora você refatora e renomeia o campo:

// +page.ts — renamed 'posts' to 'articles'
export const load: PageLoad = async () => {
	return { articles: await fetchPosts() }
}

Sem tipos, isso compila normalmente. O componente quebra silenciosamente em tempo de execução — data.posts agora é undefined, e seus usuários veem um erro. Com os tipos gerados pelo SvelteKit, seu editor imediatamente mostra:

<h1>{data.posts.length} posts</h1>
<!--        ^^^^^ Property 'posts' does not exist on type '{ articles: Post[] }' -->

Você encontra o problema em segundos, antes de chegar a ser publicado. Esta é a proposta de valor central: tipos tornam a refatoração segura.

Como Funciona

Passo 1: Tipar sua Função Load

O tipo PageLoad fornece autocompletar completo para todos os parâmetros disponíveis, incluindo o formato exato de params inferido a partir dos nomes das suas pastas:

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

export const load: PageLoad = async ({ params, fetch, url }) => {
	// TypeScript knows:
	// - params.slug exists (from the [slug] folder name)
	// - fetch is the special SvelteKit fetch
	// - url is a URL object

	const response = await fetch(`/api/posts/${params.slug}`)

	return {
		post: await response.json(),
		relatedPosts: []
	}
}

Passo 2: Tipar seu Componente

O tipo PageProps sabe exatamente o que sua função load retorna:

<!-- src/routes/blog/[slug]/+page.svelte -->
<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()

	// TypeScript knows:
	// - data.post exists
	// - data.relatedPosts exists
	// - data.post is the return type from your API
</script>

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

O Fluxo de Ponta a Ponta

flowchart
    A["+page.ts returns { title, posts }"] --> B["SvelteKit generates types"]
    B --> C["PageProps knows data.title, data.posts"]
    C --> D["Component gets autocomplete"]

    style A fill:#fff3e0, color:#000
    style B fill:#e1f5fe, color:#000
    style C fill:#f3e5f5, color:#000
    style D fill:#e8f5e9, color:#000

Se você alterar sua função load:

// Before
return { title: 'Hello', posts: [] }

// After - removed 'title'
return { posts: [] }

Seu componente imediatamente mostra um erro:

<h1>{data.title}</h1>
<!--        ^^^^^ Property 'title' does not exist -->

Você detecta os bugs antes mesmo de executar o código!

Este ciclo de feedback instantâneo é o motivo pelo qual o TypeScript brilha no SvelteKit. Mude um tipo em um lugar e veja todo o código afetado imediatamente destacado.

Tipos Disponíveis

Tipos de Página

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

// src/routes/blog/+page.server.ts
import type { PageServerLoad } from './$types'

// src/routes/blog/+page.svelte
import type { PageProps } from './$types'

Tipos de Layout

// src/routes/+layout.ts
import type { LayoutLoad } from './$types'

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types'

// src/routes/+layout.svelte
import type { LayoutProps } from './$types'

Tipos de Endpoint do Servidor

// src/routes/api/posts/+server.ts
import type { RequestHandler } from './$types'

export const GET: RequestHandler = async ({ params, url }) => {
	// ...
}

Parâmetros de Rota São Tipados

O SvelteKit infere tipos de parâmetros a partir da estrutura de pastas:

src/routes/blog/[slug]/+page.ts
              ^^^^^^
              params.slug: string

src/routes/users/[id]/posts/[postId]/+page.ts
                ^^^^        ^^^^^^^^
                params.id: string
                params.postId: string

// src/routes/users/[id]/posts/[postId]/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params }) => {
	// TypeScript knows both params exist
	const userId = params.id // Correct - string
	const postId = params.postId // Correct - string
	const other = params.other // Error: Property 'other' does not exist
}

Dados do Pai São Tipados

Ao acessar dados do pai, o TypeScript sabe o que está disponível:

// src/routes/+layout.server.ts
export const load = async () => {
	return {
		user: { name: 'John', email: 'john@example.com' }
	}
}

// src/routes/dashboard/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ parent }) => {
	const parentData = await parent()

	// TypeScript knows parentData.user exists!
	console.log(parentData.user.name)

	return {
		dashboardData: []
	}
}

Tipos de Ações de Formulário

As ações de formulário também recebem segurança de tipos completa:

// src/routes/login/+page.server.ts
import type { Actions, PageServerLoad } from './$types'
import { fail } from '@sveltejs/kit'

export const load: PageServerLoad = async () => {
	return { message: 'Please log in' }
}

export const actions: Actions = {
	default: async ({ request }) => {
		const data = await request.formData()
		const email = data.get('email')

		if (!email) {
			return fail(400, {
				error: 'Email is required',
				email: '' // Return for form repopulation
			})
		}

		return { success: true }
	}
}

<!-- src/routes/login/+page.svelte -->
<script lang="ts">
	import type { PageProps } from './$types'

	let { data, form }: PageProps = $props()

	// TypeScript knows:
	// - data.message: string
	// - form?.error: string | undefined
	// - form?.success: boolean | undefined
</script>

{#if form?.error}
	<p class="error">{form.error}</p>
{/if}

{#if form?.success}
	<p class="success">Logged in!</p>
{/if}

O Diretório `.svelte-kit`

O SvelteKit gera tipos em um diretório oculto .svelte-kit/types. Você não precisa examinar esses arquivos, mas entender que eles existem ajuda a explicar a "mágica":

.svelte-kit/
└── types/
    └── src/
        └── routes/
            ├── $types.d.ts           ← Root route types
            ├── blog/
            │   ├── $types.d.ts       ← /blog types
            │   └── [slug]/
            │       └── $types.d.ts   ← /blog/[slug] types

Esses arquivos são gerados automaticamente e devem estar no seu .gitignore.

Configuração do TypeScript

O tsconfig.json do SvelteKit é pré-configurado para entender o $types:

{
	"extends": "./.svelte-kit/tsconfig.json",
	"compilerOptions": {
		"strict": true
	}
}

A configuração estendida inclui aliases de caminho que fazem o ./$types funcionar.

Padrões Comuns

Tipando Respostas de API

// src/lib/types.ts
export interface Post {
	id: string
	title: string
	content: string
	createdAt: string
}

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'
import type { Post } from '$lib/types'

export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/posts')
	const posts: Post[] = await response.json()

	return { posts }
}

Tipos Compartilhados Entre Rotas

// src/lib/types.ts
export interface User {
	id: string
	name: string
	email: string
}

export interface LayoutData {
	user: User | null
}

Type Guards para Tratamento de Erros

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

	let { data }: PageProps = $props()

	// Type guard for optional data
	function hasPost(d: typeof data): d is typeof data & { post: NonNullable<typeof data.post> } {
		return d.post !== null
	}
</script>

{#if hasPost(data)}
	<h1>{data.post.title}</h1>
{:else}
	<p>No post found</p>
{/if}

Solução de Problemas

Tipos Não Estão Atualizando?

Certifique-se de que seu servidor de desenvolvimento está em execução (pnpm dev)
Tente reiniciar o servidor de desenvolvimento
Execute pnpm check para regenerar os tipos

Erros de Importação?

Certifique-se de que você está importando de ./$types, não de $types:

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

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

Sublinhados Vermelhos em Novos Arquivos?

Após criar uma nova rota, salve o arquivo e aguarde um momento para que os tipos sejam gerados. Às vezes é necessário fechar e reabrir o arquivo no seu editor.

Conclusão

A geração automática de tipos do SvelteKit transforma o TypeScript de um recurso desejável em um acelerador fundamental de desenvolvimento. Ao analisar seus arquivos de rota e gerar tipos abrangentes, ele elimina toda uma categoria de bugs relacionados a incompatibilidades de props, tipos de parâmetros incorretos e violações de contrato de API.

Os tipos PageData, PageServerData e LayoutData fluem automaticamente das funções de carregamento para os componentes, sem necessidade de definições manuais de tipos ou asserções de tipo propensas a erros.

Dominar a segurança de tipos no SvelteKit significa adotar a convenção ./$types, entender como o estreitamento de tipos funciona com uniões discriminadas e aproveitar os tipos gerados para formulários e actions. Quando os tipos fluem automaticamente do servidor para o cliente, das funções de carregamento para os componentes e dos formulários para os manipuladores de actions, você constrói aplicações onde classes inteiras de erros em tempo de execução se tornam avisos em tempo de compilação.

Isso não é apenas sobre detectar bugs — é sobre construir com confiança, refatorar sem medo e deixar o sistema de tipos guiar o desenvolvimento.

Principais Conclusões

O SvelteKit gera tipos automaticamente a partir dos arquivos de rota em .svelte-kit/types — importe-os via ./$types para obter parâmetros de função de carregamento e props de componentes com segurança de tipos
Os tipos PageProps fluem automaticamente dos valores de retorno das funções de carregamento para as props dos componentes: let { data }: PageProps = $props() no Svelte 5 oferece segurança de tipos completa com base no que sua função de carregamento retorna
Uniões discriminadas permitem o estreitamento de tipos — use type guards para diferenciar entre PageData e PageServerData com base em condições de tempo de execução
As actions de formulário são tipadas via ActionData — os valores de retorno das actions de formulário são automaticamente tipados na prop form e em page.form
O operador satisfies valida sem ampliar — use satisfies PageLoad ou satisfies PageServerLoad para detectar erros enquanto preserva os tipos de retorno inferidos
Execute o comando sync após alterações nos arquivos — npm run dev ou svelte-kit sync regenera os tipos quando você adiciona ou modifica arquivos de rota
Os tipos gerados incluem helpers para actions — o tipo Actions de ./$types fornece autocompletar e validação para exportações de actions de formulário
O TypeScript detecta erros de roteamento em tempo de build — parâmetros incorretos, formatos de dados incompatíveis e respostas de actions inválidas são detectados antes da implantação

Veja Também

Documentação Oficial do SvelteKit - Segurança de Tipos
Tipos Gerados - Entendendo as importações de ./$types
Actions de Formulário - Manipuladores de actions tipados
TypeScript satisfies - Validação sem ampliação de tipos
Uniões Discriminadas - Padrões de estreitamento de tipos