Armadilhas de Server-Side Rendering com Runes no Svelte 5

O Paradigma da Aplicação Universal

O server-side rendering representa uma mudança de paradigma na forma como pensamos sobre a arquitetura de aplicações web. Ao contrário dos primeiros dias das single-page applications, onde o JavaScript era o único responsável por renderizar o conteúdo no navegador, frameworks modernos como o SvelteKit adotam uma abordagem "universal", na qual o código da aplicação é executado em múltiplos ambientes. Essa decisão arquitetural traz benefícios enormes — carregamentos iniciais mais rápidos, SEO aprimorado, melhor acessibilidade e degradação graciosa quando o JavaScript falha — mas também introduz uma categoria de desafios que muitos desenvolvedores acham confusos e frustrantes.

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 oferecem 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 o server-side rendering 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 travamentos 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 entre ambientes, por que certos padrões causam problemas e como pensar sobre o design de componentes de uma forma que evite naturalmente as armadilhas do SSR. Ao final desta análise aprofundada, você terá não apenas soluções para problemas comuns, mas o framework conceitual para raciocinar sobre novas situações que encontrar.

Entendendo a Natureza Fundamental das Aplicações Universais

Para realmente compreender as armadilhas do SSR, devemos primeiro entender 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 o Cloudflare Workers) e o navegador. Esses ambientes compartilham o JavaScript como linguagem, mas diferem drasticamente 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. Seu navegador envia uma requisição HTTP para o 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 client-side, 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 executa de fato 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 o markup resultante em uma string HTML. Esse HTML é enviado ao navegador, onde o usuário vê imediatamente um conteúdo significativo.

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

Essa execução dupla é a fonte de cada armadilha de 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. Entender 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 solicita uma página, ele quer ver o conteúdo o mais rápido possível. Com a renderização client-side, o navegador precisa baixar o shell HTML, depois baixar o bundle JavaScript, depois 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 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 dispositivos menos potentes.

A otimização para mecanismos de busca fornece outra razão 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 nos resultados de busca.

Acessibilidade e progressive enhancement se beneficiam significativamente do SSR. Usuários que navegam com JavaScript desativado (seja por escolha ou devido a firewalls corporativos) ainda podem acessar seu conteúdo. Os leitores de tela recebem o markup completo imediatamente, em vez de aguardar a 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 seu site no Twitter ou Facebook, essas plataformas buscam o HTML e extraem metadados. Elas não executam JavaScript, então 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. Entender 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 de 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 há objeto window, nem document, nem localStorage, nem navigator, nem IntersectionObserver, nem ResizeObserver. O servidor não conhece o tamanho de 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, ele executa seu código de forma síncrona, produz HTML e descarta todo o estado. Não há um processo contínuo observando mudanças. O servidor renderiza uma vez e segue em frente. Se 1000 usuários solicitarem 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 funciona em um sandbox com restrições de segurança. O navegador não pode acessar o sistema de arquivos, executar comandos shell ou conectar-se a bancos de dados diretamente. Ele é executado em um event loop 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 effects 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.

O insight crucial é que os ambientes de servidor e de navegador compartilham quase nada, exceto a própria linguagem JavaScript. Quando você escreve código que assume que APIs do navegador existem, esse código travará 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. O SSR bem-sucedido exige escrever código que funcione corretamente em ambos os ambientes — ou lidar explicitamente com 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 rastrear 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. Seu navegador envia uma requisição para o servidor. O código server-side do SvelteKit recebe essa requisição e começa a processá-la.

Durante essa fase, o SvelteKit executa suas funções load em +page.server.js e +page.js (se existirem). Essas funções podem acessar recursos server-side como bancos de dados, fazer chamadas de API autenticadas e preparar dados para seus componentes. Os dados retornados pelas funções load ficam disponíveis como props para seus componentes de página.

É também quando os cookies são lidos, as sessões de usuário são validadas e qualquer lógica server-side é executada. Crucialmente, isso acontece antes que qualquer código de componente seja executado. No momento em que seus componentes Svelte são executados, as funções load já foram concluídas.

Fase 2: Execução de Componentes no Servidor

Com os dados carregados, o SvelteKit começa a renderizar sua árvore de componentes. Começando pelo layout raiz e descendo pelos layouts aninhados até o componente da sua 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 torna-se o valor do estado. Se você escrever let count = $state(0), a variável count terá o valor 0. Quaisquer modificações síncronas subsequentes a esse estado são capturadas — se você escrever imediatamente count = 10, o estado torna-se 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 torna-se 20.

