O Problema da Configuração do Compilador no Nível do Componente

Ao construir aplicações Svelte sofisticadas, você inevitavelmente se depara com situações em que as configurações globais do compilador não se encaixam perfeitamente às necessidades de todos os componentes. Talvez você esteja construindo uma biblioteca de componentes que deve funcionar independentemente de como os projetos consumidores estão configurados. Ou talvez você precise compilar um componente específico como um Web Component para ser consumido em uma aplicação JavaScript puro. Ou ainda você pode estar trabalhando com gráficos SVG que exigem um namespace de renderização diferente dos seus componentes HTML.

O elemento especial <svelte:options> existe precisamente para esses cenários. Ele fornece um mecanismo declarativo para especificar opções do compilador por componente diretamente dentro dos seus arquivos .svelte, substituindo quaisquer configurações globais definidas no seu svelte.config.js ou na configuração do bundler. Esse controle granular torna-se indispensável à medida que as aplicações crescem em complexidade e precisam acomodar requisitos diversos entre diferentes componentes.

Ao contrário dos outros elementos especiais do Svelte que afetam principalmente o comportamento em tempo de execução (como <svelte:window> para vinculação de eventos da janela ou <svelte:head> para manipulação do head do documento), o <svelte:options> opera inteiramente em tempo de compilação. As opções que você especifica influenciam como o compilador Svelte transforma o código-fonte do seu componente em JavaScript, mas não deixam nenhum rastro na saída final em tempo de execução. Essa distinção é crucial para entender quando e como aproveitar esse poderoso elemento.

Anatomia do Elemento `<svelte:options>`

O elemento <svelte:options> utiliza uma sintaxe simples baseada em atributos para configuração:

<svelte:options option={value} />

Este elemento auto-fechável deve aparecer no nível raiz do seu arquivo de componente — ele não pode ser aninhado dentro de outros elementos ou blocos de controle de fluxo. Embora não haja uma exigência estrita quanto à sua posição em relação às tags <script> ou <style>, a prática convencional de colocá-lo no início do arquivo (antes da tag script) melhora a descoberta e torna os requisitos especiais de compilação do componente imediatamente aparentes para qualquer pessoa que leia o código.

Importante: Conteúdo dentro de <svelte:options> é proibido. Ao contrário de outros elementos, você não pode colocar nenhum conteúdo entre as tags de abertura e fechamento — use sempre a forma auto-fechável.

O elemento aceita vários atributos, cada um controlando um aspecto diferente da compilação:

runes={true} — força um componente para o modo runes
runes={false} — força um componente para o modo legado
namespace="..." — o namespace onde este componente será usado: "html" (padrão), "svg" ou "mathml"
customElement={...} — opções para compilar como custom element (string para o nome da tag, ou objeto para configuração detalhada)
css="injected" — injeta estilos inline em vez de extraí-los

Vamos examinar cada opção em profundidade, entendendo não apenas o que ela faz, mas por que e quando você vai querer usá-la.

Controlando o Modo Runes: Garantindo Comportamento Previsível

A opção runes oferece controle explícito sobre qual sistema de reatividade um componente utiliza:

<svelte:options runes={true} />

<script>
	// This component will always use runes regardless of project configuration
	let count = $state(0)
	let doubled = $derived(count * 2)

	function increment() {
		count++
	}
</script>

<button onclick={increment}>
	Count: {count} (Doubled: {doubled})
</button>

Quando você define runes={true}, está instruindo o compilador a analisar e transformar este componente usando o sistema de runes do Svelte 5, independentemente da configuração global do seu projeto.

O Comportamento de Inferência Padrão

Quando você omite a opção runes completamente, o compilador emprega uma inferência inteligente. Ele examina o código-fonte do seu componente em busca de sinais reveladores de uso de runes — $state, $derived, $effect, $props e construções similares. Se encontrar alguma declaração de rune, compila o componente no modo runes; caso contrário, recai para o modo legado. Essa detecção automática funciona muito bem na maioria dos cenários, mas ocasionalmente pode produzir resultados surpreendentes quando um componente é ambíguo.

Nota Crítica para Autores de Bibliotecas: Definir runes: true no seu svelte.config.js força o modo runes para todo o seu projeto, incluindo componentes em node_modules. Isso pode quebrar bibliotecas de terceiros. Em vez disso, defina explicitamente <svelte:options runes={true} /> em cada componente da sua biblioteca para garantir que eles se comportem de forma consistente independentemente de como as aplicações consumidoras estão configuradas.

Configuração de Namespace: Além do HTML

Embora a maioria dos componentes Svelte renderize elementos HTML, o framework também suporta conteúdo SVG e MathML. A opção namespace informa ao compilador qual namespace XML governa a marcação do componente, afetando como os elementos são analisados e validados.

Trabalhando com Componentes SVG

O SVG (Scalable Vector Graphics) opera sob regras diferentes do HTML. Os nomes dos elementos diferenciam maiúsculas de minúsculas, certos atributos usam convenções de nomenclatura diferentes (como viewBox em vez de viewbox), e a API do DOM para criar elementos é diferente. Ao construir um componente que renderiza conteúdo SVG puro, você deve declarar o namespace explicitamente:

<svelte:options namespace="svg" />

<script>
	let { width = 100, height = 100, color = '#3498db' } = $props()
</script>

<!-- These are SVG elements, not HTML elements with the same names -->
<svg {width} {height} viewBox="0 0 100 100">
	<circle cx="50" cy="50" r="40" fill={color} stroke="black" stroke-width="2" />
	<text x="50" y="55" text-anchor="middle" fill="white" font-size="16"> SVG </text>
</svg>

Sem a declaração de namespace, o compilador pode interpretar erroneamente certos elementos ou gerar código de manipulação do DOM incorreto. Por exemplo, elementos SVG devem ser criados usando document.createElementNS() com o URI do namespace SVG, em vez de document.createElement().

Componentes de Fragmento SVG Puro

Ao criar componentes SVG reutilizáveis que serão compostos dentro de um elemento <svg> pai, você pode criar componentes que renderizam fragmentos SVG sem sua própria tag <svg> raiz:

<svelte:options namespace="svg" />

<script>
	let { x = 0, y = 0, size = 20, fill = 'currentColor' } = $props()
</script>

<!-- This component renders a star shape as SVG path elements -->
<g transform="translate({x}, {y})">
	<polygon
		points="10,0 13,7 20,7 14,12 16,20 10,15 4,20 6,12 0,7 7,7"
		{fill}
		transform="scale({size / 20})"
	/>
</g>

Este componente pode então ser composto dentro de um SVG pai:

<script>
	import Star from './Star.svelte'
</script>

<svg width="200" height="100" viewBox="0 0 200 100">
	<Star x={20} y={40} fill="gold" />
	<Star x={80} y={40} fill="silver" />
	<Star x={140} y={40} fill="bronze" />
</svg>

Suporte a MathML

Para notação matemática, o Svelte suporta o namespace MathML:

<svelte:options namespace="mathml" />

