Armadilhas da Renderização no Lado do Servidor com Runes no Svelte 5

O Paradigma de Aplicação Universal

A renderização no lado do servidor representa uma mudança de paradigma na forma como pensamos sobre a arquitetura de aplicações web. Diferentemente dos primórdios das aplicações de página única, onde o JavaScript era o único responsável por renderizar conteúdo no navegador, frameworks modernos como o SvelteKit adotam uma abordagem "universal" na qual o código da sua aplicação é executado em múltiplos ambientes. Essa decisão arquitetural traz benefícios enormes — carregamentos iniciais mais rápidos, melhor SEO, maior acessibilidade e degradação graciosa quando o JavaScript falha — mas também introduz uma categoria de desafios que muitos desenvolvedores acham confusa e frustrante.

Quando o Svelte 5 introduziu as runes como o novo primitivo reativo, isso mudou fundamentalmente a forma como os desenvolvedores expressam reatividade em suas aplicações. As runes $state, $derived e $effect fornecem um modelo de reatividade mais explícito e previsível em comparação com as declarações reativas implícitas do Svelte 4. No entanto, esse novo modelo interage com a renderização no lado do servidor de maneiras que exigem compreensão cuidadosa. Uma rune que funciona perfeitamente em um contexto somente cliente pode causar bugs sutis, incompatibilidades de hidratação ou falhas totais quando seu componente é executado no servidor.

Este tutorial tem como objetivo construir um modelo mental abrangente para entender o SSR com as runes do Svelte 5. Em vez de simplesmente fornecer trechos de código para copiar, exploraremos os princípios subjacentes que governam como o código é executado em diferentes ambientes, por que certos padrões causam problemas e como pensar sobre o design de componentes de uma forma que naturalmente evite as armadilhas do SSR. Ao final desta imersão, você terá não apenas soluções para problemas comuns, mas o framework conceitual para raciocinar sobre novas situações que encontrar.

Compreendendo a Natureza Fundamental das Aplicações Universais

Para realmente entender as armadilhas do SSR, devemos primeiro compreender o que significa uma aplicação ser "universal". Esse termo descreve aplicações onde a mesma base de código é executada em ambientes fundamentalmente diferentes: o servidor (tipicamente Node.js, mas potencialmente Deno, Bun ou runtimes de borda como Cloudflare Workers) e o navegador. Esses ambientes compartilham o JavaScript como linguagem, mas diferem dramaticamente em suas APIs disponíveis, modelos de execução e propósitos.

Considere o que acontece quando um usuário navega para sua aplicação SvelteKit pela primeira vez. O navegador envia uma requisição HTTP para o seu servidor. O servidor recebe essa requisição e precisa responder com HTML que o navegador possa exibir. Em uma aplicação tradicional renderizada no servidor (como PHP ou Ruby on Rails), o servidor usaria templates para gerar esse HTML diretamente. Em uma SPA do lado do cliente, o servidor retornaria um shell HTML mínimo, e o JavaScript construiria a página inteira no navegador.

O SvelteKit adota uma abordagem híbrida. Quando o servidor recebe a requisição, ele realmente executa seus componentes Svelte — executando o código JavaScript que você escreveu — para produzir o HTML inicial. Isso significa que o bloco <script> do seu componente é executado no servidor, suas declarações reativas são avaliadas e o Svelte renderiza a marcação resultante em uma string HTML. Esse HTML é enviado ao navegador, onde o usuário vê imediatamente conteúdo significativo.

Mas a história não termina aí. O navegador também recebe seu bundle JavaScript. Assim que esse JavaScript é carregado e executado, o Svelte realiza um processo chamado "hidratação", no qual ele pega o HTML renderizado no servidor existente e o torna interativo. Durante a hidratação, o código do seu componente é executado novamente — desta vez no navegador — e o Svelte anexa manipuladores de eventos, configura assinaturas reativas e prepara a aplicação para a interação do usuário.

Essa execução dual é a origem de cada armadilha do SSR que discutiremos. Seu código é executado duas vezes: uma vez no servidor para gerar HTML e uma vez no cliente para habilitar a interatividade. Compreender essa realidade fundamental é a chave para evitar problemas.

Por Que Essa Arquitetura Existe?

Antes de mergulhar nos detalhes técnicos, vale a pena entender por que o SvelteKit (e frameworks como Next.js, Nuxt e Remix) escolheram essa arquitetura. Os benefícios são substanciais o suficiente para justificar a complexidade adicional.

Desempenho e velocidade percebida representam a motivação primária. Quando um usuário requisita uma página, quer ver o conteúdo o mais rápido possível. Com a renderização do lado do cliente, o navegador precisa baixar o shell HTML, depois baixar o bundle JavaScript e então executar o JavaScript para renderizar o conteúdo. Somente após a conclusão de todas essas etapas o usuário vê algo significativo. Com o SSR, o servidor envia HTML completo imediatamente. O usuário vê o conteúdo enquanto o JavaScript é baixado em segundo plano. Isso melhora dramaticamente o desempenho percebido, especialmente em conexões mais lentas ou em dispositivos menos potentes.

A otimização para mecanismos de busca fornece outro motivo convincente. Embora os mecanismos de busca modernos possam executar JavaScript e indexar conteúdo renderizado no cliente, o SSR garante que os crawlers vejam o conteúdo completo imediatamente. Isso elimina a incerteza sobre como os mecanismos de busca interpretarão suas páginas e pode melhorar seu posicionamento nas buscas.

A acessibilidade e o aprimoramento progressivo se beneficiam significativamente do SSR. Usuários que navegam com JavaScript desabilitado (seja por escolha ou por firewalls corporativos) ainda podem acessar seu conteúdo. Os leitores de tela recebem marcação completa imediatamente, em vez de esperar pela execução do JavaScript. A aplicação degrada graciosamente quando algo dá errado.

O compartilhamento em redes sociais depende do SSR para gerar pré-visualizações de links. Quando alguém compartilha um link para o seu site no Twitter ou Facebook, essas plataformas buscam o HTML e extraem metadados. Elas não executam JavaScript, portanto o conteúdo renderizado no cliente não apareceria nas pré-visualizações.

Esses benefícios explicam por que a indústria migrou amplamente para o SSR em aplicações de produção. Compreender esse contexto ajuda a enquadrar os desafios que abordaremos: a complexidade do SSR é o preço que pagamos por esses benefícios substanciais.

Os Dois Ambientes: Uma Comparação Detalhada

Vamos examinar em detalhes as diferenças entre os ambientes de servidor e de navegador, pois essas diferenças são a causa raiz da maioria dos problemas de SSR.

O ambiente do servidor é executado no Node.js (ou em um runtime similar). Esse ambiente não tem conceito de exibição visual, interação do usuário ou APIs do navegador. Não existe objeto window, nem document, nem localStorage, nem navigator, nem IntersectionObserver, nem ResizeObserver. O servidor não sabe o tamanho da tela do usuário, a preferência de esquema de cores, o fuso horário ou o locale. Ele não pode reproduzir áudio, renderizar em canvas ou acessar a área de transferência. O trabalho do servidor é processar uma requisição e produzir uma resposta o mais rápido possível — idealmente em milissegundos.

A execução no servidor também é fundamentalmente diferente em seu ciclo de vida. Quando o servidor renderiza seu componente, executa o código de forma síncrona, produz HTML e descarta todo o estado. Não há processo contínuo monitorando mudanças. O servidor renderiza uma vez e segue em frente. Se 1000 usuários requisitarem a mesma página, o servidor a renderizará 1000 vezes (a menos que você implemente cache), sendo cada renderização independente e sem estado.

O ambiente do navegador é rico em APIs, mas restrito de maneiras diferentes. Ele tem acesso a todas as APIs da plataforma web — manipulação do DOM, armazenamento, sensores do dispositivo, reprodução de mídia — mas é executado em uma sandbox com restrições de segurança. O navegador não pode acessar o sistema de arquivos, executar comandos shell ou conectar-se diretamente a bancos de dados. Ele é executado em um loop de eventos que responde a interações do usuário, respostas de rede e callbacks de temporizadores.

A execução no navegador também é persistente dentro de uma sessão. Uma vez que seu componente é montado, ele permanece ativo até que o usuário navegue para outro lugar ou feche a aba. O estado persiste entre interações. Os efeitos são executados e re-executados em resposta a mudanças de estado. O componente existe no tempo, respondendo a um fluxo contínuo de eventos.

A percepção crucial é que os ambientes de servidor e de navegador compartilham quase nada, exceto a linguagem JavaScript em si. Quando você escreve código que assume que as APIs do navegador existem, esse código falhará no servidor. Quando você escreve código que assume estado persistente, esse código não funcionará corretamente com o modelo de renderização única do SSR. Um SSR bem-sucedido exige escrever código que funcione corretamente em ambos os ambientes — ou tratar explicitamente as diferenças.

A Linha do Tempo do SSR: Uma Análise Momento a Momento