Os blocos $effect são completamente ignorados. Esta é talvez a regra mais importante a ser internalizada. Os effects não são executados no servidor. Ponto final. O servidor ignora completamente os blocos $effect. Isso faz sentido quando você pensa bem: os effects 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. Não há "ao longo do tempo" no servidor.

$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.

Callbacks de onMount não são chamados. Como os effects, onMount só é executado no navegador. O callback é registrado, mas não executado.

Callbacks de 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 passo 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, além de tags <script> que carregarão seu bundle JavaScript, além de 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 causaria recarregamentos completos da página sem JavaScript). Os formulários existem (e funcionariam por meio do envio de formulário tradicional sem JavaScript). A página é utilizável, ainda que 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, seu navegador baixa o bundle JavaScript em segundo plano. Dependendo do tamanho do bundle e da velocidade de conexão, isso pode levar de milissegundos a vários segundos.

Após o download, o navegador analisa e executa o JavaScript. Isso é computacionalmente custoso, especialmente em dispositivos móveis. A thread principal fica ocupada durante esse tempo, 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 event handlers 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 de 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>Hello</p> mas o código do cliente renderizaria <p>World</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, event handlers quebrados ou comportamento incorreto.

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

Fase 6: Navegação Client-Side

Após a conclusão da hidratação, sua aplicação é 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 (ao clicar em um link interno), o SvelteKit intercepta a navegação e a trata no client-side. Nenhuma nova requisição de 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 load e monta o novo componente de página.

Essa navegação client-side 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 nas navegações subsequentes — a navegação client-side ignora o servidor por completo.

Análise Aprofundada: Como Cada Rune Se Comporta Durante o SSR

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

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

A rune $state cria um estado reativo que dispara atualizações na UI quando modificado. Na superfície, parece simples: você declara uma variável com um valor inicial, e essa variável torna-se 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 têm efeito:

<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 travará 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, o 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 de proxy significa que você não pode serializar diretamente os valores de $state com JSON.stringify — você precisa usar $state.snapshot() primeiro. Isso normalmente não é um problema durante o SSR normal, mas importa se você estiver serializando 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 perfeitamente 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 a mesma saída.

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 com 600px de largura, a hidratação define screenWidth como 600, fazendo isMobile tornar-se 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 em 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 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 várias vezes (para rastreamento de dependências) ou podem não ser avaliadas de forma alguma (se nada as ler). Efeitos colaterais dentro de 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 effects são fundamentalmente exclusivos do cliente. Eles nunca são executados no servidor.

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

Interagir com APIs do navegador (localStorage, medições do DOM, etc.)
Assinar fontes de dados externas
Realizar logging ou analytics
Integrar com bibliotecas de terceiros que requerem 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, não tem localStorage para ler, não tem navegador para interagir. Ao ignorar os effects durante o SSR, o Svelte mantém a renderização no servidor rápida e evita travamentos por APIs de 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 valor padrão. Após a hidratação, o effect é executado e começa a atualizar mousePosition com as coordenadas reais do mouse.

Os effects também lidam com dependências reativas automaticamente. O Svelte rastreia quais valores de estado você lê dentro do effect e re-executa o effect 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 um efeito é importante porque determina quando os efeitos são re-executados. 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>

Esse 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 Pré-Atualização do DOM

A rune $effect.pre é uma variante especializada que é executada antes das atualizações do DOM em vez de depois. 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 executar 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 que novas mensagens cheguem. 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 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 seguramente adiadas 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 Através de Limites

As props funcionam de forma idêntica no servidor e no cliente — elas são simplesmente valores passados de componentes pai para filho. 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 estado: use padrões consistentes e atualize nos 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 SSR de formas específicas.

onMount só é executado no cliente, após a hidratação. 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 o componente ser montado. $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 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 detalhadamente, 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 forem diferentes, a saída renderizada será diferente, 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), ele 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 depende da hora atual pode ter 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 cruza um limiar, "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), e então muda para 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 diferir 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 tom 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 dois passos (O Padrão "Mount"):

Se você não pode passar dados do servidor (por exemplo, dentro de um componente reutilizável), use uma abordagem em dois passos. Renderize um estado padrão neutro durante o SSR, e então 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 em dois passos. No entanto, a melhor prática para IDs de acessibilidade geralmente é deixar o consumidor passar um ID ou usar uma biblioteca que lida com a geração estável de IDs.

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.