<script>
	let { a = 1, b = 2, c = 1 } = $props()

	let discriminant = $derived(b * b - 4 * a * c)
</script>

<!-- The quadratic formula -->
<math display="block">
	<mrow>
		<mi>x</mi>
		<mo>=</mo>
		<mfrac>
			<mrow>
				<mo>-</mo>
				<mi>b</mi>
				<mo>±</mo>
				<msqrt>
					<mrow>
						<msup><mi>b</mi><mn>2</mn></msup>
						<mo>-</mo>
						<mn>4</mn>
						<mi>a</mi>
						<mi>c</mi>
					</mrow>
				</msqrt>
			</mrow>
			<mrow>
				<mn>2</mn>
				<mi>a</mi>
			</mrow>
		</mfrac>
	</mrow>
</math>

<p>With a={a}, b={b}, c={c}: discriminant = {discriminant}</p>

Componentes MathML são menos comuns, mas inestimáveis para aplicações educacionais, documentação científica ou qualquer contexto que exija tipografia matemática adequada que o CSS sozinho não consegue alcançar.

Estratégia de Injeção de CSS: A Opção `css="injected"`

O Svelte normalmente extrai os estilos dos componentes para arquivos CSS separados durante a compilação — seu bundler então cuida de combinar e carregar esses estilos. No entanto, certos cenários se beneficiam de uma abordagem diferente, em que os estilos são embutidos diretamente no bundle JavaScript e injetados em tempo de execução.

<svelte:options css="injected" />

<script>
	let { variant = 'primary', children } = $props()
</script>

<button class="custom-button {variant}">
	{@render children()}
</button>

<style>
	.custom-button {
		padding: 0.75rem 1.5rem;
		border: none;
		border-radius: 4px;
		font-weight: 600;
		cursor: pointer;
		transition: all 0.2s ease;
	}

	.custom-button.primary {
		background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
		color: white;
	}

	.custom-button.secondary {
		background: #e2e8f0;
		color: #475569;
	}

	.custom-button:hover {
		transform: translateY(-2px);
		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
	}
</style>

Como o CSS Injetado Funciona

Com css="injected", o comportamento difere entre renderização no lado do servidor e renderização no lado do cliente:

Durante o SSR: Os estilos do componente são renderizados como uma tag <style> na seção <head> do documento, garantindo que os estilos estejam disponíveis imediatamente quando o HTML for analisado.

Durante o CSR: Os estilos são incluídos no bundle JavaScript e injetados dinamicamente no documento quando o componente é montado. O Svelte é inteligente o suficiente para verificar se os estilos já foram injetados (evitando blocos de estilo duplicados quando existem múltiplas instâncias do mesmo componente).

Quando Usar CSS Injetado

Esta opção se mostra particularmente útil em vários cenários:

Bibliotecas de Componentes: Ao distribuir uma biblioteca de componentes, o CSS injetado significa que os consumidores não precisam configurar suas ferramentas de build para lidar com o seu CSS. Os estilos "simplesmente funcionam" quando importam seu componente.

Componentes Carregados Dinamicamente: Para componentes com code-splitting carregados sob demanda, o CSS injetado garante que os estilos cheguem junto com o código do componente, em vez de exigir que um chunk CSS separado seja carregado.

Arquiteturas Micro-Frontend: Ao incorporar componentes Svelte em aplicações maiores construídas com frameworks diferentes, o CSS injetado elimina desafios de coordenação em torno do carregamento de estilos.

Custom Elements: Ao compilar componentes como web components (custom elements), css="injected" é habilitado automaticamente, pois os estilos devem ser injetados no shadow DOM.

Compensações a Considerar

O CSS injetado não é universalmente superior. Considere estas implicações:

Tamanho do Bundle: Os estilos tornam-se parte do seu bundle JavaScript, aumentando seu tamanho. Para aplicações grandes, o CSS extraído que pode ser cacheado separadamente geralmente tem melhor desempenho.

Flash of Unstyled Content (FOUC): Em cenários de renderização somente no cliente, pode haver um breve momento em que o conteúdo aparece antes que os estilos sejam injetados. O SSR mitiga essa preocupação.

Eficiência de Cache: Arquivos CSS extraídos podem ser cacheados independentemente do JavaScript, potencialmente melhorando o desempenho em visitas repetidas.

Construindo Custom Elements: Web Components com Svelte

Talvez o uso mais poderoso e complexo do <svelte:options> seja compilar componentes Svelte como custom elements (web components). Essa capacidade permite criar elementos de UI reutilizáveis que funcionam em qualquer lugar — aplicações JavaScript puro, projetos React, codebases Vue ou até mesmo páginas HTML estáticas.

Criação Básica de Custom Element

A forma mais simples usa um valor de string para a opção customElement:

<svelte:options customElement="user-avatar" />

<script>
	let { name = 'Anonymous', imageUrl = null, size = 'medium' } = $props()

	let initials = $derived(
		name
			.split(' ')
			.map((part) => part[0])
			.join('')
			.toUpperCase()
			.slice(0, 2)
	)

	let sizeClass = $derived(
		{
			small: 'w-8 h-8 text-xs',
			medium: 'w-12 h-12 text-sm',
			large: 'w-16 h-16 text-lg'
		}[size] || 'w-12 h-12 text-sm'
	)
</script>