Entender exatamente quando o código é executado é essencial para evitar problemas de SSR. Vamos acompanhar o ciclo de vida completo de uma requisição de página, examinando o que acontece em cada etapa.

Fase 1: O Servidor Recebe uma Requisição

Tudo começa com uma requisição HTTP. Um usuário digita uma URL, clica em um link ou envia um formulário. O navegador envia uma requisição ao seu servidor. O código do lado do servidor do SvelteKit recebe essa requisição e começa a processá-la.

Durante esta fase, o SvelteKit executa suas funções de carregamento +page.server.js e +page.js (caso existam). Essas funções podem acessar recursos do lado do servidor como bancos de dados, fazer chamadas autenticadas a APIs e preparar dados para seus componentes. Os dados retornados pelas funções de carregamento ficam disponíveis como props para os componentes de página.

É também nesta fase que os cookies são lidos, as sessões de usuário são validadas e qualquer lógica do lado do servidor é executada. De forma crucial, isso acontece antes que qualquer código de componente seja executado. No momento em que seus componentes Svelte são executados, as funções de carregamento já foram concluídas.

Fase 2: Execução do Componente no Servidor

Com os dados carregados, o SvelteKit começa a renderizar sua árvore de componentes. Partindo do layout raiz e descendo pelos layouts aninhados até o componente de página, o Svelte executa o bloco <script> de cada componente.

É aqui que as coisas ficam interessantes para as runes. Quando o servidor executa seu componente:

As declarações $state são executadas e inicializadas. O valor inicial que você fornece se torna o valor do estado. Se você escrever let count = $state(0), a variável count possui o valor 0. Quaisquer modificações síncronas subsequentes nesse estado são capturadas — se você imediatamente escrever count = 10, o estado se torna 10.

As declarações $derived calculam seus valores. O Svelte avalia a expressão de derivação usando os valores de estado atuais. Se você escrever let doubled = $derived(count * 2), e count for 10, então doubled se torna 20.

Os blocos $effect são completamente ignorados. Essa é talvez a regra mais importante a internalizar. Os efeitos nunca são executados no servidor. Ponto. O servidor pula os blocos $effect inteiramente. Isso faz sentido quando você pensa bem: os efeitos são projetados para efeitos colaterais que respondem a mudanças de estado ao longo do tempo, mas o servidor renderiza uma vez e descarta o resultado. No servidor, não existe "ao longo do tempo".

$props recebe valores dos componentes pai. As props funcionam de forma idêntica no servidor e no cliente — são apenas valores passados do pai para o filho.

Os callbacks onMount não são chamados. Assim como os efeitos, onMount só é executado no navegador. O callback é registrado, mas não executado.

Os callbacks onDestroy são chamados após a conclusão da renderização. Este é o único hook de ciclo de vida que é executado no servidor, permitindo a limpeza de quaisquer recursos alocados durante o ciclo de renderização.

Após todos os componentes terem sido executados, o Svelte serializa a árvore de componentes resultante em uma string HTML. Esse HTML representa o estado inicial completo da sua página.

Fase 3: Entrega do HTML ao Navegador

O servidor envia a resposta HTML ao navegador. Essa resposta inclui o HTML renderizado, mais as tags <script> que carregarão o seu bundle JavaScript, mais quaisquer dados serializados que o cliente precisa para a hidratação.

Neste momento, o usuário vê sua página. O conteúdo está visível e legível. Os links estão presentes (embora clicar neles causasse recarregamentos completos da página sem JavaScript). Os formulários existem (e funcionariam via submissão tradicional de formulário sem JavaScript). A página é utilizável, embora não totalmente interativa.

Este é o benefício do SSR: conteúdo significativo aparece antes mesmo do JavaScript começar a carregar. Em conexões lentas, isso pode economizar segundos de espera. Em conexões rápidas, ainda é perceptivelmente mais rápido do que esperar o JavaScript renderizar tudo.

Fase 4: Carregamento e Análise do JavaScript

Enquanto o usuário visualiza o HTML, o navegador baixa o bundle JavaScript em segundo plano. Dependendo do tamanho do bundle e da velocidade da conexão, isso pode levar de milissegundos a vários segundos.

Uma vez baixado, o navegador analisa e executa o JavaScript. Isso é computacionalmente caro, especialmente em dispositivos móveis. A thread principal fica ocupada durante esse período, o que pode fazer a página parecer sem resposta se o bundle for grande.

Fase 5: Hidratação

A hidratação é onde a mágica acontece — e onde os bugs de SSR frequentemente se manifestam. Durante a hidratação, o Svelte "se conecta" ao DOM existente em vez de criar novos elementos.

O processo de hidratação funciona aproximadamente assim:

O Svelte cria sua estrutura interna de árvore de componentes, espelhando o que foi criado no servidor.
Para cada componente, o Svelte executa o bloco <script> novamente — sim, seu código é executado uma segunda vez.
O Svelte percorre o DOM existente, correspondendo os elementos à sua representação interna.
Os manipuladores de eventos são anexados aos elementos DOM existentes.
As assinaturas reativas são estabelecidas para que a UI possa responder a mudanças de estado.
Os blocos $effect são executados pela primeira vez.
Os callbacks onMount são chamados.

O ponto crítico é o passo 3: o Svelte espera que o DOM existente corresponda ao que teria renderizado. Se o servidor renderizou <p>Olá</p> mas o código do cliente renderizaria <p>Mundo</p>, o Svelte detecta essa incompatibilidade. Em desenvolvimento, você verá avisos no console. Em produção, o Svelte tenta reconciliar a diferença, mas isso pode causar falhas visuais, manipuladores de eventos quebrados ou comportamento incorreto.

É por isso que ocorrem incompatibilidades de hidratação: quando o servidor e o cliente produzem resultados diferentes. Compreender as causas dessas incompatibilidades — e como evitá-las — é essencial para o sucesso com SSR.

Fase 6: Navegação do Lado do Cliente

Após a conclusão da hidratação, sua aplicação está totalmente interativa. O usuário pode clicar em botões, preencher formulários e acionar mudanças de estado. O sistema de reatividade do Svelte responde a essas mudanças, atualizando o DOM conforme necessário.

Quando o usuário navega para uma página diferente dentro da sua aplicação (clicando em um link interno), o SvelteKit intercepta a navegação e a trata do lado do cliente. Nenhuma nova requisição ao servidor é feita para o HTML. Em vez disso, o SvelteKit carrega o módulo JavaScript da nova página (se ainda não estiver em cache), busca dados das funções de carregamento e monta o novo componente de página.

Essa navegação do lado do cliente não envolve SSR. Os componentes são montados diretamente no navegador. É por isso que alguns bugs de SSR aparecem apenas no carregamento inicial da página, mas não na navegação subsequente — a navegação do lado do cliente pula o servidor completamente.

Análise Detalhada: Como Cada Rune se Comporta Durante o SSR

Agora que entendemos a linha do tempo, vamos examinar o comportamento de cada rune em detalhes. Compreender esses comportamentos ajudará você a antecipar problemas antes que ocorram.

A Rune `$state`: Inicialização do Estado Reativo

A rune $state cria estado reativo que aciona atualizações na UI quando modificado. Na superfície, parece simples: você declara uma variável com um valor inicial, e essa variável se torna reativa.

<script>
	let count = $state(0)
	let user = $state({ name: 'Anonymous', loggedIn: false })
	let items = $state(['apple', 'banana', 'cherry'])
</script>

Durante o SSR, essas declarações funcionam exatamente como esperado. As variáveis são inicializadas com os valores fornecidos. Se você as modificar de forma síncrona durante a execução do script, essas modificações entram em vigor:

<script>
	let count = $state(0)

	// This synchronous modification happens during SSR
	count = 10

	// The HTML will show 10, not 0
</script>

<p>Count: {count}</p>

A complexidade surge quando você tenta inicializar o estado a partir de fontes que não existem no servidor. Considere este código aparentemente razoável:

<script>
	// DANGEROUS: localStorage doesn't exist on the server!
	let savedTheme = $state(localStorage.getItem('theme') || 'light')
</script>

Este código falhará durante o SSR com um erro "localStorage is not defined". O servidor não tem localStorage — é uma API exclusiva do navegador. O mesmo se aplica a qualquer inicialização que dependa de APIs do navegador:

<script>
	// DANGEROUS: window doesn't exist on the server!
	let windowWidth = $state(window.innerWidth)

	// DANGEROUS: document doesn't exist on the server!
	let cookies = $state(document.cookie)

	// DANGEROUS: navigator doesn't exist on the server!
	let userAgent = $state(navigator.userAgent)
</script>

A solução envolve fornecer valores padrão seguros e adiar a inicialização específica do navegador para $effect, que exploraremos em breve.

Outro problema sutil envolve a reatividade profunda. Quando você usa $state com um objeto ou array, o Svelte cria um proxy profundamente reativo. Isso funciona de forma idêntica no servidor e no cliente, mas o comportamento do proxy tem implicações para a serialização:

<script>
	let todos = $state([
		{ id: 1, text: 'Learn SSR', done: false },
		{ id: 2, text: 'Avoid gotchas', done: false }
	])

	// This is a deeply reactive proxy
	// Modifications to nested properties trigger updates
	todos[0].done = true // This works reactively
</script>

A natureza do proxy significa que você não pode serializar diretamente valores de $state com JSON.stringify — você precisa usar $state.snapshot() primeiro. Isso geralmente não é um problema durante o SSR normal, mas é relevante se você estiver serializando o estado para depuração ou transferência de dados.

A Rune `$derived`: Valores Computados e Suas Dependências

O estado derivado representa valores computados que se atualizam automaticamente quando suas dependências mudam. Conceitualmente, as derivações são funções puras de outros estados:

<script>
	let firstName = $state('John')
	let lastName = $state('Doe')

	// This derivation depends on firstName and lastName
	let fullName = $derived(`${firstName} ${lastName}`)

	// Complex derivations use $derived.by
	let initials = $derived.by(() => {
		return `${firstName[0]}${lastName[0]}`
	})
</script>

As derivações funcionam muito bem durante o SSR porque são computações puras sem efeitos colaterais. O servidor avalia a expressão de derivação usando os valores de estado atuais e renderiza o resultado. O cliente reavalia durante a hidratação e (assumindo as mesmas entradas) produz o mesmo resultado.

A armadilha com as derivações ocorre quando elas dependem de estado que difere entre servidor e cliente. Considere este exemplo:

<script>
	import { browser } from '$app/environment'

	let screenWidth = $state(browser ? window.innerWidth : 1024)
	let isMobile = $derived(screenWidth < 768)
</script>

<nav class:mobile={isMobile}>
	<!-- Navigation content -->
</nav>

Durante o SSR, screenWidth é 1024 (nosso fallback), então isMobile é false. O servidor renderiza <nav> sem a classe mobile. Mas se o usuário tiver uma tela de celular de 600px de largura, a hidratação define screenWidth como 600, fazendo com que isMobile se torne true. O cliente espera <nav class="mobile">, mas o DOM tem <nav>. Incompatibilidade de hidratação!

A solução é garantir que as derivações produzam valores consistentes entre servidor e cliente durante a renderização inicial. Exploraremos padrões para isso nas seções posteriores.

Outra consideração é que as derivações não podem conter efeitos colaterais. O Svelte impõe isso — você não pode modificar o estado dentro de uma expressão $derived:

<script>
	let count = $state(0)
	let log = $state([])

	// ERROR: Cannot modify state inside $derived
	let doubled = $derived(() => {
		log.push(count) // This is forbidden!
		return count * 2
	})
</script>

Essa restrição existe porque as derivações podem ser avaliadas múltiplas vezes (para rastreamento de dependências) ou podem não ser avaliadas de forma alguma (se nada as ler). Efeitos colaterais dentro das derivações teriam comportamento imprevisível. Essa restrição se aplica igualmente durante o SSR e no navegador.

A Rune `$effect`: Seu Porto Seguro para Código do Navegador

A rune $effect cria efeitos colaterais que são executados em resposta a mudanças de estado. Ao contrário de $state e $derived, os efeitos são fundamentalmente exclusivos do cliente. Eles nunca são executados no servidor.

Esse comportamento é intencional e crucial para entender. Os efeitos são projetados para tarefas como:

Interagir com APIs do navegador (localStorage, medições do DOM, etc.)
Assinar fontes de dados externas
Realizar registro ou análises
Integrar com bibliotecas de terceiros que exigem contexto do navegador
Gerenciar temporizadores e intervalos
Lidar com foco e interações de teclado

Nada disso faz sentido em um contexto de servidor. O servidor não tem DOM para medir, nem localStorage para ler, nem navegador para interagir. Ao pular os efeitos durante o SSR, o Svelte mantém a renderização do servidor rápida e evita falhas por APIs do navegador ausentes.

<script>
	let mousePosition = $state({ x: 0, y: 0 })

	$effect(() => {
		// This entire block is ignored during SSR
		// It only runs after hydration in the browser

		function handleMouseMove(event) {
			mousePosition = { x: event.clientX, y: event.clientY }
		}

		window.addEventListener('mousemove', handleMouseMove)

		// Cleanup function runs when effect re-runs or component unmounts
		return () => {
			window.removeEventListener('mousemove', handleMouseMove)
		}
	})
</script>

<p>Mouse: ({mousePosition.x}, {mousePosition.y})</p>

O padrão mostrado acima é fundamental para interações com o navegador seguras para SSR. Observe que mousePosition tem um valor padrão seguro para SSR de { x: 0, y: 0 }. O servidor renderiza esse padrão. Após a hidratação, o efeito é executado e começa a atualizar mousePosition com as coordenadas reais do mouse.

Os efeitos também tratam as dependências reativas automaticamente. O Svelte rastreia quais valores de estado você lê dentro do efeito e re-executa o efeito quando esses valores mudam:

<script>
	let userId = $state(null)
	let userData = $state(null)

	$effect(() => {
		// This effect re-runs whenever userId changes
		if (!userId) {
			userData = null
			return
		}

		// Fetch user data from API
		fetch(`/api/users/${userId}`)
			.then((res) => res.json())
			.then((data) => {
				userData = data
			})
	})
</script>

Entender as dependências de efeitos é importante porque isso determina quando os efeitos são reexecutados. Valores lidos de forma síncrona dentro do corpo do efeito (antes de qualquer await ou dentro de setTimeout) tornam-se dependências. Valores lidos de forma assíncrona (após await ou dentro de callbacks) não se tornam dependências:

<script>
	let searchTerm = $state('')
	let results = $state([])
	let sortOrder = $state('asc')

	$effect(() => {
		// searchTerm is a dependency (read synchronously)
		const term = searchTerm

		if (!term) {
			results = []
			return
		}

		// Perform search
		fetch(`/api/search?q=${encodeURIComponent(term)}`)
			.then((res) => res.json())
			.then((data) => {
				// sortOrder is NOT a dependency (read asynchronously)
				// Changing sortOrder won't trigger a new search
				results = data.sort((a, b) => (sortOrder === 'asc' ? a.rank - b.rank : b.rank - a.rank))
			})
	})
</script>

Este rastreamento de dependências funciona da mesma forma após a hidratação como funcionaria em um componente somente para o cliente. A única diferença é que a execução inicial do efeito acontece após a hidratação em vez de após a inicialização do componente.

A Rune `$effect.pre`: Efeitos Colaterais Antes da Atualização do DOM

A rune $effect.pre é uma variante especializada que é executada antes das atualizações do DOM em vez de depois. Assim como os efeitos regulares, os pré-efeitos só são executados no cliente — nunca no servidor.

Os pré-efeitos resolvem um problema específico: às vezes você precisa medir ou salvar o estado do DOM antes de uma atualização, e então usar essa informação para realizar uma ação após a atualização. O exemplo clássico é manter a posição de rolagem em uma janela de chat:

<script>
	let messages = $state([])
	let containerRef = $state()
	let shouldAutoScroll = $state(true)

	$effect.pre(() => {
		// This runs BEFORE the DOM updates with new messages
		if (!containerRef) return

		// Check if user is scrolled to the bottom
		const { scrollTop, scrollHeight, clientHeight } = containerRef
		shouldAutoScroll = scrollHeight - scrollTop <= clientHeight + 50
	})

	$effect(() => {
		// This runs AFTER the DOM updates with new messages
		if (shouldAutoScroll && containerRef) {
			containerRef.scrollTop = containerRef.scrollHeight
		}
	})
</script>

O pré-efeito verifica se o usuário está no final do contêiner de rolagem antes de novas mensagens chegarem. Se estiver, definimos uma flag. O efeito regular então é executado após as atualizações do DOM (incluindo as novas mensagens) e rola até o final se a flag estiver definida.

Sem os pré-efeitos, você enfrentaria uma condição de corrida: no momento em que o efeito regular é executado, o DOM já foi atualizado, e você não consegue determinar se o usuário estava no final antes da atualização.

Como os pré-efeitos não são executados no servidor, quaisquer medições do DOM que eles realizam são adiadas com segurança para o cliente. O servidor renderiza com qualquer estado inicial que você fornecer, e a lógica do pré-efeito só entra em ação após a hidratação.

A Rune `$props`: Comunicação de Componentes Entre Fronteiras

As props funcionam de forma idêntica no servidor e no cliente — são simplesmente valores passados de componentes pais para filhos. No entanto, as props ainda podem causar problemas de SSR se os pais passarem valores diferentes em contextos diferentes:

<!-- Parent.svelte -->
<script>
	import { browser } from '$app/environment'
	import Child from './Child.svelte'

	// This prop value differs between server and client!
	let screenSize = browser ? (window.innerWidth > 768 ? 'desktop' : 'mobile') : 'unknown'
</script>

<Child {screenSize} />

<!-- Child.svelte -->
<script>
	let { screenSize } = $props()
</script>

<div class="layout" class:mobile={screenSize === 'mobile'}>
	<!-- Content -->
</div>