Melhor solução: Use o elemento <picture> com 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> permite que o navegador escolha o formato apropriado sem JavaScript. O HTML é idêntico no servidor e no cliente, e o navegador seleciona automaticamente WebP se 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 o 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 de o formato do cliente assumir. 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 (por cookies, cabeçalhos ou preferências do usuário), passe-o através das 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 tem viewport. Ele não pode saber o tamanho da tela do usuário, a densidade de pixels ou a orientação do dispositivo. 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 tratam layouts responsivos sem nenhum JavaScript. O HTML é idêntico no servidor e no cliente; o navegador aplica os estilos apropriados 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 trate 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 a grade 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

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 em $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>

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

<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 só funcionam 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 de 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 forma declarativa de escutar eventos de window e fazer binding com propriedades de window usando o elemento <svelte:window>. Isso costuma ser mais limpo do que adicionar manualmente listeners 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, então 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 trate isso adequadamente, talvez usando por padrão um layout de desktop ou um estado de carregamento para evitar mudanças de layout quando 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:

<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 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 obsoletos. 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 save:

<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>

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 e começa a desenhar.

Padrão 7: Intersection Observer para Lazy Loading

O Intersection Observer é comumente usado para lazy loading, scroll infinito e animações acionadas por 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 desativa a renderização do lado do servidor para uma página:

// +page.js
export const ssr = false

Com essa 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 é relevante
Páginas com interações complexas exclusivas do cliente onde o SSR não agrega valor

Contrapartidas:

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

Use essa opção com parcimônia. 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 desativa a renderização do 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 submetidos de forma tradicional, sem JavaScript algum
Sem navegação do lado do cliente — cada link causa um recarregamento completo da página
Pode melhorar dramaticamente o desempenho para páginas adequadas

A Opção `prerender`

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

// +page.js
export const prerender = true

Durante npm run build, o SvelteKit rastreia 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 em tempo de build — conteúdo dinâmico requer novos builds
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 conseguem funcionar durante o SSR — eles dependem excessivamente de APIs do navegador, bibliotecas de terceiros ou condições específicas de runtime. Você pode ignorar a renderização deles inteiramente 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 imports dinâmicos 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 do Servidor para o Cliente

Às vezes você precisa passar valores computados do servidor para o cliente sem recomputação. A forma padrão do SvelteKit de 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.

Esse padrão é particularmente valioso para:

Saídas de modelos de aprendizado de máquina
Cálculos ou agregações complexas
Dados que requerem autenticação do lado do servidor para serem obtidos
Qualquer coisa custosa que não deveria ser executada duas vezes

Gerenciando Estado de Autenticação

A autenticação frequentemente reside em cookies (acessíveis durante o SSR), mas precisa de tratamento do lado do cliente para atualizaçã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 é adequado já que modais normalmente começam fechados.

Gerenciando Foco

O gerenciamento de foco é totalmente do 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 problemas de SSR ocorrem, 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 durante o 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 proteja 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 pelo 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 localidade.

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

Resumo de Boas Práticas

Vamos consolidar o que aprendemos em diretrizes acionáveis:

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 requer 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 de window. Esses utilitários gerenciam o SSR automaticamente e fornecem atualizações reativas sem gerenciamento manual de event listeners.

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

Seja deliberado quanto às 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 causa.

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

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

Faça log 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 do 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; você está escrevendo código que deve funcionar corretamente em dois contextos fundamentalmente diferentes, em dois momentos diferentes, com dois conjuntos distintos de APIs disponíveis.

O insight fundamental é 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ó são executados 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 effects, 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 de forma eficaz.

A renderização do lado do servidor não é apenas uma otimização de desempenho ou uma técnica de SEO. É um compromisso com a construção de aplicações resilientes que funcionam para todos: conexões rápidas e lentas, dispositivos poderosos e fracos, JavaScript habilitado e desabilitado, mecanismos 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 entre a fronteira servidor-cliente, entregando carregamentos iniciais rápidos enquanto habilitam uma 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 de Server-Side Rendering com Runes no Svelte 5

O Paradigma da Aplicação Universal

Entendendo 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 de Componentes 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 Client-Side

Análise Aprofundada: 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 Pré-Atualização do DOM

A Rune $props: Comunicação de Componentes Através de Limites

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 de 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 Lazy Loading

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 do Servidor para o Cliente

Gerenciando Estado de Autenticação

Componentes Portal

Gerenciando 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 Pré-Atualização do DOM

A Rune `$props`: Comunicação de Componentes Através de Limites

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`