<div class="avatar {sizeClass}">
	{#if imageUrl}
		<img src={imageUrl} alt={name} class="avatar-image" />
	{:else}
		<span class="avatar-initials">{initials}</span>
	{/if}
</div>

<style>
	.avatar {
		display: inline-flex;
		align-items: center;
		justify-content: center;
		border-radius: 50%;
		background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
		color: white;
		font-weight: 600;
		overflow: hidden;
	}

	.avatar-image {
		width: 100%;
		height: 100%;
		object-fit: cover;
	}

	.avatar-initials {
		line-height: 1;
	}
</style>

Quando este componente é compilado com a opção de compilador customElement: true, ele produz um custom element que pode ser usado em qualquer contexto HTML:

<!-- In any HTML file or framework -->
<user-avatar name="John Doe" size="large"></user-avatar>
<user-avatar name="Jane Smith" image-url="/avatars/jane.jpg"></user-avatar>

Definição Diferida de Tag

Você pode omitir o nome da tag para qualquer um dos seus componentes internos que não deseja expor e usá-los como componentes Svelte regulares. Os consumidores do componente ainda podem nomeá-lo posteriormente, se necessário, usando a propriedade estática element, que contém o construtor do custom element:

import MyElement from './MyElement.svelte'

customElements.define('my-element', MyElement.element)

Este padrão é útil ao construir bibliotecas de componentes onde o usuário final deve escolher os nomes das tags.

Configuração Avançada de Custom Element

Para casos de uso sofisticados, a opção customElement aceita um objeto com amplas capacidades de configuração:

<svelte:options
	customElement={{
		tag: 'data-table',
		shadow: 'open',
		props: {
			columns: {
				type: 'Array',
				reflect: false
			},
			data: {
				type: 'Array',
				reflect: false
			},
			pageSize: {
				type: 'Number',
				attribute: 'page-size',
				reflect: true
			},
			sortable: {
				type: 'Boolean',
				reflect: true
			},
			selectedIds: {
				type: 'Array',
				attribute: 'selected-ids',
				reflect: true
			}
		}
	}}
/>

<script>
	let { columns = [], data = [], pageSize = 10, sortable = false, selectedIds = [] } = $props()

	let currentPage = $state(0)
	let sortColumn = $state(null)
	let sortDirection = $state('asc')

	let sortedData = $derived.by(() => {
		if (!sortColumn || !sortable) return data

		return [...data].sort((a, b) => {
			const aVal = a[sortColumn]
			const bVal = b[sortColumn]
			const modifier = sortDirection === 'asc' ? 1 : -1

			if (typeof aVal === 'string') {
				return aVal.localeCompare(bVal) * modifier
			}
			return (aVal - bVal) * modifier
		})
	})

	let paginatedData = $derived.by(() => {
		const start = currentPage * pageSize
		return sortedData.slice(start, start + pageSize)
	})

	let totalPages = $derived(Math.ceil(data.length / pageSize))

	function handleSort(column) {
		if (!sortable) return

		if (sortColumn === column) {
			sortDirection = sortDirection === 'asc' ? 'desc' : 'asc'
		} else {
			sortColumn = column
			sortDirection = 'asc'
		}
	}

	function toggleSelection(id) {
		const index = selectedIds.indexOf(id)
		if (index === -1) {
			selectedIds = [...selectedIds, id]
		} else {
			selectedIds = selectedIds.filter((sid) => sid !== id)
		}

		// Dispatch custom event for parent components
		const event = new CustomEvent('selection-change', {
			detail: { selectedIds },
			bubbles: true,
			composed: true
		})
		dispatchEvent(event)
	}
</script>

<div class="table-container">
	<table>
		<thead>
			<tr>
				<th class="checkbox-column">
					<input type="checkbox" />
				</th>
				{#each columns as column}
					<th class={{ sortable }} onclick={() => handleSort(column.key)}>
						{column.label}
						{#if sortColumn === column.key}
							<span class="sort-indicator">
								{sortDirection === 'asc' ? '↑' : '↓'}
							</span>
						{/if}
					</th>
				{/each}
			</tr>
		</thead>
		<tbody>
			{#each paginatedData as row}
				<tr class={{ selected: selectedIds.includes(row.id) }}>
					<td class="checkbox-column">
						<input
							type="checkbox"
							checked={selectedIds.includes(row.id)}
							onchange={() => toggleSelection(row.id)}
						/>
					</td>
					{#each columns as column}
						<td>{row[column.key]}</td>
					{/each}
				</tr>
			{/each}
		</tbody>
	</table>

	<div class="pagination">
		<button disabled={currentPage === 0} onclick={() => currentPage--}> Previous </button>
		<span>Page {currentPage + 1} of {totalPages}</span>
		<button disabled={currentPage >= totalPages - 1} onclick={() => currentPage++}> Next </button>
	</div>
</div>

<style>
	.table-container {
		font-family: system-ui, sans-serif;
		border: 1px solid #e2e8f0;
		border-radius: 8px;
		overflow: hidden;
	}

	table {
		width: 100%;
		border-collapse: collapse;
	}

	th,
	td {
		padding: 12px 16px;
		text-align: left;
		border-bottom: 1px solid #e2e8f0;
	}

	th {
		background: #f8fafc;
		font-weight: 600;
	}

	th.sortable {
		cursor: pointer;
		user-select: none;
	}

	th.sortable:hover {
		background: #f1f5f9;
	}

	.checkbox-column {
		width: 40px;
		text-align: center;
	}

	tr.selected {
		background: #eff6ff;
	}

	tr:hover {
		background: #f8fafc;
	}

	.pagination {
		display: flex;
		align-items: center;
		justify-content: center;
		gap: 16px;
		padding: 12px;
		background: #f8fafc;
	}

	.pagination button {
		padding: 8px 16px;
		border: 1px solid #cbd5e1;
		border-radius: 4px;
		background: white;
		cursor: pointer;
	}

	.pagination button:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.sort-indicator {
		margin-left: 4px;
	}
</style>

Vamos detalhar cada opção de configuração:

tag: O nome da tag HTML para o seu custom element. Deve conter um hífen conforme a especificação de Web Components (ex.: my-component, app-header, user-profile). Se omitido, você pode definir a tag programaticamente depois.

shadow: Controla a criação do shadow DOM. As opções são 'open' (padrão, permite que JavaScript externo acesse o shadow root) ou 'none' (sem shadow DOM, os estilos não são encapsulados). O shadow DOM fornece isolamento de estilos, mas impede que CSS externo estilize elementos internos.

props: Configuração detalhada para cada propriedade, incluindo:

type: Como analisar valores de atributos ('String', 'Boolean', 'Number', 'Array', 'Object'). Crítico porque atributos HTML são sempre strings.
attribute: Mapeamento personalizado do nome do atributo. O Svelte converte camelCase para kebab-case por padrão, mas você pode substituir isso.
reflect: Se as alterações de propriedade devem atualizar o atributo correspondente. Útil para seletores de atributo CSS e depuração.

A Opção `extend`: Personalização Profunda de Custom Elements

A opção extend oferece flexibilidade máxima ao permitir que você aprimore ou personalize completamente a classe de custom element gerada. Isso é particularmente poderoso para integração com formulários HTML usando a API ElementInternals:

<svelte:options
	customElement={{
		tag: 'validated-input',
		props: {
			value: { type: 'String', reflect: true },
			name: { type: 'String', reflect: true },
			required: { type: 'Boolean', reflect: true },
			minLength: { type: 'Number', attribute: 'min-length', reflect: true },
			maxLength: { type: 'Number', attribute: 'max-length', reflect: true },
			pattern: { type: 'String', reflect: true }
		},
		extend: (customElementConstructor) => {
			return class extends customElementConstructor {
				// Mark this element as form-associated
				static formAssociated = true

				// Store reference to internals for form integration
				#internals

				constructor() {
					super()
					this.#internals = this.attachInternals()
				}

				// Form integration: provides value to form data
				get form() {
					return this.#internals.form
				}

				get validity() {
					return this.#internals.validity
				}

				get validationMessage() {
					return this.#internals.validationMessage
				}

				checkValidity() {
					return this.#internals.checkValidity()
				}

				reportValidity() {
					return this.#internals.reportValidity()
				}

				// Called by the Svelte component to update form value
				setFormValue(value) {
					this.#internals.setFormValue(value)
				}

				// Called by the Svelte component to update validation state
				setValidity(flags, message, anchor) {
					this.#internals.setValidity(flags, message, anchor)
				}

				// Expose internals to the Svelte component
				get internals() {
					return this.#internals
				}
			}
		}
	}}
/>

<script>
	let {
		value = $bindable(''),
		name = '',
		required = false,
		minLength = 0,
		maxLength = Infinity,
		pattern = ''
	} = $props()

	let inputElement
	let touched = $state(false)
	let errorMessage = $state('')

	// Get the custom element host for form integration
	const host = $host()

	function validate() {
		if (!inputElement) return

		const validity = inputElement.validity
		let flags = {}
		let message = ''

		if (validity.valueMissing) {
			flags.valueMissing = true
			message = 'This field is required'
		} else if (validity.tooShort) {
			flags.tooShort = true
			message = `Minimum ${minLength} characters required`
		} else if (validity.tooLong) {
			flags.tooLong = true
			message = `Maximum ${maxLength} characters allowed`
		} else if (validity.patternMismatch) {
			flags.patternMismatch = true
			message = 'Please match the requested format'
		}

		errorMessage = message

		// Update custom element's form validity
		if (host?.setValidity) {
			if (Object.keys(flags).length > 0) {
				host.setValidity(flags, message, inputElement)
			} else {
				host.setValidity({})
			}
		}

		// Update form value
		if (host?.setFormValue) {
			host.setFormValue(value)
		}
	}

	// Validate whenever value changes
	$effect(() => {
		validate()
	})

	function handleInput(event) {
		value = event.target.value
	}

	function handleBlur() {
		touched = true
	}
</script>

<div class={['input-wrapper', touched && errorMessage && 'has-error']}>
	<input
		bind:this={inputElement}
		type="text"
		{name}
		{value}
		{required}
		minlength={minLength || undefined}
		maxlength={maxLength === Infinity ? undefined : maxLength}
		{pattern}
		oninput={handleInput}
		onblur={handleBlur}
	/>
	{#if touched && errorMessage}
		<span class="error-message">{errorMessage}</span>
	{/if}
</div>

<style>
	.input-wrapper {
		display: flex;
		flex-direction: column;
		gap: 4px;
	}

	input {
		padding: 8px 12px;
		border: 2px solid #cbd5e1;
		border-radius: 6px;
		font-size: 16px;
		transition: border-color 0.2s;
	}

	input:focus {
		outline: none;
		border-color: #3b82f6;
	}

	.has-error input {
		border-color: #ef4444;
	}

	.error-message {
		color: #ef4444;
		font-size: 12px;
	}
</style>

Este custom element estendido participa de formulários HTML assim como controles de formulário nativos, habilitando recursos como envio de formulário, validação e a pseudo-classe CSS :invalid.

Entendendo as Nuances do Ciclo de Vida de Custom Elements

Custom elements seguem seu próprio modelo de ciclo de vida que difere sutilmente dos componentes Svelte padrão. Entender essas nuances evita bugs confusos:

Criação Adiada do Componente

Quando um custom element é instanciado, o componente Svelte interno não é criado imediatamente. A criação acontece no próximo tick após o disparo de connectedCallback (ou seja, após o elemento ser anexado ao DOM). Isso significa:

// This might not work as expected immediately
const myElement = document.createElement('my-custom-element')
myElement.someMethod() // Error! Component not mounted yet

// Instead, wait for connection
document.body.appendChild(myElement)
// Or use requestAnimationFrame/setTimeout
requestAnimationFrame(() => {
	myElement.someMethod() // Now it works
})

Propriedades definidas antes da anexação ao DOM são preservadas e aplicadas quando o componente finalmente é montado, mas métodos exportados não estão disponíveis até esse momento. Se você precisar invocar funções antes da criação do componente, pode contornar isso usando a opção extend para adicionar os métodos diretamente à classe do custom element.

Movimentações no DOM e Desanexação Temporária

Se um custom element for temporariamente removido do DOM e reanexado (uma ocorrência comum durante certas operações no DOM), o componente Svelte interno sobrevive. A destruição só acontece no próximo tick após o disparo de disconnectedCallback, dando tempo para que operações de movimentação síncronas sejam concluídas sem destruir o componente.

Atualizações em Lote no Shadow DOM

Atualizações no shadow DOM são agrupadas em lote e aplicadas no próximo tick, não de forma síncrona. Isso evita re-renderizações excessivas, mas significa que você não pode inspecionar o DOM atualizado imediatamente após alterar uma propriedade:

myElement.count = 5
console.log(myElement.shadowRoot.querySelector('.count').textContent)
// Might still show old value

// Use awaiting a tick or watching for mutations if immediate inspection is needed

Problemas Reais e Soluções

2. Construindo um Design System Agnóstico de Framework

Cenário: Sua empresa usa múltiplos frameworks frontend em diferentes equipes — React para a aplicação principal, Vue para ferramentas internas e JavaScript puro para sistemas legados. Você precisa construir um design system unificado que funcione em todos os lugares.

Solução: Biblioteca de Custom Elements com Svelte

Crie uma biblioteca de componentes que compile para custom elements.

!!! Nota Importante sobre Slots em Custom Elements !!!

Ao compilar componentes Svelte como custom elements, você deve usar o elemento HTML nativo <slot> em vez da sintaxe de snippet do Svelte 5 ({@render children()}). Isso ocorre porque custom elements operam no shadow DOM nativo do navegador, que usa o mecanismo de slot padrão de Web Components. O elemento <slot> em custom elements se comporta de forma diferente dos componentes Svelte regulares — o conteúdo inserido via slot é renderizado de forma eager (imediata) em vez de lazy.

<!-- lib/Button.svelte -->
<svelte:options
	customElement={{
		tag: 'ds-button',
		shadow: 'open',
		props: {
			variant: { type: 'String', reflect: true },
			size: { type: 'String', reflect: true },
			disabled: { type: 'Boolean', reflect: true },
			loading: { type: 'Boolean', reflect: true }
		}
	}}
/>

<script>
	let { variant = 'primary', size = 'medium', disabled = false, loading = false } = $props()
</script>

<button class="ds-button {variant} {size}" {disabled} aria-busy={loading}>
	{#if loading}
		<span class="spinner" aria-hidden="true"></span>
	{/if}
	<slot />
</button>

<style>
	.ds-button {
		display: inline-flex;
		align-items: center;
		justify-content: center;
		gap: 8px;
		font-family: inherit;
		font-weight: 500;
		border: none;
		border-radius: 6px;
		cursor: pointer;
		transition: all 0.15s ease;
	}

	/* Size variants */
	.ds-button.small {
		padding: 6px 12px;
		font-size: 14px;
	}
	.ds-button.medium {
		padding: 10px 20px;
		font-size: 16px;
	}
	.ds-button.large {
		padding: 14px 28px;
		font-size: 18px;
	}

	/* Color variants */
	.ds-button.primary {
		background: var(--ds-primary, #3b82f6);
		color: white;
	}
	.ds-button.primary:hover:not(:disabled) {
		background: var(--ds-primary-hover, #2563eb);
	}

	.ds-button.secondary {
		background: var(--ds-secondary, #e2e8f0);
		color: var(--ds-secondary-text, #1e293b);
	}

	.ds-button.danger {
		background: var(--ds-danger, #ef4444);
		color: white;
	}

	.ds-button:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.spinner {
		width: 16px;
		height: 16px;
		border: 2px solid currentColor;
		border-top-color: transparent;
		border-radius: 50%;
		animation: spin 0.6s linear infinite;
	}

	@keyframes spin {
		to {
			transform: rotate(360deg);
		}
	}
</style>

Uso entre frameworks:

<!-- Vanilla HTML -->
<ds-button variant="primary" size="large">Click Me</ds-button>

<!-- React (with wrapper for better DX) -->
<DsButton variant="primary" onClick="{handleClick}"> Click Me </DsButton>

<!-- Vue -->
<ds-button :variant="buttonVariant" @click="handleClick"> Click Me </ds-button>

Insight principal: Use propriedades customizadas CSS (como --ds-primary) para temas, permitindo que cada aplicação consumidora personalize as cores sem modificar o código do componente.

2. Conteúdo de Slot Renderizado de Forma Eager em Custom Elements

Cenário: Você tem um componente de abas onde o conteúdo de cada aba deveria renderizar apenas quando aquela aba está ativa. Mas com custom elements, todo o conteúdo inserido via slot é renderizado imediatamente, independentemente de blocos {#if}.

Entendendo o Problema: No Svelte padrão, o conteúdo de slot renderiza de forma lazy — ele só é criado quando o slot é de fato renderizado. Em custom elements (DOM), o conteúdo de slot renderiza de forma eager. Incluir um <slot> em um bloco {#if ...} não impede que o conteúdo seja criado.

Solução: Slots Nomeados com Controle de Exibição

<svelte:options customElement="tab-panel" />

<script>
	let { activeTab = 0 } = $props()
</script>

<div class="tabs">
	<div class="tab-headers">
		<slot name="headers" />
	</div>

	<div class="tab-panels">
		<!-- Instead of conditionally rendering slots, control visibility -->
		<div class="panel" class:active={activeTab === 0}>
			<slot name="panel-0" />
		</div>
		<div class="panel" class:active={activeTab === 1}>
			<slot name="panel-1" />
		</div>
		<div class="panel" class:active={activeTab === 2}>
			<slot name="panel-2" />
		</div>
	</div>
</div>

<style>
	.panel {
		display: none;
	}
	.panel.active {
		display: block;
	}
</style>

Solução Alternativa: Se você precisar de renderização verdadeiramente lazy, use props de callback ou carregamento dinâmico de conteúdo em vez de slots:

<svelte:options
	customElement={{
		tag: 'lazy-tabs',
		props: {
			tabs: { type: 'Array' },
			activeTab: { type: 'Number', reflect: true }
		}
	}}
/>

<script>
	let { tabs = [], activeTab = 0 } = $props()
</script>

<div class="tabs">
	{#each tabs as tab, index}
		<button class:active={activeTab === index} onclick={() => (activeTab = index)}>
			{tab.label}
		</button>
	{/each}
</div>

<!-- Only the active content is in the DOM -->
<div class="content">
	{@html tabs[activeTab]?.content || ''}
</div>

3. Custom Elements Não Funcionando com SSR

Cenário: Sua aplicação SvelteKit usa custom elements, mas eles aparecem como caixas vazias durante a renderização no servidor antes que o JavaScript seja carregado.

Entendendo o Problema: Custom elements geralmente não são adequados para renderização no lado do servidor porque o shadow DOM fica invisível até que o JavaScript seja carregado. O navegador não sabe como renderizar a estrutura interna do componente sem a definição JavaScript.

Solução 1: Padrão de Progressive Enhancement

Projete seus custom elements para exibir conteúdo significativo mesmo antes que o JavaScript seja carregado:

<svelte:options customElement="product-card" />

<script>
	let { name, price, imageUrl } = $props()
</script>

<!-- The slot acts as fallback content visible during SSR -->
<article class="card">
	<slot name="fallback">
		<!-- This content appears before JS loads -->
		<noscript>
			<p>Enable JavaScript to view this product</p>
		</noscript>
	</slot>

	<img src={imageUrl} alt={name} />
	<h3>{name}</h3>
	<p class="price">${price}</p>
</article>

Uso com conteúdo de fallback:

<product-card name="Widget" price="29.99" image-url="/widget.jpg">
	<div slot="fallback">
		<!-- Server-rendered fallback -->
		<img src="/widget.jpg" alt="Widget" />
		<h3>Widget</h3>
		<p>$29.99</p>
	</div>
</product-card>

Solução 2: Arquitetura Consciente de Hidratação

Mantenha custom elements para widgets verdadeiramente interativos e use componentes Svelte regulares para conteúdo crítico em SSR:

<!-- Regular Svelte component for SSR -->
<script>
	import { browser } from '$app/environment'

	let { productData } = $props()
</script>

<!-- SSR-friendly static content -->
<article class="product">
	<h2>{productData.name}</h2>
	<p>{productData.description}</p>

	<!-- Custom element only for interactive parts -->
	{#if browser}
		<add-to-cart product-id={productData.id} price={productData.price}></add-to-cart>
	{:else}
		<button disabled>Add to Cart (Loading...)</button>
	{/if}
</article>

4. Estilizando Custom Elements de Fora

Cenário: Você está usando um componente de custom element, mas precisa aplicar estilos globais ou personalizações de tema a partir da aplicação pai.

Entendendo o Problema: O shadow DOM fornece encapsulamento de estilos — estilos externos não conseguem penetrar a barreira do shadow. Isso geralmente é desejável, mas pode ser frustrante quando você precisa de temas.

Solução 1: Propriedades Customizadas CSS (Recomendado)

Propriedades customizadas CSS atravessam o shadow DOM:

<svelte:options customElement="themed-card" />

<script>
	let { title } = $props()
</script>

<div class="card">
	<h2>{title}</h2>
	<slot />
</div>

<style>
	.card {
		/* Use CSS custom properties with fallbacks */
		background: var(--card-bg, white);
		color: var(--card-text, #1e293b);
		border: 1px solid var(--card-border, #e2e8f0);
		border-radius: var(--card-radius, 8px);
		padding: var(--card-padding, 20px);
		box-shadow: var(--card-shadow, 0 1px 3px rgba(0, 0, 0, 0.1));
	}

	h2 {
		color: var(--card-heading-color, inherit);
		font-size: var(--card-heading-size, 1.25rem);
		margin: 0 0 12px;
	}
</style>

Temas externos:

/* Global theme */
:root {
	--card-bg: #1e293b;
	--card-text: #f1f5f9;
	--card-border: #334155;
	--card-heading-color: #60a5fa;
}

/* Or scope to specific instances */
themed-card.dark-mode {
	--card-bg: #0f172a;
}

Solução 2: Desativar o Shadow DOM

Para componentes que precisam de controle total de estilização externa:

<svelte:options
	customElement={{
		tag: 'styleable-card',
		shadow: 'none'
	}}
/>

<script>
	let { title } = $props()
</script>

<!-- No shadow DOM - styles from parent document apply -->
<div class="card">
	<h2>{title}</h2>
	<slot />
</div>

Trade-off: Sem o shadow DOM, você perde o encapsulamento de estilos. Os estilos do seu componente podem conflitar com os estilos da aplicação pai, e vice-versa.

Solução 3: Estilização Baseada em Part

Use o pseudo-elemento CSS ::part() para estilização externa seletiva:

<svelte:options customElement="styled-button" />

<script>
	let { variant = 'primary' } = $props()
</script>

<button part="button base" class={variant}>
	<span part="icon">
		<slot name="icon" />
	</span>
	<span part="label">
		<slot />
	</span>
</button>

<style>
	button {
		/* Default styles */
		display: inline-flex;
		align-items: center;
		gap: 8px;
	}
</style>

Estilização externa com ::part():

styled-button::part(button) {
	border-radius: 9999px;
}

styled-button::part(icon) {
	color: var(--accent-color);
}

5. Context Não Funcionando Através de Fronteiras de Custom Elements

Cenário: Você está usando a API de contexto do Svelte (setContext/getContext) na sua aplicação, mas ela não funciona ao cruzar fronteiras de custom elements.

Entendendo o Problema: O recurso de contexto do Svelte funciona entre componentes Svelte regulares dentro de um custom element, mas você não pode usar contexto entre custom elements. Definir contexto em um custom element pai não será acessível via getContext em um custom element filho.

Solução 1: Custom Events para Comunicação

<!-- Parent custom element -->
<svelte:options customElement="data-provider" />

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

	function handleRequestData(event) {
		// Respond to child's request
		event.target.dispatchEvent(
			new CustomEvent('data-response', {
				detail: data,
				bubbles: false
			})
		)
	}
</script>

<div onrequest-data={handleRequestData}>
	<slot />
</div>

<!-- Child custom element -->
<svelte:options customElement="data-consumer" />

<script>
	import { $host } from 'svelte'
	import { onMount } from 'svelte'

	let data = $state(null)
	const host = $host()

	onMount(() => {
		// Listen for response
		host.addEventListener('data-response', (e) => {
			data = e.detail
		})

		// Request data from parent
		host.dispatchEvent(
			new CustomEvent('request-data', {
				bubbles: true,
				composed: true
			})
		)
	})
</script>

{#if data}
	<div>{JSON.stringify(data)}</div>
{:else}
	<div>Loading...</div>
{/if}

Solução 2: Estado Compartilhado via Window ou Módulo

// lib/shared-state.svelte.js
export const sharedState = $state({
	theme: 'light',
	user: null,
	notifications: []
})

export function updateTheme(theme) {
	sharedState.theme = theme
}

<!-- Any custom element can access shared state -->
<svelte:options customElement="theme-toggle" />

<script>
	import { sharedState, updateTheme } from './shared-state.svelte.js'
</script>

<button onclick={() => updateTheme(sharedState.theme === 'light' ? 'dark' : 'light')}>
	Current: {sharedState.theme}
</button>

6. Sistema de Ícones SVG com Cores Dinâmicas

Cenário: Você está construindo um sistema de ícones onde os ícones precisam herdar cores de seu contexto e suportar múltiplas personalizações de cores.

Solução: Componentes SVG com currentColor

<!-- lib/icons/Icon.svelte -->
<svelte:options namespace="svg" />

<script>
	let { name, size = 24, strokeWidth = 2, class: className = '' } = $props()

	// Icon path definitions
	const icons = {
		home: 'M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z M9 22V12h6v10',
		settings:
			'M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6z M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z',
		user: 'M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2 M12 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8z',
		alert:
			'M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z M12 9v4 M12 17h.01'
	}
</script>

<svg
	width={size}
	height={size}
	viewBox="0 0 24 24"
	fill="none"
	stroke="currentColor"
	stroke-width={strokeWidth}
	stroke-linecap="round"
	stroke-linejoin="round"
	class="icon {className}"
	aria-hidden="true"
>
	<path d={icons[name]} />
</svg>

<style>
	.icon {
		display: inline-block;
		vertical-align: middle;
		flex-shrink: 0;
	}
</style>

Uso com cores herdadas:

<script>
	import Icon from '$lib/icons/Icon.svelte'
</script>

<!-- Icon inherits text color -->
<button class="primary">
	<Icon name="home" />
	Home
</button>

<button class="danger">
	<Icon name="alert" />
	Warning
</button>

<style>
	.primary {
		color: #3b82f6;
	}
	.danger {
		color: #ef4444;
	}
</style>

7. Componentes de Biblioteca se Comportando Diferentemente com Base na Configuração do Consumidor

Cenário: Você está publicando uma biblioteca de componentes Svelte, mas os componentes se comportam de forma imprevisível dependendo se o projeto consumidor usa runes: true globalmente.

Solução: Declaração Explícita de Modo

Sempre declare o modo runes explicitamente em componentes de biblioteca:

<!-- Always at the top of every library component -->
<svelte:options runes={true} />

<script>
	// Now this component behaves consistently regardless of consumer's config
	let { items = [], onSelect } = $props()

	let selectedIndex = $state(-1)

	function handleKeyDown(event) {
		if (event.key === 'ArrowDown') {
			selectedIndex = Math.min(selectedIndex + 1, items.length - 1)
		} else if (event.key === 'ArrowUp') {
			selectedIndex = Math.max(selectedIndex - 1, 0)
		} else if (event.key === 'Enter' && selectedIndex >= 0) {
			onSelect?.(items[selectedIndex])
		}
	}
</script>

<ul role="listbox" onkeydown={handleKeyDown} tabindex="0">
	{#each items as item, index}
		<li
			role="option"
			aria-selected={selectedIndex === index}
			class:selected={selectedIndex === index}
		>
			{item.label}
		</li>
	{/each}
</ul>

Dica de documentação: Inclua no README da sua biblioteca:

## Compatibility

This library is built with Svelte 5 runes. It works with any Svelte 5 project regardless of your `runes` configuration setting.

8. Incorporando Widgets Svelte em Aplicações Não-Svelte

Cenário: Você precisa incorporar um widget complexo baseado em Svelte (como um widget de chat ou painel de análise) em sites construídos com diversas tecnologias—WordPress, HTML estático ou outros frameworks.

Solução: Widget Autocontido com Auto-Registro

<!-- ChatWidget.svelte -->
<svelte:options
	customElement={{
		tag: 'chat-widget',
		shadow: 'open',
		props: {
			apiKey: { type: 'String', attribute: 'api-key' },
			position: { type: 'String', reflect: true },
			theme: { type: 'String', reflect: true },
			greeting: { type: 'String' }
		}
	}}
	css="injected"
/>

<script>
	let {
		apiKey,
		position = 'bottom-right',
		theme = 'light',
		greeting = 'How can we help?'
	} = $props()

	let isOpen = $state(false)
	let messages = $state([])
	let inputValue = $state('')

	async function sendMessage() {
		if (!inputValue.trim()) return

		messages = [...messages, { role: 'user', content: inputValue }]
		const userMessage = inputValue
		inputValue = ''

		// Simulate API call
		const response = await fetch('/api/chat', {
			method: 'POST',
			headers: {
				'Content-Type': 'application/json',
				Authorization: `Bearer ${apiKey}`
			},
			body: JSON.stringify({ message: userMessage })
		})

		const data = await response.json()
		messages = [...messages, { role: 'assistant', content: data.reply }]
	}
</script>

<div class="widget {position} {theme}">
	{#if isOpen}
		<div class="chat-window">
			<header>
				<h3>Support Chat</h3>
				<button onclick={() => (isOpen = false)}>×</button>
			</header>

			<div class="messages">
				<div class="message assistant">{greeting}</div>
				{#each messages as message}
					<div class="message {message.role}">{message.content}</div>
				{/each}
			</div>

			<form
				onsubmit={(e) => {
					e.preventDefault()
					sendMessage()
				}}
			>
				<input bind:value={inputValue} placeholder="Type a message..." />
				<button type="submit">Send</button>
			</form>
		</div>
	{:else}
		<button class="trigger" onclick={() => (isOpen = true)}>
			<svg viewBox="0 0 24 24" width="24" height="24">
				<path
					fill="currentColor"
					d="M12 3c5.5 0 10 3.58 10 8s-4.5 8-10 8c-1.24 0-2.43-.18-3.53-.5C5.55 21 2 21 2 21c2.33-2.33 2.7-3.9 2.75-4.5C3.05 15.07 2 13.13 2 11c0-4.42 4.5-8 10-8z"
				/>
			</svg>
		</button>
	{/if}
</div>

<style>
	.widget {
		position: fixed;
		z-index: 9999;
		font-family: system-ui, sans-serif;
	}

	.widget.bottom-right {
		bottom: 20px;
		right: 20px;
	}
	.widget.bottom-left {
		bottom: 20px;
		left: 20px;
	}

	.widget.light {
		--bg: white;
		--text: #1e293b;
		--border: #e2e8f0;
		--primary: #3b82f6;
	}
	.widget.dark {
		--bg: #1e293b;
		--text: #f1f5f9;
		--border: #334155;
		--primary: #60a5fa;
	}

	.trigger {
		width: 56px;
		height: 56px;
		border-radius: 50%;
		background: var(--primary);
		color: white;
		border: none;
		cursor: pointer;
		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
	}

	.chat-window {
		width: 350px;
		height: 500px;
		background: var(--bg);
		border-radius: 12px;
		box-shadow: 0 8px 30px rgba(0, 0, 0, 0.12);
		display: flex;
		flex-direction: column;
		overflow: hidden;
	}

	header {
		padding: 16px;
		background: var(--primary);
		color: white;
		display: flex;
		justify-content: space-between;
		align-items: center;
	}

	header h3 {
		margin: 0;
		font-size: 16px;
	}

	header button {
		background: none;
		border: none;
		color: white;
		font-size: 24px;
		cursor: pointer;
	}

	.messages {
		flex: 1;
		overflow-y: auto;
		padding: 16px;
		display: flex;
		flex-direction: column;
		gap: 12px;
	}

	.message {
		padding: 10px 14px;
		border-radius: 18px;
		max-width: 80%;
	}

	.message.user {
		background: var(--primary);
		color: white;
		align-self: flex-end;
	}

	.message.assistant {
		background: var(--border);
		color: var(--text);
		align-self: flex-start;
	}

	form {
		display: flex;
		padding: 12px;
		gap: 8px;
		border-top: 1px solid var(--border);
	}

	input {
		flex: 1;
		padding: 10px;
		border: 1px solid var(--border);
		border-radius: 20px;
		background: var(--bg);
		color: var(--text);
	}

	form button {
		padding: 10px 20px;
		background: var(--primary);
		color: white;
		border: none;
		border-radius: 20px;
		cursor: pointer;
	}
</style>

Incorporando em qualquer site:

<!-- Just include the script and use the element -->
<script src="https://cdn.yourcompany.com/chat-widget.js"></script>

<chat-widget
	api-key="your-api-key"
	position="bottom-right"
	theme="light"
	greeting="Hi! How can we help you today?"
></chat-widget>

Boas Práticas e Armadilhas Comuns

Posicionamento e Visibilidade

Sempre coloque <svelte:options> no início do arquivo de componente, antes das tags <script>:

<!-- PREFERRED: Options first -->
<svelte:options runes={true} />

<script>
	// Component logic
</script>

<!-- AVOID: Options buried in the file -->
<script>
	// Component logic
</script>

<svelte:options runes={true} />

Embora tecnicamente válido em qualquer lugar no nível superior, o posicionamento no início torna a configuração do compilador imediatamente aparente.

Declaração Explícita de Props para Elementos Personalizados

Ao criar elementos personalizados, você deve desestruturar explicitamente as props em vez de usar $props() sem desestruturação. O compilador precisa saber quais propriedades expor no elemento DOM:

<svelte:options customElement="my-element" />

<script>
	// PREFERRED: Explicit destructuring tells Svelte which props to expose
	let { name, count, items = [] } = $props()

	// AVOID: Svelte doesn't know which props to expose as element properties
	// let props = $props();
</script>

Evitando Conflitos de Nomes de Propriedades

Não nomeie propriedades de elementos personalizados começando com on—o Svelte as interpreta como ouvintes de eventos:

<svelte:options customElement="my-toggle" />

<script>
	// AVOID: "onclick" gets interpreted as an event listener
	// let { onclick } = $props();

	// PREFERRED: Use a different name
	let { handleClick, clickCallback } = $props()
</script>

Isso significa que <custom-element oneworld={true}> é tratado como customElement.addEventListener('eworld', true), e não como customElement.oneworld = true.

Preservando Slots em Shadow Roots Declarativas

Ao usar <template shadowrootmode="..."> para shadow DOM declarativo, o Svelte 5 preserva elementos <slot /> como slots DOM reais em vez de transformá-los:

<template shadowrootmode="open">
	<!-- This slot is preserved as a real DOM slot element -->
	<slot></slot>
</template>

Combinando Opções para Cenários Complexos

As opções podem ser combinadas para requisitos sofisticados:

<svelte:options
	runes={true}
	namespace="svg"
	customElement={{
		tag: 'icon-chart',
		shadow: 'open',
		props: {
			data: { type: 'Array' },
			width: { type: 'Number', reflect: true },
			height: { type: 'Number', reflect: true }
		}
	}}
/>

<script>
	let { data = [], width = 200, height = 100 } = $props()

	let maxValue = $derived(Math.max(...data.map((d) => d.value), 1))
	let points = $derived(
		data
			.map((d, i) => {
				const x = (i / (data.length - 1)) * width
				const y = height - (d.value / maxValue) * height
				return `${x},${y}`
			})
			.join(' ')
	)
</script>

<svg {width} {height} viewBox="0 0 {width} {height}">
	<polyline {points} fill="none" stroke="currentColor" stroke-width="2" />
	{#each data as point, i}
		<circle
			cx={(i / (data.length - 1)) * width}
			cy={height - (point.value / maxValue) * height}
			r="4"
			fill="currentColor"
		/>
	{/each}
</svg>

<style>
	svg {
		overflow: visible;
	}

	polyline {
		stroke-linecap: round;
		stroke-linejoin: round;
	}

	circle {
		transition: r 0.2s;
	}

	circle:hover {
		r: 6;
	}
</style>

Isso cria um elemento personalizado que renderiza um gráfico SVG, usa a reatividade moderna de runes e expõe corretamente propriedades tipadas.

Testando Elementos Personalizados

Ao testar elementos personalizados, lembre-se do comportamento de montagem diferida:

import { describe, it, expect } from 'vitest'
import { tick } from 'svelte'
import './MyElement.svelte' // This registers the custom element

describe('my-element', () => {
	it('renders with default props', async () => {
		const element = document.createElement('my-element')
		document.body.appendChild(element)

		// Wait for Svelte to mount the inner component
		await tick()

		expect(element.shadowRoot.querySelector('h1').textContent).toBe('Default Title')

		// Cleanup
		element.remove()
	})

	it('reflects property changes', async () => {
		const element = document.createElement('my-element')
		document.body.appendChild(element)
		await tick()

		element.title = 'New Title'
		await tick() // Wait for batched update

		expect(element.shadowRoot.querySelector('h1').textContent).toBe('New Title')
		element.remove()
	})
})

Depurando Elementos Personalizados

Use o DevTools do navegador para inspecionar shadow roots de elementos personalizados:

// In browser console
const element = document.querySelector('my-element')
console.log(element.shadowRoot) // Inspect shadow DOM

// Check current property values
console.log(element.name, element.count)

// Manually trigger updates for testing
element.count = 42

Referência de Opções Depreciadas

O Svelte 5 deprecia várias opções que não são funcionais no modo runes:

A Opção `immutable` (Depreciada)

<!-- DEPRECATED - Has no effect in runes mode -->
<svelte:options immutable={true} />

Esta opção informava ao compilador que ele poderia usar verificações de igualdade por referência (===) em vez de comparações profundas para detecção de mudanças. No modo runes, o sistema de reatividade de granularidade fina torna essa otimização irrelevante—o compilador rastreia exatamente quais propriedades são acessadas e atualizadas.

A Opção `accessors` (Depreciada)

<!-- DEPRECATED - Has no effect in runes mode -->
<svelte:options accessors={true} />

Esta opção gerava pares getter/setter para as props do componente, permitindo que código externo lesse e escrevesse props programaticamente. O modo runes lida com o acesso a propriedades de forma diferente. Para elementos personalizados, o acesso a propriedades é tratado automaticamente através das definições de propriedade do elemento personalizado.

Referência Rápida

Quando Usar Cada Opção

Opção	Usar Quando
`runes={true}`	Publicar bibliotecas que precisam de comportamento consistente independentemente da configuração do consumidor
`runes={false}`	Manter componentes que intencionalmente usam padrões legados
`namespace="svg"`	Construir componentes SVG puros ou sistemas de ícones
`namespace="mathml"`	Criar componentes de notação matemática
`css="injected"`	Distribuir componentes independentes, construir widgets ou compilar elementos customizados
`customElement="tag-name"`	Criar web components agnósticos de framework
`customElement={{ ... }}`	Configuração avançada de elementos customizados com tipagem de props, controle do Shadow DOM ou integração com formulários

Conclusão

O elemento <svelte:options> fornece controle cirúrgico sobre como os componentes individuais são compilados, habilitando cenários que de outra forma exigiriam a reestruturação de toda a sua configuração de build ou o abandono completo do modelo de compilação do Svelte. Essa configurabilidade em nível de componente é particularmente valiosa ao construir bibliotecas, manter bases de código legadas durante migrações ou criar web components agnósticos de framework que precisam se integrar a ambientes diversos.

Dominar o <svelte:options> significa entender não apenas a sintaxe de cada opção, mas as decisões estratégicas por trás de quando usá-las. A opção runes garante que os componentes de biblioteca se comportem de forma previsível independentemente das configurações das aplicações consumidoras. A opção namespace é essencial para componentes SVG e MathML, reconhecendo que nem todo conteúdo é HTML. A opção css="injected" simplifica cenários de distribuição e carregamento dinâmico, embora com trade-offs que valem a pena entender. A configuração customElement desbloqueia o Svelte para a construção de web components verdadeiramente portáteis com tipagem sofisticada de props, controle do Shadow DOM e interoperabilidade com frameworks.

Com <svelte:options> em seu arsenal, você pode construir aplicações Svelte que lidam graciosamente com requisitos diversos — desde componentes modernos baseados em runes até web components portáteis implantáveis em qualquer lugar onde navegadores modernos sejam executados. A chave é entender não apenas o que cada opção faz, mas quando recorrer a ela e quais implicações arquiteturais ela carrega.

Principais Conclusões

<svelte:options> configura o comportamento do compilador por componente, substituindo os padrões em nível de projeto para modo runes, namespace, injeção de CSS, elementos customizados, imutabilidade e avisos de acessibilidade
A opção runes={true/false} habilita o controle explícito de modo, permitindo componentes legados em projetos com runes ou excluindo componentes específicos do modo runes em bases de código em transição
A opção namespace é crítica para SVG e MathML — use namespace="svg" para componentes SVG ou namespace="mathml" para notação matemática, a fim de garantir a criação correta dos elementos
A opção css="injected" empacota estilos no JavaScript, habilitando o carregamento dinâmico de componentes sem arquivos CSS separados, ideal para code-splitting e web components, porém aumentando o tamanho do bundle JS
A configuração de elementos customizados via objeto customElement transforma componentes Svelte em web components agnósticos de framework com nomes de tags, opções de Shadow DOM e mapeamentos de props/eventos
Shadow DOM "open" vs "none" negocia encapsulamento — o modo open isola estilos mas bloqueia CSS global, enquanto o modo none habilita estilização mas perde o encapsulamento
Props com tipagem requerem interfaces TypeScript em declarações svelte:options tag="...">, usando SvelteComponent.element para extensão adequada de HTMLElement
Elementos customizados têm limitações de ciclo de vida e contexto — sem suporte a SSR, árvores de contexto separadas das aplicações Svelte pai, e a renderização de conteúdo em slots requer compreensão da mecânica de projeção

Veja Também

Documentação Oficial do Svelte 5 - <svelte:options>
Especificação de Web Components - API nativa do navegador para elementos customizados
Shadow DOM - Entendendo encapsulamento de estilos e projeção de slots
Custom Elements Everywhere - Testes de compatibilidade de frameworks para web components
Documentação de Runes do Svelte - Entendendo o novo modelo de reatividade
SVG em HTML - Tratamento de namespace para conteúdo SVG
MathML Core - Notação matemática em navegadores web
Cascata e Herança CSS - Como o Shadow DOM afeta a estilização
Genéricos TypeScript - Props de elementos customizados com tipagem segura