O pai passa screenSize = 'unknown' durante o SSR e screenSize = 'desktop' ou 'mobile' durante a hidratação. O filho renderiza nomes de classe diferentes, causando uma incompatibilidade de hidratação.

A solução é a mesma que com o estado: use padrões consistentes e atualize em efeitos:

<!-- Parent.svelte -->
<script>
	import Child from './Child.svelte'

	// Start with a safe default
	let screenSize = $state('desktop') // Reasonable assumption

	$effect(() => {
		// Update to actual value after hydration
		screenSize = window.innerWidth > 768 ? 'desktop' : 'mobile'

		// Keep it updated on resize
		function handleResize() {
			screenSize = window.innerWidth > 768 ? 'desktop' : 'mobile'
		}

		window.addEventListener('resize', handleResize)
		return () => window.removeEventListener('resize', handleResize)
	})
</script>

<Child {screenSize} />

Agora tanto o servidor quanto o cliente renderizam inicialmente com screenSize = 'desktop', evitando a incompatibilidade. Após a hidratação, o efeito atualiza para o tamanho de tela real.

Hooks de Ciclo de Vida: `onMount` e `onDestroy` no Contexto de SSR

Embora não sejam tecnicamente runes, os hooks de ciclo de vida merecem menção porque interagem com o SSR de maneiras específicas.

onMount só é executado no cliente, após a hidratação. Ele não é executado no servidor. Isso o torna outro porto seguro para código específico do navegador:

<script>
	import { onMount } from 'svelte'

	let chartRef = $state()

	onMount(() => {
		// Safe to use browser APIs here
		// This only runs after hydration
		const chart = new ChartLibrary(chartRef, {
			// chart configuration
		})

		// Return cleanup function
		return () => chart.destroy()
	})
</script>

<div bind:this={chartRef}></div>

A diferença entre onMount e $effect é sutil, mas importante. onMount é executado exatamente uma vez após a montagem do componente. $effect é executado após a montagem e novamente sempre que suas dependências mudam. Para código de inicialização que deve ser executado uma vez, qualquer um funciona. Para código que deve responder a mudanças de estado, use $effect.

onDestroy é executado em ambos os ambientes — no servidor após a renderização, e no cliente quando o componente é desmontado. Este é o único hook de ciclo de vida que é executado durante o SSR. Use-o para limpar quaisquer recursos alocados durante a execução síncrona do script:

<script>
	import { onDestroy } from 'svelte'

	// If you allocate resources synchronously during SSR...
	const subscription = someGlobalEventBus.subscribe(handleEvent)

	// ...you can clean them up with onDestroy
	onDestroy(() => {
		subscription.unsubscribe()
	})
</script>

Na prática, você raramente precisa de onDestroy para limpeza de SSR porque a maioria dos recursos (elementos do DOM, assinaturas de API do navegador, etc.) só são criados no cliente por meio de efeitos ou onMount.

O Problema de Incompatibilidade de Hidratação: Causas, Detecção e Soluções

As incompatibilidades de hidratação representam a categoria mais comum e frustrante de bugs de SSR. Vamos explorar este tópico a fundo, entendendo não apenas os sintomas, mas as causas subjacentes e as soluções sistemáticas.

O Que Exatamente É uma Incompatibilidade de Hidratação?

Quando o Svelte hidrata uma página, ele espera que o DOM existente corresponda ao que ele renderizaria dado o estado atual. O servidor renderizou o HTML com base no estado no momento da renderização. O cliente reconstrói o estado do componente durante a hidratação. Se esses estados diferirem, a saída renderizada difere, criando uma incompatibilidade.

O Svelte detecta incompatibilidades percorrendo o DOM durante a hidratação e comparando cada elemento com suas expectativas. Quando encontra uma diferença — conteúdo de texto errado, atributo ausente, elemento extra, classe incorreta — ele registra um aviso no modo de desenvolvimento.

Em produção, o Svelte tenta se recuperar graciosamente. Para incompatibilidades menores (conteúdo de texto errado), pode simplesmente atualizar o DOM para corresponder às expectativas do cliente. Para incompatibilidades estruturais (elementos diferentes ou filhos ausentes), a recuperação é mais complicada e pode resultar em manipuladores de eventos quebrados ou falhas visuais.

A natureza insidiosa das incompatibilidades de hidratação é que elas frequentemente parecem "funcionar" em produção. A página renderiza, o conteúdo parece correto, tudo parece bem. Mas bugs sutis espreitam: um manipulador de eventos anexado ao elemento errado, um estado de componente fora de sincronia com o estado do DOM, ou atributos de acessibilidade em um estado inconsistente.

Categoria 1: Incompatibilidades Baseadas em Tempo

O tempo representa uma diferença fundamental entre os ambientes de servidor e cliente. O servidor renderiza em um momento no tempo; o cliente hidrata em um momento posterior. Qualquer conteúdo que dependa do tempo atual pode gerar incompatibilidades.

Considere um componente que exibe tempos relativos como "5 minutos atrás" ou "ontem":

<script>
	let { timestamp } = $props()

	// PROBLEM: "now" is different on server vs client
	function getRelativeTime(ts) {
		const now = Date.now()
		const diff = now - ts

		if (diff < 60000) return 'just now'
		if (diff < 3600000) return `${Math.floor(diff / 60000)} minutes ago`
		if (diff < 86400000) return `${Math.floor(diff / 3600000)} hours ago`
		return 'yesterday'
	}

	let relativeTime = $derived(getRelativeTime(timestamp))
</script>

<span>{relativeTime}</span>

Se o servidor renderiza às 12:00:00 e o cliente hidrata às 12:00:05, um timestamp de 11:59:50 mostra "agora mesmo" no servidor mas "15 segundos atrás" (arredondando para "agora mesmo") no cliente — ou se o tempo cruzar um limite, "agora mesmo" vs "1 minuto atrás." Incompatibilidade!

Solução: Renderize uma representação estável no lado do servidor, aprimore no cliente:

<script>
	let { timestamp } = $props()

	// Start with a stable representation that won't mismatch
	// Use the absolute date/time, not relative
	let displayTime = $state(new Date(timestamp).toLocaleString())

	$effect(() => {
		// Update to relative time on the client
		function updateRelativeTime() {
			const now = Date.now()
			const diff = now - timestamp

			if (diff < 60000) {
				displayTime = 'just now'
			} else if (diff < 3600000) {
				displayTime = `${Math.floor(diff / 60000)} minutes ago`
			} else if (diff < 86400000) {
				displayTime = `${Math.floor(diff / 3600000)} hours ago`
			} else {
				displayTime = new Date(timestamp).toLocaleDateString()
			}
		}

		updateRelativeTime()

		// Update periodically for live updates
		const interval = setInterval(updateRelativeTime, 60000)
		return () => clearInterval(interval)
	})
</script>

<time datetime={new Date(timestamp).toISOString()}>
	{displayTime}
</time>

Essa abordagem mostra o timestamp absoluto durante o SSR (estável, determinístico), depois muda para o tempo relativo após a hidratação (dinâmico, amigável ao usuário).

Categoria 2: Aleatoriedade e Valores Não Determinísticos

Qualquer valor que difira entre computações causará incompatibilidades. O culpado mais óbvio é Math.random():

<script>
	// PROBLEM: Different random values on server vs client
	let backgroundColor = $state(`hsl(${Math.random() * 360}, 70%, 80%)`)
</script>

<div style="background-color: {backgroundColor}">Random colored box</div>

O servidor gera um matiz aleatório; o cliente gera um diferente. Incompatibilidade!

Solução 1: Passe valores aleatórios do servidor:

A solução mais robusta é gerar o valor aleatório na sua função load do servidor e passá-lo como uma prop. Isso garante que tanto a renderização do servidor quanto a hidratação do cliente usem exatamente o mesmo valor.

// +page.server.js
export function load() {
	return {
		randomHue: Math.random() * 360
	}
}

<!-- +page.svelte -->
<script>
	let { data } = $props()
	let backgroundColor = $derived(`hsl(${data.randomHue}, 70%, 80%)`)
</script>

<div style="background-color: {backgroundColor}">Consistently random colored box</div>

Solução 2: Renderização em duas passagens (O Padrão "Mount"):

Se você não puder passar dados do servidor (por exemplo, dentro de um componente reutilizável), use uma abordagem de duas passagens. Renderize um estado padrão neutro durante o SSR e aplique o valor aleatório somente após a montagem.

<script>
	import { onMount } from 'svelte'

	let hue = $state(0) // Default neutral value
	let initialized = $state(false)

	onMount(() => {
		hue = Math.random() * 360
		initialized = true
	})
</script>

<div
	style="background-color: hsl({hue}, 70%, 80%); transition: background-color 0.3s;"
	style:opacity={initialized ? 1 : 0.5}
>
	Random colored box
</div>

Isso evita a incompatibilidade porque o servidor e a renderização inicial do cliente usam hue = 0. A atualização acontece imediatamente após a montagem.

Solução 3: Geração de ID estável:

Para gerar IDs únicos (por exemplo, para atributos de acessibilidade), o Svelte 5 ainda não tem um hook useId embutido como o React, mas você pode usar um contador global ou crypto.randomUUID() de forma de duas passagens. No entanto, a melhor prática para IDs de acessibilidade geralmente é deixar o consumidor passar um ID ou usar uma biblioteca que lide com a geração de IDs estáveis.

Categoria 3: Detecção de Capacidades do Navegador

Navegadores diferentes suportam recursos diferentes. Código que renderiza de forma diferente com base nas capacidades do navegador causa incompatibilidades:

<script>
	import { browser } from '$app/environment'

	// PROBLEM: Server doesn't know browser capabilities
	let supportsWebP = $state(false)

	if (browser) {
		const canvas = document.createElement('canvas')
		supportsWebP = canvas.toDataURL('image/webp').startsWith('data:image/webp')
	}
</script>

{#if supportsWebP}
	<img src="/image.webp" alt="..." />
{:else}
	<img src="/image.jpg" alt="..." />
{/if}

O servidor sempre renderiza o fallback JPEG. Se o navegador suportar WebP, ele espera a imagem WebP durante a hidratação. Incompatibilidade!

Solução: Mostre um estado inicial consistente, detecte capacidades no efeito:

<script>
	// null = "still detecting"
	let supportsWebP = $state(null)

	$effect(() => {
		const canvas = document.createElement('canvas')
		supportsWebP = canvas.toDataURL('image/webp').startsWith('data:image/webp')
	})
</script>

<!-- While detecting, show JPEG (consistent with SSR) -->
<!-- After detection, show appropriate format -->
<img src={supportsWebP === true ? '/image.webp' : '/image.jpg'} alt="..." />

Espere — isso ainda causa uma incompatibilidade! Após a hidratação, supportsWebP muda de null para true, alterando o atributo src.

Solução melhor: Use o elemento <picture> com o tratamento nativo do navegador:

<picture>
	<source srcset="/image.webp" type="image/webp" />
	<source srcset="/image.jpg" type="image/jpeg" />
	<img src="/image.jpg" alt="..." />
</picture>

O elemento <picture> deixa o navegador escolher o formato apropriado sem JavaScript. O HTML é idêntico no servidor e no cliente, e o navegador seleciona automaticamente o WebP se for suportado.

Categoria 4: Diferenças de Localidade e Internacionalização

As configurações de localidade do servidor frequentemente diferem das do navegador do usuário, fazendo com que os valores formatados não correspondam:

<script>
	let price = $state(1234.56)

	// PROBLEM: Server locale might be en-US, user locale might be de-DE
	// en-US: "$1,234.56"
	// de-DE: "1.234,56 $"
	let formattedPrice = $derived(
		price.toLocaleString(undefined, {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

<span class="price">{formattedPrice}</span>

Usar undefined para a localidade significa "usar a localidade padrão do ambiente." O servidor tem um padrão; o navegador do usuário tem outro. Incompatibilidade!

Solução 1: Force uma localidade consistente:

<script>
	let price = $state(1234.56)

	// Always use the same locale
	let formattedPrice = $derived(
		price.toLocaleString('en-US', {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

Solução 2: Detectar locale no lado do cliente e atualizar:

<script>
	let price = $state(1234.56)
	let userLocale = $state('en-US') // Safe default

	$effect(() => {
		userLocale = navigator.language
	})

	let formattedPrice = $derived(
		price.toLocaleString(userLocale, {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

Isso causa um flash — o formato renderizado pelo servidor aparece brevemente antes que o formato do cliente tome conta. Para preços, isso pode ser aceitável. Para elementos críticos da UI, a Solução 1 (locale consistente) costuma ser melhor.

Solução 3: Passar o locale a partir do servidor:

Se você conhece o locale do usuário no lado do servidor (via cookies, headers ou preferências do usuário), passe-o pelas funções load:

// +page.server.js
export function load({ request }) {
	const acceptLanguage = request.headers.get('accept-language')
	const locale = parseAcceptLanguage(acceptLanguage) || 'en-US'

	return { locale }
}

<!-- +page.svelte -->
<script>
	let { data } = $props()

	let price = $state(1234.56)
	let formattedPrice = $derived(
		price.toLocaleString(data.locale, {
			style: 'currency',
			currency: 'USD'
		})
	)
</script>

Agora servidor e cliente usam o mesmo locale, eliminando a incompatibilidade.

Categoria 5: Diferenças de Viewport e Dispositivo

O servidor não possui viewport. Ele não consegue saber o tamanho da tela do usuário, a densidade de pixels ou a orientação do dispositivo. O código que renderiza com base nesses fatores gera incompatibilidades:

<script>
	import { browser } from '$app/environment'

	// PROBLEM: Server can't measure the viewport
	let columns = $state(browser ? (window.innerWidth > 1200 ? 4 : 2) : 3)
</script>

<div class="grid" style="--columns: {columns}">
	<!-- Grid items -->
</div>

O servidor escolhe 3 colunas como estimativa. O cliente pode calcular 4 colunas com base no viewport real. Incompatibilidade!

Solução: Use CSS para layouts responsivos, não JavaScript:

<div class="grid">
	<!-- Grid items -->
</div>

<style>
	.grid {
		display: grid;
		grid-template-columns: repeat(2, 1fr);
	}

	@media (min-width: 768px) {
		.grid {
			grid-template-columns: repeat(3, 1fr);
		}
	}

	@media (min-width: 1200px) {
		.grid {
			grid-template-columns: repeat(4, 1fr);
		}
	}
</style>

Media queries CSS lidam com layouts responsivos sem nenhum JavaScript. O HTML é idêntico no servidor e no cliente; o navegador aplica os estilos adequados com base no tamanho do viewport.

Quando você absolutamente precisar usar JavaScript para layout (talvez para lógica mais complexa), aceite que servidor e cliente podem diferir e gerencie a transição de forma elegante:

<script>
	import { innerWidth } from 'svelte/reactivity/window'

	// innerWidth.current is undefined during SSR
	// Provide a reasonable desktop default
	let columns = $derived(
		(innerWidth.current ?? 1200) > 1200 ? 4 : (innerWidth.current ?? 1200) > 768 ? 3 : 2
	)
</script>

<div class="grid" style="--columns: {columns}">
	<!-- Grid items -->
</div>

Aqui, assumimos por padrão um viewport de desktop (1200px+) durante o SSR, o que resulta em 4 colunas. Em dispositivos móveis, há um breve flash enquanto o grid se ajusta após a hidratação. Isso geralmente é aceitável porque o layout está próximo do correto e o ajuste é pequeno.

Padrões para Acesso Seguro a APIs do Navegador

Já estabelecemos que as APIs do navegador não existem no servidor e devem ser acessadas com cuidado. Vamos desenvolver um conjunto abrangente de padrões para cenários comuns.

Padrão 1: O Wrapper de Effect

O padrão mais fundamental envolve todo acesso a APIs do navegador dentro de $effect:

<script>
	let scrollPosition = $state(0)
	let viewportHeight = $state(800) // Reasonable default

	$effect(() => {
		// All browser API access happens here
		viewportHeight = window.innerHeight

		function handleScroll() {
			scrollPosition = window.scrollY
		}

		function handleResize() {
			viewportHeight = window.innerHeight
		}

		window.addEventListener('scroll', handleScroll)
		window.addEventListener('resize', handleResize)

		// Initial values
		handleScroll()
		handleResize()

		return () => {
			window.removeEventListener('scroll', handleScroll)
			window.removeEventListener('resize', handleResize)
		}
	})

	let scrollProgress = $derived(scrollPosition / (document.body.scrollHeight - viewportHeight))
</script>

Espera — há um bug acima! O $derived referencia document.body.scrollHeight, que não existe no servidor. Vamos corrigi-lo:

<script>
	let scrollPosition = $state(0)
	let viewportHeight = $state(800)
	let documentHeight = $state(2000) // Reasonable default

	$effect(() => {
		viewportHeight = window.innerHeight
		documentHeight = document.body.scrollHeight

		function handleScroll() {
			scrollPosition = window.scrollY
			documentHeight = document.body.scrollHeight
		}

		function handleResize() {
			viewportHeight = window.innerHeight
			documentHeight = document.body.scrollHeight
		}

		window.addEventListener('scroll', handleScroll)
		window.addEventListener('resize', handleResize)

		handleScroll()
		handleResize()

		return () => {
			window.removeEventListener('scroll', handleScroll)
			window.removeEventListener('resize', handleResize)
		}
	})

	// Now all values in the derivation are safe
	let scrollProgress = $derived(
		documentHeight <= viewportHeight ? 0 : scrollPosition / (documentHeight - viewportHeight)
	)
</script>

<div class="progress-bar" style="width: {scrollProgress * 100}%"></div>

Padrão 2: Carregamento Lazy de Módulos do Navegador

Algumas bibliotecas funcionam apenas no navegador. Em vez de importá-las normalmente (o que falharia durante o SSR), carregue-as dinamicamente:

<script>
	let chartContainer = $state()
	let chartInstance = $state(null)

	$effect(() => {
		if (!chartContainer) return

		// Dynamic import only happens on the client
		import('chart.js').then(({ Chart }) => {
			chartInstance = new Chart(chartContainer, {
				type: 'bar',
				data: chartData,
				options: chartOptions
			})
		})

		return () => {
			if (chartInstance) {
				chartInstance.destroy()
			}
		}
	})
</script>

<canvas bind:this={chartContainer}></canvas>

O import() dinâmico dentro de $effect é seguro porque os effects não são executados no servidor. O módulo é carregado apenas no navegador.

Padrão 3: O Guard do Navegador com Fallback

Às vezes você quer usar um valor de uma API do navegador, mas precisa de um fallback razoável para o SSR:

<script>
	import { browser } from '$app/environment'

	// Determine color scheme with SSR-safe fallback
	let prefersDarkMode = $state(false)

	// This runs during SSR (browser is false) and during hydration (browser is true)
	// But the value only updates meaningfully after the effect runs

	$effect(() => {
		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
		prefersDarkMode = mediaQuery.matches

		function handleChange(e) {
			prefersDarkMode = e.matches
		}

		mediaQuery.addEventListener('change', handleChange)
		return () => mediaQuery.removeEventListener('change', handleChange)
	})
</script>

<div class:dark-mode={prefersDarkMode}>
	<!-- Content -->
</div>

Padrão 4: Usando Bindings do `svelte:window`

O Svelte fornece uma maneira declarativa de ouvir eventos de window e fazer bind com propriedades de window usando o elemento <svelte:window>. Isso costuma ser mais limpo do que adicionar manualmente ouvintes de eventos em effects.

<script>
	let innerWidth = $state(0)
	let innerHeight = $state(0)
	let scrollY = $state(0)
	let online = $state(true)

	// Use safe defaults for derived values
	// During SSR, innerWidth will be 0 (or whatever you initialize it to)
	let isMobile = $derived(innerWidth > 0 && innerWidth < 768)
</script>

<svelte:window bind:innerWidth bind:innerHeight bind:scrollY bind:online />

<header class:mobile={isMobile} class:scrolled={scrollY > 50}>
	{#if !online}
		<div class="offline-banner">You are offline</div>
	{/if}
	<!-- Header content -->
</header>

Note que durante o SSR, os bindings não são executados, portanto suas variáveis de estado mantêm seus valores iniciais. Isso significa que innerWidth será 0 (ou o que você definir) no servidor. Certifique-se de que sua UI lide com isso de forma elegante, talvez assumindo por padrão um layout de desktop ou um estado de carregamento para evitar mudanças de layout, se possível, ou aceitando que o layout pode se ajustar após a hidratação.

Padrão 5: APIs de Storage (localStorage, sessionStorage)

As APIs de storage são exclusivas do navegador e requerem tratamento cuidadoso:

<script>
	// Initial value used for SSR
	let theme = $state('light')

	$effect(() => {
		// Read from storage on mount
		const stored = localStorage.getItem('theme')
		if (stored) {
			theme = stored
		}
	})

	// Separate effect to write changes
	$effect(() => {
		// This effect depends on `theme`
		// It runs whenever theme changes (after the first effect sets it)
		localStorage.setItem('theme', theme)
	})

	function toggleTheme() {
		theme = theme === 'light' ? 'dark' : 'light'
	}
</script>

<button onclick={toggleTheme}>
	Current theme: {theme}
</button>

Há um problema sutil aqui: o segundo effect é executado imediatamente após o primeiro, gravando o valor inicial no storage antes mesmo de termos lido do storage. Vamos corrigir isso:

<script>
	let theme = $state('light')
	let initialized = $state(false)

	$effect(() => {
		// Read from storage
		const stored = localStorage.getItem('theme')
		if (stored) {
			theme = stored
		}
		initialized = true
	})

	$effect(() => {
		// Only write after initialization
		if (!initialized) return
		localStorage.setItem('theme', theme)
	})
</script>

Ou de forma mais elegante, combine leitura e escrita em um único effect que rastreia as mudanças:

<script>
	let theme = $state('light')

	$effect(() => {
		// Read initial value
		const stored = localStorage.getItem('theme')
		if (stored && stored !== theme) {
			theme = stored
		}

		// Track future changes
		return () => {
			localStorage.setItem('theme', theme)
		}
	})
</script>

Hmm, isso ainda tem problemas com a função de cleanup capturando valores desatualizados. Aqui está uma abordagem mais limpa usando dois effects com uma flag:

<script>
	let theme = $state('light')
	let hasLoadedFromStorage = false

	$effect(() => {
		// First run: load from storage
		if (!hasLoadedFromStorage) {
			const stored = localStorage.getItem('theme')
			if (stored) {
				theme = stored
			}
			hasLoadedFromStorage = true
			return
		}

		// Subsequent runs: save to storage
		localStorage.setItem('theme', theme)
	})
</script>

Na verdade, o padrão mais limpo usa untrack para evitar que a leitura do valor inicial acione um salvamento:

<script>
	import { untrack } from 'svelte'

	let theme = $state('light')

	// Load from storage once
	$effect(() => {
		const stored = localStorage.getItem('theme')
		if (stored) {
			theme = stored
		}
	})

	// Save to storage on changes
	$effect(() => {
		const currentTheme = theme // Read theme (creates dependency)

		// Avoid saving on first run
		untrack(() => {
			// Small delay to ensure we don't save the initial value
			const timeout = setTimeout(() => {
				localStorage.setItem('theme', currentTheme)
			}, 0)

			return () => clearTimeout(timeout)
		})
	})
</script>

Isso está ficando complicado! Para código em produção, considere extrair isso em um utilitário reutilizável:

// lib/persisted.svelte.js
export function createPersistedState(key, initialValue) {
	let value = $state(initialValue)
	let loaded = false

	$effect(() => {
		if (!loaded) {
			const stored = localStorage.getItem(key)
			if (stored !== null) {
				try {
					value = JSON.parse(stored)
				} catch {
					value = stored
				}
			}
			loaded = true
		} else {
			localStorage.setItem(key, JSON.stringify(value))
		}
	})

	return {
		get value() {
			return value
		},
		set value(v) {
			value = v
		}
	}
}

<script>
	import { createPersistedState } from '$lib/persisted.svelte.js'

	const theme = createPersistedState('theme', 'light')
</script>

<button onclick={() => (theme.value = theme.value === 'light' ? 'dark' : 'light')}>
	Theme: {theme.value}
</button>

Padrão 6: Canvas e WebGL

Operações com Canvas requerem acesso ao DOM e devem ser totalmente adiadas:

<script>
	let canvasRef = $state()
	let animationFrame = $state(null)

	$effect(() => {
		if (!canvasRef) return

		const ctx = canvasRef.getContext('2d')
		if (!ctx) return

		// Animation loop
		function draw(timestamp) {
			ctx.clearRect(0, 0, canvasRef.width, canvasRef.height)

			// Draw your scene
			const x = (timestamp / 10) % canvasRef.width
			ctx.fillStyle = 'blue'
			ctx.fillRect(x, 50, 50, 50)

			animationFrame = requestAnimationFrame(draw)
		}

		animationFrame = requestAnimationFrame(draw)

		return () => {
			if (animationFrame) {
				cancelAnimationFrame(animationFrame)
			}
		}
	})
</script>

<canvas bind:this={canvasRef} width="400" height="200">
	<!-- Fallback content for SSR and non-canvas browsers -->
	<p>Animated canvas demonstration</p>
</canvas>

O elemento <canvas> é renderizado durante o SSR com seu conteúdo de fallback. Após a hidratação, o effect assume o controle e começa a desenhar.

Padrão 7: Intersection Observer para Carregamento Lazy

O Intersection Observer é comumente usado para carregamento lazy, scroll infinito e animações acionadas pelo scroll:

<script>
	let { src, alt } = $props()

	let imgRef = $state()
	let isVisible = $state(false)
	let hasLoaded = $state(false)

	$effect(() => {
		if (!imgRef) return

		const observer = new IntersectionObserver(
			(entries) => {
				entries.forEach((entry) => {
					if (entry.isIntersecting) {
						isVisible = true
						observer.disconnect() // Only need to load once
					}
				})
			},
			{
				rootMargin: '100px', // Start loading 100px before visible
				threshold: 0
			}
		)

		observer.observe(imgRef)

		return () => observer.disconnect()
	})
</script>

<div class="image-container" bind:this={imgRef}>
	{#if isVisible}
		<img {src} {alt} onload={() => (hasLoaded = true)} class:loaded={hasLoaded} />
	{:else}
		<!-- Placeholder shown during SSR and before intersection -->
		<div class="placeholder" aria-hidden="true"></div>
	{/if}
</div>

<style>
	.image-container {
		min-height: 200px; /* Prevent layout shift */
	}

	img {
		opacity: 0;
		transition: opacity 0.3s;
	}

	img.loaded {
		opacity: 1;
	}

	.placeholder {
		background: #e0e0e0;
		height: 200px;
	}
</style>

Controlando o SSR no Nível da Página

O SvelteKit fornece opções de página para controlar o comportamento do SSR em páginas específicas. Entender essas opções ajuda você a tomar decisões informadas sobre onde aplicar o SSR.

A Opção `ssr`

Definir ssr = false desabilita a renderização no lado do servidor para uma página:

// +page.js
export const ssr = false

Com esta configuração, o servidor retorna um shell HTML mínimo sem conteúdo pré-renderizado. A página inteira é renderizada pelo JavaScript no navegador.

Quando usar ssr = false:

Páginas que fundamentalmente não podem funcionar sem APIs do navegador (ex.: um jogo baseado em WebGL)
Painéis administrativos protegidos por autenticação onde SEO não importa
Páginas com interações complexas somente no cliente onde o SSR não agrega valor

Contrapartidas:

Nenhum conteúdo até que o JavaScript carregue e execute (ruim para a percepção de desempenho)
Nenhum benefício de SEO — motores de busca veem uma página vazia
Usuários com JavaScript desabilitado não veem nada
Perda dos benefícios de aprimoramento progressivo e acessibilidade

Use esta opção com moderação. A maioria das páginas se beneficia do SSR, e os padrões que discutimos permitem lidar com recursos exclusivos do navegador mantendo o SSR habilitado.

A Opção `csr`

Definir csr = false desabilita a renderização no lado do cliente (hidratação):

// +page.js
export const csr = false

A página é renderizada no servidor e enviada como HTML estático. Nenhum JavaScript é enviado; nenhuma hidratação ocorre.

Quando usar csr = false:

Páginas de conteúdo puramente estático (sobre, termos de serviço, política de privacidade)
Posts de blog e artigos que não precisam de interatividade
Páginas onde minimizar o JavaScript é crítico

Contrapartidas:

Sem interatividade — botões não funcionam, formulários são enviados de forma tradicional, nenhum JavaScript
Sem navegação no lado do cliente — cada link causa um recarregamento completo da página
Pode melhorar drasticamente o desempenho para páginas adequadas

A Opção `prerender`

A pré-renderização gera HTML no momento da build em vez de no momento da requisição:

// +page.js
export const prerender = true

Durante o npm run build, o SvelteKit percorre seu site, renderiza as páginas pré-renderizáveis e as salva como arquivos HTML estáticos.

Quando usar prerender = true:

Páginas com conteúdo que não muda por requisição (posts de blog, documentação)
Páginas de marketing que são iguais para todos os usuários
Qualquer página que possa ser armazenada em cache e servida como arquivos estáticos

Contrapartidas:

O conteúdo é fixado no momento da build — conteúdo dinâmico exige rebuilds
Não é possível usar cookies, cabeçalhos ou dados específicos da requisição durante a pré-renderização
Ainda hidrata no cliente, a menos que csr = false também seja definido

Você pode combinar essas opções para um controle refinado:

// A truly static page: no JavaScript, pre-built at compile time
export const prerender = true
export const csr = false

// A fully dynamic page: no SSR, entirely client-rendered
export const ssr = false
// (csr is true by default)

Padrões e Técnicas Avançadas de SSR

Vamos explorar alguns padrões sofisticados para lidar com cenários complexos de SSR.

Carregamento Condicional de Componentes

Alguns componentes simplesmente não podem funcionar durante o SSR — dependem demais de APIs do navegador, bibliotecas de terceiros ou condições específicas de runtime. Você pode pular completamente a renderização deles durante o SSR:

<script>
	import { browser } from '$app/environment'
	import HeavyBrowserComponent from './HeavyBrowserComponent.svelte'
</script>

{#if browser}
	<HeavyBrowserComponent />
{:else}
	<div class="placeholder" aria-label="Loading interactive feature">
		<p>Interactive feature loading...</p>
	</div>
{/if}

O servidor renderiza o placeholder. O cliente o substitui pelo componente real após a hidratação. Isso não é uma incompatibilidade porque o Svelte sabe que browser muda entre servidor e cliente.

Para um desempenho ainda melhor, use importações dinâmicas para evitar baixar código exclusivo do navegador no servidor:

<script>
	import { browser } from '$app/environment'

	let HeavyComponent = $state(null)

	if (browser) {
		import('./HeavyBrowserComponent.svelte').then((module) => {
			HeavyComponent = module.default
		})
	}
</script>

{#if HeavyComponent}
	<svelte:component this={HeavyComponent} />
{:else}
	<div class="placeholder">Loading...</div>
{/if}

Na verdade, com o Svelte 5 podemos usar o componente diretamente:

<script>
	import { browser } from '$app/environment'

	let Component = $state(null)

	$effect(() => {
		import('./HeavyBrowserComponent.svelte').then((module) => {
			Component = module.default
		})
	})
</script>

{#if Component}
	<Component />
{:else}
	<div class="placeholder">Loading...</div>
{/if}

Transferência de Estado Servidor-Cliente

Às vezes você precisa passar valores computados do servidor para o cliente sem recomputação. A forma padrão do SvelteKit para fazer isso é via props data.

// +page.server.js
export async function load({ fetch }) {
	const rawData = await fetchLargeDataset()
	const processedData = expensiveTransformation(rawData)

	return {
		processedData
	}
}

<!-- +page.svelte -->
<script>
	let { data } = $props()
</script>

<DataVisualization data={data.processedData} />

O servidor executa expensiveTransformation, serializa o resultado nos dados da página e o cliente o recebe pronto para uso. Isso evita executar lógica custosa no cliente e garante consistência.

Este padrão é particularmente valioso para:

Saídas de modelos de machine learning
Cálculos ou agregações complexas
Dados que requerem autenticação no servidor para buscar
Qualquer coisa custosa que não deva ser executada duas vezes

Gerenciamento do Estado de Autenticação

A autenticação geralmente vive em cookies (acessíveis durante o SSR), mas precisa de tratamento no lado do cliente para renovação de token, logout etc.:

<!-- +layout.svelte -->
<script>
	import { page } from '$app/state'

	// User data from server-side load function
	let user = $derived(page.data.user)

	// Client-side session management
	let sessionExpiresAt = $state(null)
	let isRefreshing = $state(false)

	$effect(() => {
		if (!user) return

		// Parse session expiry from JWT or stored value
		const token = document.cookie
			.split('; ')
			.find((row) => row.startsWith('session='))
			?.split('=')[1]

		if (token) {
			try {
				const payload = JSON.parse(atob(token.split('.')[1]))
				sessionExpiresAt = new Date(payload.exp * 1000)
			} catch {
				// Invalid token format
			}
		}

		// Set up automatic refresh before expiry
		function checkAndRefresh() {
			if (!sessionExpiresAt) return

			const timeUntilExpiry = sessionExpiresAt.getTime() - Date.now()

			if (timeUntilExpiry < 60000 && !isRefreshing) {
				isRefreshing = true

				fetch('/api/auth/refresh', { method: 'POST' })
					.then((res) => res.json())
					.then((data) => {
						sessionExpiresAt = new Date(data.expiresAt)
					})
					.finally(() => {
						isRefreshing = false
					})
			}
		}

		const interval = setInterval(checkAndRefresh, 30000)
		checkAndRefresh()

		return () => clearInterval(interval)
	})
</script>

<slot />

Componentes Portal

Portais renderizam conteúdo fora da hierarquia DOM do componente, tipicamente para modais, tooltips ou dropdowns. Eles requerem manipulação do DOM:

<!-- Modal.svelte -->
<script>
	import { browser } from '$app/environment'

	let { open = $bindable(false), children } = $props()
	let portalTarget = $state(null)

	$effect(() => {
		// Create portal container
		const container = document.createElement('div')
		container.className = 'modal-portal'
		container.setAttribute('role', 'presentation')
		document.body.appendChild(container)
		portalTarget = container

		return () => {
			container.remove()
		}
	})

	$effect(() => {
		if (!browser) return

		if (open) {
			document.body.style.overflow = 'hidden'

			// Focus trap and escape key handling
			function handleKeydown(e) {
				if (e.key === 'Escape') {
					open = false
				}
			}

			document.addEventListener('keydown', handleKeydown)

			return () => {
				document.body.style.overflow = ''
				document.removeEventListener('keydown', handleKeydown)
			}
		}
	})
</script>

{#if open && portalTarget}
	<!-- Content rendered into portal via Svelte's own rendering -->
	<div class="modal-overlay" onclick={() => (open = false)}>
		<div class="modal-content" role="dialog" aria-modal="true" onclick={(e) => e.stopPropagation()}>
			{@render children()}
		</div>
	</div>
{/if}

O modal não é renderizado durante o SSR (sem portalTarget), o que é apropriado já que modais normalmente começam fechados.

Gerenciamento de Foco

O gerenciamento de foco é inteiramente no lado do cliente, mas importante para acessibilidade:

<script>
	let { isOpen = $bindable(false) } = $props()
	let closeButtonRef = $state()
	let previousActiveElement = $state(null)

	$effect(() => {
		if (isOpen) {
			// Save current focus
			previousActiveElement = document.activeElement

			// Focus the modal
			closeButtonRef?.focus()

			return () => {
				// Restore focus when closing
				previousActiveElement?.focus()
			}
		}
	})
</script>

{#if isOpen}
	<div class="modal">
		<button bind:this={closeButtonRef} onclick={() => (isOpen = false)}> Close </button>
		<!-- Modal content -->
	</div>
{/if}

Depurando Problemas de SSR

Quando ocorrem problemas de SSR, você precisa de abordagens sistemáticas de depuração.

Logging com Consciência do Ambiente

Adicione logging que distingue servidor de cliente:

<script>
	import { browser, dev } from '$app/environment'

	function log(message, ...args) {
		if (!dev) return // Only log in development

		const prefix = browser ? '🌐 [Browser]' : '🖥️ [Server]'
		const timestamp = new Date().toISOString().substr(11, 12)
		console.log(`${prefix} ${timestamp} ${message}`, ...args)
	}

	log('Component initializing')

	let count = $state(0)
	log('State initialized', { count })

	$effect(() => {
		log('Effect running')
	})
</script>

Detectando Incompatibilidades de Hidratação

O Svelte registra incompatibilidades de hidratação no console em desenvolvimento. Para torná-las mais evidentes:

// hooks.client.js
const originalWarn = console.warn
console.warn = (...args) => {
	if (args[0]?.includes?.('hydrat')) {
		console.error('🚨 HYDRATION MISMATCH:', ...args)
		// Optionally trigger a debugger breakpoint
		// debugger;
	}
	originalWarn.apply(console, args)
}

Mensagens de Erro Comuns Explicadas

"window is not defined" ou "document is not defined": Você está acessando globais do navegador durante o SSR. Mova o código para um $effect ou use uma guarda com if (browser).

"localStorage is not defined": Mesmo problema — localStorage é exclusivo do navegador. Use um effect para acessá-lo.

"Hydration completed but contains mismatches": O HTML renderizado no servidor não corresponde ao que o cliente esperava. Verifique valores dependentes de tempo, valores aleatórios, renderização específica do navegador ou diferenças de locale.

"Cannot read property 'X' of undefined": Ocorre frequentemente ao acessar elementos do DOM antes de estarem disponíveis. Certifique-se de que suas refs bind:this estejam preenchidas antes de usá-las.

Resumo de Boas Práticas

Vamos consolidar o que aprendemos em diretrizes práticas:

Sempre forneça valores padrão seguros para SSR. Cada parte do estado deve ter um padrão razoável que faça sentido no servidor. Não assuma que APIs do navegador existem durante a inicialização.

Use $effect como seu santuário de APIs do navegador. Qualquer código que requeira APIs do navegador pertence a um effect. Effects nunca são executados no servidor, tornando-os inerentemente seguros para código específico do navegador.

Adote svelte/reactivity/window para valores reativos da janela. Esses utilitários tratam o SSR automaticamente e fornecem atualizações reativas sem gerenciamento manual de event listeners.

Teste com JavaScript desabilitado. Seu HTML renderizado no servidor deve ser significativo e funcional. Se não for, você está perdendo os benefícios do SSR.

Seja deliberado sobre as expectativas de hidratação. Pergunte a si mesmo: "Isso será renderizado de forma idêntica no servidor e no cliente?" Se não, reestruture para garantir consistência ou aceite a transição.

Prefira CSS para layouts responsivos. Media queries não causam incompatibilidades de hidratação. Lógica responsiva baseada em JavaScript, sim.

Proteja conteúdo sensível ao tempo. Use representações estáveis durante o SSR e melhore com valores dinâmicos após a hidratação.

Tenha em mente as opções de página. ssr, csr e prerender oferecem controle refinado. Use-as deliberadamente com base nas necessidades de cada página.

Faça logging com consciência do ambiente. Ao depurar, saber se o código foi executado no servidor ou no cliente é inestimável.

Conclusão

A renderização no lado do servidor com o sistema de runes do Svelte 5 requer uma mudança fundamental de pensamento. Você não está mais escrevendo código que roda em um único ambiente; está escrevendo código que deve funcionar corretamente em dois contextos fundamentalmente diferentes, em dois momentos diferentes, com dois conjuntos diferentes de APIs disponíveis.

O insight principal é que os problemas de SSR não são misteriosos ou imprevisíveis quando você entende a mecânica subjacente. O servidor renderiza de forma síncrona, produz HTML e descarta o estado. O cliente hidrata, esperando que o DOM corresponda às suas expectativas. Effects só rodam no cliente. APIs do navegador só existem no cliente. Armado com esse entendimento, você pode antecipar problemas antes que ocorram e projetar componentes que funcionem corretamente desde o início.

Os padrões que exploramos — acesso a APIs do navegador baseado em effect, valores padrão seguros para SSR, hydratable para valores sincronizados, design responsivo baseado em CSS — não são convenções arbitrárias. São consequências lógicas da natureza fundamental do SSR. Quando você entende por que esses padrões funcionam, pode adaptá-los a situações novas e depurar problemas com eficácia.

A renderização no lado do servidor não é apenas uma otimização de desempenho ou técnica de SEO. É um compromisso de construir aplicações resilientes que funcionam para todos: conexões rápidas e lentas, dispositivos poderosos e fracos, JavaScript habilitado e desabilitado, motores de busca e leitores de tela. A complexidade que navegamos é o preço dessa resiliência, e é um preço que vale a pena pagar.

Suas aplicações Svelte 5 agora podem transitar com confiança pela fronteira servidor-cliente, entregando carregamentos iniciais rápidos enquanto habilitam interatividade rica. Os problemas conhecidos estão mapeados, os padrões estão estabelecidos e você tem o modelo mental para lidar com quaisquer desafios que surjam. Construa com confiança.

Armadilhas da Renderização no Lado do Servidor com Runes no Svelte 5

O Paradigma de Aplicação Universal

Compreendendo a Natureza Fundamental das Aplicações Universais

Por Que Essa Arquitetura Existe?

Os Dois Ambientes: Uma Comparação Detalhada

A Linha do Tempo do SSR: Uma Análise Momento a Momento

Fase 1: O Servidor Recebe uma Requisição

Fase 2: Execução do Componente no Servidor

Fase 3: Entrega do HTML ao Navegador

Fase 4: Carregamento e Análise do JavaScript

Fase 5: Hidratação

Fase 6: Navegação do Lado do Cliente

Análise Detalhada: Como Cada Rune se Comporta Durante o SSR

A Rune $state: Inicialização do Estado Reativo

A Rune $derived: Valores Computados e Suas Dependências

A Rune $effect: Seu Porto Seguro para Código do Navegador

A Rune $effect.pre: Efeitos Colaterais Antes da Atualização do DOM

A Rune $props: Comunicação de Componentes Entre Fronteiras

Hooks de Ciclo de Vida: onMount e onDestroy no Contexto de SSR

O Problema de Incompatibilidade de Hidratação: Causas, Detecção e Soluções

O Que Exatamente É uma Incompatibilidade de Hidratação?

Categoria 1: Incompatibilidades Baseadas em Tempo

Categoria 2: Aleatoriedade e Valores Não Determinísticos

Categoria 3: Detecção de Capacidades do Navegador

Categoria 4: Diferenças de Localidade e Internacionalização

Categoria 5: Diferenças de Viewport e Dispositivo

Padrões para Acesso Seguro a APIs do Navegador

Padrão 1: O Wrapper de Effect

Padrão 2: Carregamento Lazy de Módulos do Navegador

Padrão 3: O Guard do Navegador com Fallback

Padrão 4: Usando Bindings do svelte:window

Padrão 5: APIs de Storage (localStorage, sessionStorage)

Padrão 6: Canvas e WebGL

Padrão 7: Intersection Observer para Carregamento Lazy

Controlando o SSR no Nível da Página

A Opção ssr

A Opção csr

A Opção prerender

Padrões e Técnicas Avançadas de SSR

Carregamento Condicional de Componentes

Transferência de Estado Servidor-Cliente

Gerenciamento do Estado de Autenticação

Componentes Portal

Gerenciamento de Foco

Depurando Problemas de SSR

Logging com Consciência do Ambiente

Detectando Incompatibilidades de Hidratação

Mensagens de Erro Comuns Explicadas

Resumo de Boas Práticas

Conclusão

A Rune `$state`: Inicialização do Estado Reativo

A Rune `$derived`: Valores Computados e Suas Dependências

A Rune `$effect`: Seu Porto Seguro para Código do Navegador

A Rune `$effect.pre`: Efeitos Colaterais Antes da Atualização do DOM

A Rune `$props`: Comunicação de Componentes Entre Fronteiras

Hooks de Ciclo de Vida: `onMount` e `onDestroy` no Contexto de SSR

Padrão 4: Usando Bindings do `svelte:window`

A Opção `ssr`

A Opção `csr`

A Opção `prerender`