A Evolução da Interação com o DOM no Svelte

O Svelte sempre defendeu a filosofia de escrever menos código enquanto realiza mais. Desde seu início, o framework fornecia a diretiva use: (actions) como o principal mecanismo para interagir imperativamente com elementos DOM—vinculando bibliotecas de terceiros, gerenciando foco, implementando arrastar e soltar, e inúmeros outros cenários onde templates declarativos são insuficientes.

No entanto, à medida que o Svelte evoluiu para sua arquitetura reativa baseada em runes na versão 5, uma tensão fundamental surgiu. As actions, embora poderosas, operavam de certa forma fora do paradigma reativo do Svelte. Elas recebiam atualizações por meio de um callback update explícito, criando uma desconexão de modelo mental com o restante do sistema de reatividade push-pull do framework.

Attachments

O Svelte 5.29 introduz os attachments—uma abordagem reimaginada para interação imperativa com o DOM que se integra perfeitamente ao sistema de efeitos do Svelte. Os attachments são executados dentro de efeitos, rastreando automaticamente dependências reativas e re-executando quando essas dependências mudam.

Essa mudança aparentemente simples tem implicações profundas em como arquitetamos bibliotecas de componentes, gerenciamos interações complexas com o DOM e raciocinamos sobre reatividade entre fronteiras de componentes.

Este tutorial pressupõe familiaridade com as runes do Svelte 5 ($state, $derived, $effect, $props) e uma compreensão sólida dos fundamentos do JavaScript, incluindo Proxies, Symbols e o event loop. Vamos construir progressivamente a partir de conceitos fundamentais até padrões arquiteturais avançados, examinando não apenas como usar attachments, mas por que eles representam um avanço significativo no modelo de componentes do Svelte.

1. O Nível Conceitual

1.1 O que é um Attachment?

Em sua essência, um attachment é uma função que recebe um elemento DOM quando esse elemento é montado no DOM. A função é executada dentro de um contexto de efeito, o que significa que qualquer estado reativo lido durante a execução se torna uma dependência—quando esse estado muda, o attachment re-executa automaticamente.

interface Attachment<T extends EventTarget = Element> {
	(element: T): void | (() => void)
}

Essa assinatura de tipo revela o contrato essencial:

O attachment recebe um elemento
Opcionalmente retorna uma função de limpeza
A limpeza é executada antes da re-execução ou quando o elemento é desmontado

1.2 O Modelo de Execução Baseado em Efeitos

**Entender que os attachments são executados dentro de efeitos é crucial** para dominar seu comportamento. Considere as implicações:

<script>
	let color = $state('#ff3e00')
	let size = $state(100)

	function paintCanvas(canvas) {
		// This runs in an effect context
		const ctx = canvas.getContext('2d')

		// Both `color` and `size` are read synchronously
		// They become dependencies of this attachment
		ctx.fillStyle = color
		ctx.fillRect(0, 0, size, size)

		return () => {
			// Cleanup: runs before re-execution or unmount
			ctx.clearRect(0, 0, canvas.width, canvas.height)
		}
	}
</script>

<canvas {@attach paintCanvas} width={200} height={200}></canvas>

Quando color ou size mudam, o sistema reativo do Svelte:

Marca o attachment como sujo
Invoca a função de limpeza (se fornecida)
Re-executa a função de attachment
Rastreia quaisquer novas dependências lidas durante a execução

Isso espelha exatamente como $effect funciona em outros lugares no Svelte 5, criando um modelo mental unificado para efeitos colaterais reativos.

1.3 Attachments vs. Actions: Uma Mudança Filosófica

Na evolução do Svelte, a diretiva use: (actions) representava a abordagem original para interações imperativas com o DOM. Com a introdução das runes no Svelte 5, os attachments ({@attach ...}) oferecem uma maneira mais integrada de lidar com tais interações. Esta seção explora a mudança filosófica de actions para attachments, detalhando o que cada um é, quando usá-los e como aplicá-los de forma eficaz.

O que eram as Actions?

As actions eram o mecanismo inicial do Svelte para vincular comportamento imperativo a elementos DOM. Elas seguiam um padrão de atualização imperativa onde os desenvolvedores gerenciavam manualmente as mudanças de estado por meio de um callback update separado:

<!-- Traditional action pattern -->
<script>
	function myAction(node, params) {
		// Initial setup
		return {
			update(newParams) {
				// Called when params change
			},
			destroy() {
				// Cleanup
			}
		}
	}
</script>

<div use:myAction={someValue}>...</div>

Esse padrão exigia que os desenvolvedores:

Gerenciassem manualmente as atualizações em um callback separado
Rastreassem quais parâmetros mudaram
Implementassem atualizações diferenciais para evitar trabalho redundante

As actions operavam de certa forma fora do paradigma reativo do Svelte, criando uma desconexão com o sistema de reatividade push-pull do framework.

O que são Attachments?

Attachments são a abordagem moderna, integrada às runes, para interações com o DOM. Eles são executados dentro do sistema de efeitos do Svelte, rastreando automaticamente dependências reativas e re-executando quando essas dependências mudam:

<!-- Attachment pattern -->
<script>
	function myAttachment(node) {
		// Reads `someValue` reactively
		doSomethingWith(someValue)

		return () => {
			// Automatic cleanup before re-run
		}
	}
</script>

<div {@attach myAttachment}>...</div>

A abordagem com attachments é declarativa sobre o que acontece (o corpo da função) enquanto o Svelte cuida de quando acontece (rastreamento de dependências e agendamento).

Quando Usar Actions vs. Attachments

Embora @attach seja a abordagem preferida para novo código Svelte 5, as actions use: ainda são suportadas e podem ser úteis para:

Bases de código legadas em migração gradual.
Actions que precisam funcionar em diferentes versões do Svelte ou mesmo em outros frameworks (embora raro).
Cenários complexos onde o controle manual sobre atualizações é benéfico.

Para novas interações imperativas com o DOM no Svelte 5, prefira @attach para alinhar-se com a filosofia reativa do framework e reduzir a carga cognitiva.

Como Usar Attachments

Attachments são funções que recebem um elemento DOM e opcionalmente retornam uma função de limpeza. Eles se integram perfeitamente à reatividade do Svelte:

Uso básico: {@attach myFunction} vincula uma função simples.

<script>
	function logMount(el) {
		console.log('Element mounted')
	}
</script>

<div {@attach logMount}>Basic example</div>

Parametrizado: {@attach factory(param)} usa uma factory para comportamento dinâmico.

<script>
	function tooltip(text) {
		return (el) => {
			// Setup tooltip with text
			return () => {
				/* cleanup */
			}
		}
	}
</script>

<button {@attach tooltip('Hover me')}>Button</button>

Inline: {@attach (el) => { /* setup */ return () => { /* cleanup */ } }} para lógica pontual.

<div
	{@attach (el) => {
		el.style.color = 'red'
		return () => (el.style.color = '')
	}}
>
	Inline example
</div>

Múltiplos: Aplique vários attachments ao mesmo elemento para comportamentos combinados.

<script>
	function attach1(el) {
		/* ... */
	}
	function attach2(el) {
		/* ... */
	}
</script>

<div {@attach attach1} {@attach attach2}>Multiple attachments</div>

Componentes: Attachments são repassados por componentes que espalham {...props} (rest props).

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

<!-- Usage -->
<MyComponent {@attach someAttach} />
<div {...props}>Component content</div>

Passando Opções para Attachments

Embora os attachments em si recebam apenas o elemento, use factories para injetar opções ou parâmetros:

<script>
	function attachWithOptions(options) {
		return (element) => {
			// Use options here
			element.style.color = options.color
			element.textContent = options.text
			return () => {
				element.style.color = ''
				element.textContent = ''
			}
		}
	}
</script>

<div {@attach attachWithOptions({ color: 'red', text: 'Hello' })}>Styled element</div>

Esse padrão permite que attachments sejam parametrizados sem alterar a assinatura principal (element).

Como Migrar de Actions

Para actions existentes, use fromAction para convertê-las em attachments:

<script>
	import { fromAction } from 'svelte/attachments'
	import { someLibraryAction } from 'some-library'

	let actionParam = $state('value')
</script>

<!-- Original action -->
<div use:someLibraryAction={actionParam}>...</div>

<!-- Equivalent attachment -->
<div {@attach fromAction(someLibraryAction, () => actionParam)}>...</div>

Para actions personalizadas, reescreva-as como attachments nativos removendo o callback update e aproveitando leituras reativas diretamente no corpo da função.

A Mudança Filosófica em Detalhe

Essa mudança representa uma transição da programação imperativa para a reatividade declarativa. No modelo de actions, os desenvolvedores precisavam antecipar e tratar as mudanças de parâmetros manualmente, frequentemente levando a um gerenciamento de estado complexo e potenciais bugs por atualizações esquecidas. Os attachments, por contraste, abraçam o paradigma reativo do Svelte: você descreve o comportamento desejado e o framework garante que ele permaneça sincronizado com os dados.

Benefícios dos Attachments em Relação às Actions

Menos Boilerplate: Não há necessidade de métodos update e destroy separados; tudo está em uma única função.
Rastreamento Automático de Dependências: O Svelte sabe automaticamente quando re-executar o attachment com base nas leituras reativas.
Sistema de Efeitos Unificado: Attachments se comportam como $effect, tornando a base de código mais consistente.
Testes Mais Fáceis: Como attachments são apenas funções, podem ser testados unitariamente de forma isolada.
Melhor Desempenho: Menos sobrecarga das verificações de atualização manual; o agendador do Svelte otimiza as re-execuções.

2. Padrões Fundamentais e Sintaxe

2.1 Declaração Básica de Attachment

O attachment mais simples é uma função que realiza a configuração quando um elemento é montado:

<script>
	/** @type {import('svelte/attachments').Attachment} */
	function logMount(element) {
		console.log(`Mounted: ${element.tagName}`)
	}
</script>

<div {@attach logMount}>This div logs when it mounts</div>

Usuários de TypeScript se beneficiam do tipo Attachment exportado de svelte/attachments, que fornece tipagem adequada para o parâmetro do elemento e o tipo de retorno.

2.2 Funções de Limpeza: O Contrato do Valor de Retorno

Retornar uma função de limpeza é opcional, mas essencial para:

Remover listeners de eventos
Cancelar timers ou animações
Descartar instâncias de bibliotecas de terceiros
Liberar recursos

<script>
	function trackMouse(element) {
		function handleMove(event) {
			element.style.setProperty('--mouse-x', `${event.clientX}px`)
			element.style.setProperty('--mouse-y', `${event.clientY}px`)
		}

		document.addEventListener('mousemove', handleMove)

		return () => {
			document.removeEventListener('mousemove', handleMove)
		}
	}
</script>

<div {@attach trackMouse} class="mouse-tracker">Tracks mouse position</div>

<style>
	.mouse-tracker::before {
		content: '';
		position: fixed;
		left: var(--mouse-x, 0);
		top: var(--mouse-y, 0);
		/* ... */
	}
</style>

2.3 Múltiplos Attachments em um Único Elemento

Elementos podem receber qualquer número de attachments, cada um operando de forma independente:

<script>
	function trackVisibility(el) {
		const observer = new IntersectionObserver((entries) => {
			entries.forEach((entry) => {
				console.log(`Visible: ${entry.isIntersecting}`)
			})
		})
		observer.observe(el)
		return () => observer.disconnect()
	}

	function trackResize(el) {
		const observer = new ResizeObserver((entries) => {
			entries.forEach((entry) => {
				console.log(`Size: ${entry.contentRect.width}x${entry.contentRect.height}`)
			})
		})
		observer.observe(el)
		return () => observer.disconnect()
	}

	function applyStyles(el) {
		el.style.border = '2px solid blue'
	}
</script>

<div {@attach trackVisibility} {@attach trackResize} {@attach applyStyles}>
	This element has three independent attachments
</div>

Cada attachment:

Possui seu próprio contexto de efeito
Rastreia suas próprias dependências
Gerencia seu próprio ciclo de vida de limpeza

3. Fábricas de Attachment—Interação DOM Parametrizada

3.1 O Padrão de Fábrica Explicado

Attachments simples funcionam bem para comportamentos estáticos, mas aplicações reais exigem parametrização. Uma fábrica de attachment é uma função que retorna um attachment, permitindo que você passe configurações:

<script>
	/**
	 * Creates a tooltip attachment
	 * @param {string} content - Tooltip text
	 * @returns {import('svelte/attachments').Attachment}
	 */
	function tooltip(content) {
		return (element) => {
			// Setup tooltip with `content`
			const tip = createTooltip(element, content)
			return () => tip.destroy()
		}
	}

	let message = $state('Hello, world!')
</script>

<button {@attach tooltip(message)}> Hover for tooltip </button>

3.2 Reatividade em Fábricas: Entendendo a Re-execução

Ao usar padrões de fábrica com valores reativos, toda a expressão é reavaliada quando as dependências mudam:

<script>
	import { computePosition, autoUpdate, offset, shift } from '@floating-ui/dom'

	let content = $state('Initial tooltip')

	function tooltip(content) {
		return (element) => {
			const tooltipEl = document.createElement('div')
			tooltipEl.textContent = content
			tooltipEl.style.position = 'absolute'
			tooltipEl.style.background = 'rgba(0, 0, 0, 0.8)'
			tooltipEl.style.color = 'white'
			tooltipEl.style.padding = '4px 8px'
			tooltipEl.style.borderRadius = '4px'
			tooltipEl.style.fontSize = '14px'
			tooltipEl.style.pointerEvents = 'none'
			tooltipEl.style.display = 'none'
			document.body.appendChild(tooltipEl)

			const updatePosition = () => {
				computePosition(element, tooltipEl, {
					placement: 'top',
					middleware: [offset(6), shift()]
				}).then(({ x, y }) => {
					Object.assign(tooltipEl.style, {
						left: `${x}px`,
						top: `${y}px`
					})
				})
			}

			const cleanup = autoUpdate(element, tooltipEl, updatePosition)

			const show = () => {
				tooltipEl.style.display = 'block'
				updatePosition()
			}

			const hide = () => {
				tooltipEl.style.display = 'none'
			}

			element.addEventListener('mouseenter', show)
			element.addEventListener('mouseleave', hide)

			return () => {
				cleanup()
				element.removeEventListener('mouseenter', show)
				element.removeEventListener('mouseleave', hide)
				document.body.removeChild(tooltipEl)
			}
		}
	}
</script>

<input bind:value={content} />

<!-- When `content` changes:
     1. tooltip(content) is called with new value
     2. Previous attachment's cleanup runs
     3. New attachment runs (new tooltip element created)
-->
<button {@attach tooltip(content)}> Dynamic tooltip </button>

Essa recriação automática é o comportamento padrão. Para muitos casos de uso—especialmente operações leves—isso é perfeitamente aceitável. No entanto, para operações de configuração custosas, precisamos de um controle mais refinado.

3.3 Exemplo de Fábrica do Mundo Real: Integração com Floating UI

Vamos construir uma fábrica de tooltip pronta para produção usando o Floating UI para posicionamento:

<script>
	import { computePosition, autoUpdate, offset, shift } from '@floating-ui/dom'

	/**
	 * Creates a fully-featured tooltip attachment
	 *
	 * @param {string} content - Tooltip content
	 * @param {Object} [options={}] - Tooltip options
	 * @param {string} [options.placement='top'] - Placement of the tooltip
	 * @returns {import('svelte/attachments').Attachment<HTMLElement>}
	 */
	function tooltip(content, options = {}) {
		return (element) => {
			const tooltipEl = document.createElement('div')
			tooltipEl.textContent = content
			tooltipEl.style.position = 'absolute'
			tooltipEl.style.background = 'rgba(0, 0, 0, 0.8)'
			tooltipEl.style.color = 'white'
			tooltipEl.style.padding = '8px 12px'
			tooltipEl.style.borderRadius = '6px'
			tooltipEl.style.fontSize = '14px'
			tooltipEl.style.pointerEvents = 'none'
			tooltipEl.style.zIndex = '9999'
			tooltipEl.style.display = 'none'
			document.body.appendChild(tooltipEl)

			const updatePosition = () => {
				computePosition(element, tooltipEl, {
					placement: options.placement || 'top',
					middleware: [offset(8), shift({ padding: 5 })]
				}).then(({ x, y }) => {
					Object.assign(tooltipEl.style, {
						left: `${x}px`,
						top: `${y}px`
					})
				})
			}

			const cleanup = autoUpdate(element, tooltipEl, updatePosition)

			const show = () => {
				tooltipEl.style.display = 'block'
				updatePosition()
			}

			const hide = () => {
				tooltipEl.style.display = 'none'
			}

			element.addEventListener('mouseenter', show)
			element.addEventListener('mouseleave', hide)

			return () => {
				cleanup()
				element.removeEventListener('mouseenter', show)
				element.removeEventListener('mouseleave', hide)
				document.body.removeChild(tooltipEl)
			}
		}
	}

	let tooltipText = $state('Hover over me!')
	let placement = $state('top')
</script>

<div class="demo">
	<input type="text" bind:value={tooltipText} placeholder="Edit tooltip text" />

	<select bind:value={placement}>
		<option value="top">Top</option>
		<option value="bottom">Bottom</option>
		<option value="left">Left</option>
		<option value="right">Right</option>
	</select>

	<button {@attach tooltip(tooltipText, { placement })}> Hover Me </button>
</div>

4. Attachments Inline—Quando a Brevidade Vence

4.1 Sintaxe Inline para Casos Simples

Para attachments simples e pontuais, arrow functions inline eliminam código desnecessário:

<script>
	let color = $state('#3498db')
</script>

<canvas
	width={200}
	height={200}
	{@attach (canvas) => {
		const ctx = canvas.getContext('2d')
		ctx.fillStyle = color
		ctx.fillRect(0, 0, 200, 200)
	}}
></canvas>

<input type="color" bind:value={color} />

Vantagens dos Attachments Inline

Sem definição de função separada: Mantém a lógica próxima ao template.
Contexto imediato: Acesso a variáveis locais sem precisar passar parâmetros.
Prototipagem rápida: Ideal para comportamentos simples e não reutilizáveis.

Quando Usar Attachments Nomeados no Lugar

Reutilização: Se a lógica é usada em múltiplos lugares.
Complexidade: Para attachments com configuração ou limpeza significativas.
Testabilidade: Funções nomeadas são mais fáceis de testar unitariamente.
Legibilidade: Para lógicas mais longas, funções nomeadas melhoram a organização do código.

Attachments inline se destacam em interações leves e específicas de componentes, enquanto attachments nomeados são mais adequados para comportamentos compartilhados ou complexos.

4.2 Efeitos Aninhados Dentro de Attachments Inline

Attachments inline podem utilizar chamadas $effect aninhadas para controle de reatividade mais granular:

<script>
	let backgroundColor = $state('#ffffff')
	let foregroundColor = $state('#000000')
	let text = $state('Hello')
</script>

<canvas
	width={400}
	height={100}
	{@attach (canvas) => {
		const ctx = canvas.getContext('2d')

		// Outer effect runs once (no reactive reads yet)
		// This is where we'd do expensive setup
		ctx.font = '24px sans-serif'
		ctx.textAlign = 'center'
		ctx.textBaseline = 'middle'

		// Nested effect for background (runs when backgroundColor changes)
		$effect(() => {
			ctx.fillStyle = backgroundColor
			ctx.fillRect(0, 0, canvas.width, canvas.height)
		})

		// Another nested effect for text (runs when text or foregroundColor changes)
		$effect(() => {
			// Must redraw background first since we clear nothing
			ctx.fillStyle = backgroundColor
			ctx.fillRect(0, 0, canvas.width, canvas.height)

			ctx.fillStyle = foregroundColor
			ctx.fillText(text, canvas.width / 2, canvas.height / 2)
		})
	}}
></canvas>

Este padrão demonstra uma técnica de otimização crucial: o attachment externo é executado uma vez para a configuração custosa, enquanto efeitos aninhados lidam com atualizações reativas granulares.

5. Passando Attachments para Componentes

5.1 O Mecanismo de Prop Baseado em Symbol

Um dos recursos mais poderosos dos attachments é sua capacidade de passar por fronteiras de componentes via espalhamento de props. Quando você usa {@attach ...} em um componente, o Svelte cria uma prop com uma chave Symbol única:

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

	function focusOnMount(element) {
		element.focus()
	}
</script>

<Button {@attach focusOnMount}>I'll be focused on mount</Button>

<!-- Button.svelte -->
<script>
	/** @type {import('svelte/elements').HTMLButtonAttributes} */
	let { children, ...props } = $props()
</script>

<!-- Spreading `props` includes the attachment Symbol -->
<button {...props}>
	{@render children?.()}
</button>

5.2 Como Isso Funciona por Baixo dos Panos

Quando {@attach fn} é usado em um componente:

O Svelte gera um Symbol único
A função de attachment é atribuída a essa chave Symbol no objeto de props
Quando as props são espalhadas em um elemento, o Svelte reconhece o Symbol e anexa a função

Esse mecanismo significa que componentes wrapper "simplesmente funcionam" sem encaminhamento explícito de attachments:

<!-- IconButton.svelte -->
<script>
	import Icon from './Icon.svelte'

	let { icon, children, ...props } = $props()
</script>

<button {...props}>
	<Icon name={icon} />
	{@render children?.()}
</button>

<!-- Usage -->
<script>
	import IconButton from './IconButton.svelte'

	function trackClick(element) {
		element.addEventListener('click', () => {
			analytics.track('button_clicked')
		})
		return () => {
			// cleanup...
		}
	}
</script>

<!-- The attachment reaches the inner <button> element -->
<IconButton icon="save" {@attach trackClick}>Save Document</IconButton>

5.3 Construindo Componentes Wrapper que Preservam Attachments

Um padrão crítico para autores de bibliotecas de componentes é garantir que os attachments fluam através de componentes wrapper:

<!-- Card.svelte -->
<script>
	/**
	 * @type {{
	 *   variant?: 'default' | 'elevated' | 'outlined',
	 *   children: import('svelte').Snippet,
	 *   [key: string]: any
	 * }}
	 */
	let { variant = 'default', children, ...props } = $props()
</script>

<article class="card card--{variant}" {...props}>
	{@render children()}
</article>

<style>
	.card {
		/* ... */
	}
	.card--elevated {
		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
	}
	.card--outlined {
		border: 1px solid currentColor;
	}
</style>

Ao usar rest props (...props) e espalhá-los no elemento raiz, quaisquer attachments passados para <Card> são automaticamente aplicados ao elemento <article>.

6. Controlando a Re-execução de Attachments

6.1 O Desafio da Re-execução

Por padrão, attachments são re-executados sempre que qualquer dependência muda. Para operações custosas, isso pode ser problemático:

<script>
	function expensiveSetup(bar) {
		return (node) => {
			// This runs on EVERY change to `bar`
			veryExpensiveSetupWork(node) // 😬
			update(node, bar)
		}
	}

	let bar = $state('initial')
</script>

<div {@attach expensiveSetup(bar)}>...</div>

Toda vez que bar muda, veryExpensiveSetupWork é executado novamente—claramente indesejável.

Entendendo os Gatilhos de Re-execução

A re-execução ocorre quando:

O estado reativo lido durante a execução do attachment muda.
A fábrica de attachment é chamada com novos parâmetros (recriando a função de attachment).
O componente remonta o elemento.

Sinais de que a Re-execução é um Problema

Problemas de desempenho: Setup custoso executando desnecessariamente.
Falhas visuais: Bibliotecas reinicializando, causando flickering.
Vazamentos de recursos: Limpeza incompleta de re-execuções rápidas.
Comportamento inesperado: Estado não preservado entre re-execuções.

Quando esses problemas surgem, o padrão getter fornece uma solução.

6.2 O Padrão Getter para Leitura Diferida

A solução é passar uma função getter em vez do valor diretamente, adiando a leitura reativa para um efeito aninhado:

<script>
	/**
	 * @param {() => string} getBar - Getter for the reactive value
	 * @returns {import('svelte/attachments').Attachment}
	 */
	function expensiveSetup(getBar) {
		return (node) => {
			// Runs once—no reactive reads here
			veryExpensiveSetupWork(node)

			// Nested effect reads the value reactively
			$effect(() => {
				update(node, getBar())
			})
		}
	}

	let bar = $state('initial')
</script>

<!-- Pass a getter, not the value --><div {@attach expensiveSetup(() => bar)}>...</div>

Agora:

expensiveSetup(() => bar) cria o attachment uma vez
veryExpensiveSetupWork é executado uma vez na montagem
O $effect aninhado é executado sempre que bar muda

6.3 Exemplo Prático: Integração com Biblioteca de Gráficos

Considere integrar uma biblioteca de gráficos onde a inicialização é custosa:

<script>
	import { Chart, registerables } from 'chart.js'
	Chart.register(...registerables)

	/**
	 * Creates a reactive chart attachment
	 * @param {() => import('chart.js').ChartData} getData
	 * @param {import('chart.js').ChartOptions} options
	 */
	function createChart(getData, options = {}) {
		return (canvas) => {
			// Expensive: runs once
			const chart = new Chart(canvas, {
				type: 'line',
				data: getData(),
				options: {
					responsive: true,
					maintainAspectRatio: false,
					...options
				}
			})

			// Cheap: runs on data changes
			$effect(() => {
				const newData = getData()
				chart.data = newData
				chart.update('none') // Skip animations for updates
			})

			return () => chart.destroy()
		}
	}

	let salesData = $state({
		labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
		datasets: [
			{
				label: 'Sales',
				data: [12, 19, 3, 5, 2]
			}
		]
	})

	function addDataPoint() {
		const months = ['Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
		const nextMonth = months[salesData.labels.length - 5]
		if (nextMonth) {
			salesData.labels = [...salesData.labels, nextMonth]
			salesData.datasets[0].data = [...salesData.datasets[0].data, Math.floor(Math.random() * 20)]
		}
	}
</script>

<div class="chart-container">
	<canvas {@attach createChart(() => salesData)}></canvas>
</div>

<button onclick={addDataPoint}>Add Data Point</button>

7. Criação Programática de Attachments

7.1 A Função `createAttachmentKey`

Às vezes você precisa criar attachments de forma programática — especialmente em código de biblioteca onde você está construindo objetos de props dinamicamente. A função createAttachmentKey de svelte/attachments gera chaves Symbol reconhecidas pelo mecanismo de spreading do Svelte:

<script>
	import { createAttachmentKey } from 'svelte/attachments'

	// Create a prop object with an attachment
	const props = {
		class: 'interactive-element',
		'data-testid': 'my-element',
		onclick: () => console.log('clicked'),
		[createAttachmentKey()]: (node) => {
			node.setAttribute('data-mounted', 'true')
			return () => node.removeAttribute('data-mounted')
		}
	}
</script>

<button {...props}> Click me </button>

7.2 Caso de Uso no Desenvolvimento de Bibliotecas

Esse padrão se destaca ao construir bibliotecas de componentes que precisam anexar comportamentos dinamicamente:

<script module>
	import { createAttachmentKey } from 'svelte/attachments'

	/**
	 * Creates a props object for draggable elements
	 * @param {Object} options
	 * @param {(position: {x: number, y: number}) => void} options.onDrag
	 * @param {() => void} [options.onDragStart]
	 * @param {() => void} [options.onDragEnd]
	 */
	export function createDraggable({ onDrag, onDragStart, onDragEnd }) {
		return {
			draggable: true,
			[createAttachmentKey()]: (element) => {
				let startX, startY, initialX, initialY

				function handleDragStart(e) {
					startX = e.clientX
					startY = e.clientY
					const rect = element.getBoundingClientRect()
					initialX = rect.left
					initialY = rect.top
					onDragStart?.()
				}

				function handleDrag(e) {
					if (e.clientX === 0 && e.clientY === 0) return
					const dx = e.clientX - startX
					const dy = e.clientY - startY
					onDrag({ x: initialX + dx, y: initialY + dy })
				}

				function handleDragEnd() {
					onDragEnd?.()
				}

				element.addEventListener('dragstart', handleDragStart)
				element.addEventListener('drag', handleDrag)
				element.addEventListener('dragend', handleDragEnd)

				return () => {
					element.removeEventListener('dragstart', handleDragStart)
					element.removeEventListener('drag', handleDrag)
					element.removeEventListener('dragend', handleDragEnd)
				}
			}
		}
	}
</script>

<script>
	let position = $state({ x: 100, y: 100 })

	const draggableProps = createDraggable({
		onDrag: (pos) => (position = pos),
		onDragStart: () => console.log('Started dragging'),
		onDragEnd: () => console.log('Finished dragging')
	})
</script>

<div {...draggableProps} style="position: absolute; left: {position.x}px; top: {position.y}px;">
	Drag me!
</div>

7.3 Múltiplos Attachments Programáticos

Você pode incluir múltiplos attachments em um único objeto de props chamando createAttachmentKey() várias vezes:

<script>
	import { createAttachmentKey } from 'svelte/attachments'

	const props = {
		class: 'multi-behavior',
		[createAttachmentKey()]: (el) => {
			// First attachment: logging
			console.log('Element mounted:', el)
			return () => console.log('Element unmounting:', el)
		},
		[createAttachmentKey()]: (el) => {
			// Second attachment: intersection observer
			const observer = new IntersectionObserver((entries) => {
				entries.forEach((entry) => {
					el.classList.toggle('visible', entry.isIntersecting)
				})
			})
			observer.observe(el)
			return () => observer.disconnect()
		},
		[createAttachmentKey()]: (el) => {
			// Third attachment: focus trap
			// ...implementation
		}
	}
</script>

<div {...props}>Multiple behaviors attached programmatically</div>

8. Migrando de Actions para Attachments

8.1 O Utilitário `fromAction`

O Svelte fornece fromAction para converter actions existentes em attachments, permitindo migração gradual e interoperabilidade com bibliotecas baseadas em actions:

<script>
	import { fromAction } from 'svelte/attachments'
	import { someLibraryAction } from 'some-library'

	let actionParam = $state('value')
</script>

<!-- Original action syntax -->
<div use:someLibraryAction={actionParam}>...</div>

<!-- Equivalent attachment syntax -->
<div {@attach fromAction(someLibraryAction, () => actionParam)}>...</div>

Nota importante: O segundo argumento deve ser uma função que retorna o parâmetro, não o próprio parâmetro. Isso garante o rastreamento correto de reatividade.

8.2 Por que Migrar? A Vantagem da Composabilidade

Embora actions ainda funcionem, attachments oferecem composabilidade superior:

Passagem por componentes: Attachments passam por fronteiras de componentes via spreading
Reatividade unificada: Sem callback update separado para manter
Integração com efeitos: Pode usar $effect internamente para controle refinado

<!-- This doesn't work with actions -->
<MyComponent use:someAction={param}>Content</MyComponent>

<!-- This works with attachments -->
<MyComponent {@attach fromAction(someAction, () => param)}>Content</MyComponent>

8.3 Estratégia de Migração para Codebases Existentes

Para codebases grandes com muitas actions, migre de forma incremental:

Identifique padrões de uso de actions - catalogue todas as actions
Envolva actions críticas de bibliotecas - use fromAction para código de terceiros
Reescreva actions personalizadas - converta suas próprias actions em attachments nativos
Atualize interfaces de componentes - garanta que componentes wrapper façam spread de props

<!-- Before: Custom action -->
<script>
  export function tooltip(node, text) {
    const tip = document.createElement('div');
    tip.className = 'tooltip';
    tip.textContent = text;

    function show() { document.body.appendChild(tip); }
    function hide() { tip.remove(); }

    node.addEventListener('mouseenter', show);
    node.addEventListener('mouseleave', hide);

    return {
      update(newText) {
        tip.textContent = newText;
      },
      destroy() {
        node.removeEventListener('mouseenter', show);
        node.removeEventListener('mouseleave', hide);
        tip.remove();
      }
    };
  }
</script>

<!-- After: Native attachment -->
<script>
  export function tooltip(text) {
    return (node) => {
      const tip = document.createElement('div');
      tip.className = 'tooltip';

      // Text is read reactively through the factory closure
      tip.textContent = text;

      function show() { document.body.appendChild(tip); }
      function hide() { tip.remove(); }

      node.addEventListener('mouseenter', show);
      node.addEventListener('mouseleave', hide);

      return () => {
        node.removeEventListener('mouseenter', show);
        node.removeEventListener('mouseleave', hide);
        tip.remove();
      };
    };
  }
</script>

Armadilhas Comuns na Migração

Esquecer o getter: Usar fromAction(action, param) em vez de fromAction(action, () => param).
Limpeza ausente: Actions com limpeza manual precisam de tratamento adequado do destroy.
Fronteiras de componentes: Actions não passam por componentes a menos que sejam espalhadas.
Diferenças de reatividade: Attachments rastreiam dependências automaticamente, ao contrário das atualizações manuais das actions.

Testando Sua Migração

Garanta que attachments se comportem de forma idêntica às actions.
Teste a reatividade: mudanças devem disparar atualizações sem chamadas manuais a update.
Verifique a limpeza: sem vazamentos de memória ou efeitos persistentes.
Verifique a passagem por componentes: attachments devem funcionar em componentes wrapper.

9. Casos de Uso Reais e Padrões

9.1 Sistema de Gerenciamento de Foco

Gerenciar o foco é essencial para acessibilidade. Aqui está um attachment abrangente de armadilha de foco:

<script>
	/**
	 * Creates a focus trap attachment for modal dialogs
	 * @param {Object} options
	 * @param {boolean} [options.autoFocus=true] - Focus first focusable element on mount
	 * @param {boolean} [options.restoreFocus=true] - Restore focus on unmount
	 * @returns {import('svelte/attachments').Attachment}
	 */
	function focusTrap({ autoFocus = true, restoreFocus = true } = {}) {
		return (container) => {
			const previouslyFocused = document.activeElement

			const focusableSelectors = [
				'button:not([disabled])',
				'input:not([disabled])',
				'select:not([disabled])',
				'textarea:not([disabled])',
				'a[href]',
				'[tabindex]:not([tabindex="-1"])'
			].join(', ')

			function getFocusableElements() {
				return Array.from(container.querySelectorAll(focusableSelectors))
			}

			function handleKeyDown(event) {
				if (event.key !== 'Tab') return

				const focusable = getFocusableElements()
				if (focusable.length === 0) return

				const first = focusable[0]
				const last = focusable[focusable.length - 1]

				if (event.shiftKey && document.activeElement === first) {
					event.preventDefault()
					last.focus()
				} else if (!event.shiftKey && document.activeElement === last) {
					event.preventDefault()
					first.focus()
				}
			}

			container.addEventListener('keydown', handleKeyDown)

			if (autoFocus) {
				const focusable = getFocusableElements()
				if (focusable.length > 0) {
					focusable[0].focus()
				}
			}

			return () => {
				container.removeEventListener('keydown', handleKeyDown)
				if (restoreFocus && previouslyFocused instanceof HTMLElement) {
					previouslyFocused.focus()
				}
			}
		}
	}

	let showModal = $state(false)
</script>

{#if showModal}
	<div class="modal-backdrop">
		<div class="modal" role="dialog" aria-modal="true" {@attach focusTrap()}>
			<h2>Modal Title</h2>
			<p>Modal content goes here.</p>
			<button onclick={() => (showModal = false)}>Close</button>
		</div>
	</div>
{/if}

9.2 Intersection Observer para Carregamento Lazy

<script>
	/**
	 * Lazy loading attachment with placeholder support
	 * @param {Object} options
	 * @param {string} options.src - Image source to load
	 * @param {string} [options.placeholder] - Placeholder while loading
	 * @param {string} [options.rootMargin='100px'] - Load ahead margin
	 * @returns {import('svelte/attachments').Attachment<HTMLImageElement>}
	 */
	function lazyLoad({ src, placeholder = '', rootMargin = '100px' }) {
		return (img) => {
			// Set placeholder immediately
			if (placeholder) {
				img.src = placeholder
			}

			const observer = new IntersectionObserver(
				(entries) => {
					entries.forEach((entry) => {
						if (entry.isIntersecting) {
							// Load the real image
							img.src = src
							img.classList.add('loaded')
							observer.disconnect()
						}
					})
				},
				{ rootMargin }
			)

			observer.observe(img)

			return () => observer.disconnect()
		}
	}

	const images = [
		{ src: '/images/hero-1.jpg', alt: 'Hero image 1' },
		{ src: '/images/hero-2.jpg', alt: 'Hero image 2' },
		{ src: '/images/hero-3.jpg', alt: 'Hero image 3' }
	]
</script>

<div class="image-gallery">
	{#each images as image}
		<img
			alt={image.alt}
			{@attach lazyLoad({
				src: image.src,
				placeholder: '/images/placeholder.svg'
			})}
		/>
	{/each}
</div>

9.3 Cursor de Colaboração em Tempo Real

<script>
	import { onMount } from 'svelte'

	/**
	 * Tracks cursor position and broadcasts to collaboration server
	 * @param {Object} options
	 * @param {WebSocket} options.socket - WebSocket connection
	 * @param {string} options.userId - User identifier
	 * @param {string} options.color - Cursor color
	 */
	function collaborativeCursor({ socket, userId, color }) {
		return (container) => {
			let throttleTimer = null

			function handleMouseMove(event) {
				if (throttleTimer) return

				throttleTimer = setTimeout(() => {
					throttleTimer = null
				}, 50) // Throttle to 20fps

				const rect = container.getBoundingClientRect()
				const x = (event.clientX - rect.left) / rect.width
				const y = (event.clientY - rect.top) / rect.height

				socket.send(
					JSON.stringify({
						type: 'cursor',
						userId,
						position: { x, y },
						color
					})
				)
			}

			function handleMouseLeave() {
				socket.send(
					JSON.stringify({
						type: 'cursor',
						userId,
						position: null
					})
				)
			}

			container.addEventListener('mousemove', handleMouseMove)
			container.addEventListener('mouseleave', handleMouseLeave)

			return () => {
				container.removeEventListener('mousemove', handleMouseMove)
				container.removeEventListener('mouseleave', handleMouseLeave)
				if (throttleTimer) clearTimeout(throttleTimer)
			}
		}
	}

	let socket = $state(null)
	const userId = crypto.randomUUID()
	const cursorColor = `hsl(${Math.random() * 360}, 70%, 50%)`

	onMount(() => {
		socket = new WebSocket('wss://collab.example.com')
		return () => socket.close()
	})
</script>

{#if socket}
	<div
		class="collaboration-area"
		{@attach collaborativeCursor({ socket, userId, color: cursorColor })}
	>
		<!-- Collaborative content -->
	</div>
{/if}

9.4 Validação de Formulário com Feedback Visual

<script>
	/**
	 * Validates input and provides visual feedback
	 * @param {Object} options
	 * @param {(value: string) => string | null} options.validate - Returns error message or null
	 * @param {(isValid: boolean) => void} [options.onValidityChange] - Callback on validity change
	 * @returns {import('svelte/attachments').Attachment<HTMLInputElement>}
	 */
	function validateInput({ validate, onValidityChange }) {
		return (input) => {
			let currentValidity = true
			const errorElement = document.createElement('div')
			errorElement.className = 'validation-error'
			errorElement.setAttribute('role', 'alert')

			function checkValidity() {
				const error = validate(input.value)
				const isValid = error === null

				if (isValid !== currentValidity) {
					currentValidity = isValid
					onValidityChange?.(isValid)
				}

				input.classList.toggle('invalid', !isValid)
				input.setAttribute('aria-invalid', String(!isValid))

				if (error) {
					errorElement.textContent = error
					if (!errorElement.parentElement) {
						input.parentElement?.appendChild(errorElement)
					}
				} else {
					errorElement.remove()
				}
			}

			input.addEventListener('input', checkValidity)
			input.addEventListener('blur', checkValidity)

			// Initial check
			checkValidity()

			return () => {
				input.removeEventListener('input', checkValidity)
				input.removeEventListener('blur', checkValidity)
				errorElement.remove()
			}
		}
	}

	let email = $state('')
	let emailValid = $state(false)

	function validateEmail(value) {
		if (!value) return 'Email is required'
		if (!value.includes('@')) return 'Please enter a valid email'
		if (!value.includes('.')) return 'Please enter a valid email domain'
		return null
	}
</script>

<form>
	<label>
		Email:
		<input
			type="email"
			bind:value={email}
			{@attach validateInput({
				validate: validateEmail,
				onValidityChange: (valid) => (emailValid = valid)
			})}
		/>
	</label>

	<button type="submit" disabled={!emailValid}> Submit </button>
</form>

<style>
	.invalid {
		border-color: red;
	}
	.validation-error {
		color: red;
		font-size: 0.875rem;
		margin-top: 0.25rem;
	}
</style>

10. Padrões Avançados e Considerações Arquiteturais

10.1 Compondo Múltiplos Attachments

Crie attachments de ordem superior que combinam múltiplos comportamentos:

<script>
	import { createAttachmentKey } from 'svelte/attachments'

	/**
	 * Composes multiple attachments into a single props object
	 * @param  {...import('svelte/attachments').Attachment} attachments
	 * @returns {Record<symbol, import('svelte/attachments').Attachment>}
	 */
	function compose(...attachments) {
		return attachments.reduce((props, attachment) => {
			props[createAttachmentKey()] = attachment
			return props
		}, {})
	}

	// Individual attachments
	function logMounts(el) {
		console.log('Mounted:', el)
		return () => console.log('Unmounted:', el)
	}

	function addRipple(el) {
		function createRipple(e) {
			const ripple = document.createElement('span')
			ripple.className = 'ripple'
			ripple.style.left = `${e.offsetX}px`
			ripple.style.top = `${e.offsetY}px`
			el.appendChild(ripple)
			setTimeout(() => ripple.remove(), 600)
		}
		el.addEventListener('click', createRipple)
		return () => el.removeEventListener('click', createRipple)
	}

	// Composed props object
	const interactiveProps = compose(logMounts, addRipple)
</script>

<button {...interactiveProps}> Interactive Button </button>

Quando Usar Composição

Pacotes de comportamento reutilizáveis: Combine funcionalidades relacionadas em uma única prop.
Attachment programático: Ao construir objetos de props dinamicamente em bibliotecas.
Componentes complexos: Onde múltiplos comportamentos são sempre aplicados juntos.

Alternativa: Múltiplas Diretivas `{@attach}`

Para casos simples, múltiplos {@attach} no mesmo elemento costuma ser mais claro e não requer uma função auxiliar:

<div {@attach logMounts} {@attach addRipple}>...</div>

Composição é poderosa para cenários avançados, mas múltiplas diretivas são suficientes para a maioria dos casos de uso.

10.2 Attachments Condicionais

Attachments podem ser aplicados condicionalmente usando expressões ternárias:

<script>
	let enableTracking = $state(true)

	function analyticsTracker(el) {
		// Track interactions
		const handleClick = () => analytics.track('click', { element: el.id })
		el.addEventListener('click', handleClick)
		return () => el.removeEventListener('click', handleClick)
	}

	// No-op attachment for when tracking is disabled
	function noop() {
		return () => {}
	}
</script>

<button id="cta-button" {@attach enableTracking ? analyticsTracker : noop}> Call to Action </button>

10.3 Attachments Cientes de Contexto

Aproveite a API de contexto do Svelte para attachments que precisam de estado compartilhado:

<!-- FormContext.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	const formState = $state({
		fields: {},
		errors: {},
		isSubmitting: false
	})

	setContext('form', {
		registerField(name, validate) {
			formState.fields[name] = { validate, value: '' }
		},
		updateField(name, value) {
			formState.fields[name].value = value
			const error = formState.fields[name].validate?.(value)
			formState.errors[name] = error
		},
		getError(name) {
			return formState.errors[name]
		}
	})
</script>

{@render children()}

<!-- FormField.svelte -->
<script>
	import { getContext } from 'svelte'

	let { name, validate, ...props } = $props()

	const form = getContext('form')

	function formFieldAttachment(input) {
		form.registerField(name, validate)

		function handleInput(e) {
			form.updateField(name, e.target.value)
		}

		input.addEventListener('input', handleInput)

		$effect(() => {
			const error = form.getError(name)
			input.setCustomValidity(error || '')
		})

		return () => {
			input.removeEventListener('input', handleInput)
		}
	}
</script>

<input {name} {...props} {@attach formFieldAttachment} />

10.4 Testando Attachments

Attachments podem ser testados extraindo a lógica central:

// tooltip.js
/**
 * @param {string} content
 * @returns {import('svelte/attachments').Attachment}
 */
export function tooltip(content) {
	return (element) => {
		const tip = createTooltipElement(content)

		const show = () => positionAndShow(tip, element)
		const hide = () => tip.remove()

		element.addEventListener('mouseenter', show)
		element.addEventListener('mouseleave', hide)

		return () => {
			element.removeEventListener('mouseenter', show)
			element.removeEventListener('mouseleave', hide)
			tip.remove()
		}
	}
}

// Internal functions exposed for testing
export function createTooltipElement(content) {
	const tip = document.createElement('div')
	tip.className = 'tooltip'
	tip.textContent = content
	tip.setAttribute('role', 'tooltip')
	return tip
}

export function positionAndShow(tip, anchor) {
	const rect = anchor.getBoundingClientRect()
	tip.style.left = `${rect.left + rect.width / 2}px`
	tip.style.top = `${rect.top - 8}px`
	document.body.appendChild(tip)
}

// tooltip.test.js
import { describe, it, expect, vi } from 'vitest'
import { createTooltipElement, tooltip } from './tooltip.js'

describe('tooltip', () => {
	describe('createTooltipElement', () => {
		it('creates element with correct content', () => {
			const tip = createTooltipElement('Hello')
			expect(tip.textContent).toBe('Hello')
			expect(tip.className).toBe('tooltip')
			expect(tip.getAttribute('role')).toBe('tooltip')
		})
	})

	describe('tooltip attachment', () => {
		it('adds and removes event listeners', () => {
			const element = document.createElement('button')
			const addSpy = vi.spyOn(element, 'addEventListener')
			const removeSpy = vi.spyOn(element, 'removeEventListener')

			const cleanup = tooltip('Test')(element)

			expect(addSpy).toHaveBeenCalledWith('mouseenter', expect.any(Function))
			expect(addSpy).toHaveBeenCalledWith('mouseleave', expect.any(Function))

			cleanup()

			expect(removeSpy).toHaveBeenCalledWith('mouseenter', expect.any(Function))
			expect(removeSpy).toHaveBeenCalledWith('mouseleave', expect.any(Function))
		})
	})
})

11. Armadilhas, Casos Extremos e Anti-Padrões

11.1 Armadilhas de Reatividade

Problema: Rastreamento de dependência não intencional

<script>
	let unrelatedState = $state('hello')
	let targetState = $state('world')

	function myAttachment(el) {
		// BUG: This reads `unrelatedState` creating an unwanted dependency
		console.log('Current unrelated state:', unrelatedState)

		// This is the actual work we want to do
		el.textContent = targetState
	}
</script>

Solução: Use untrack para leituras que não devem criar dependências:

<script>
	import { untrack } from 'svelte'

	let unrelatedState = $state('hello')
	let targetState = $state('world')

	function myAttachment(el) {
		// Now this doesn't create a dependency
		untrack(() => {
			console.log('Current unrelated state:', unrelatedState)
		})

		el.textContent = targetState
	}
</script>

11.2 Vazamentos de Memória por Falta de Limpeza

Problema: Esquecer de limpar assinaturas

<script>
	function leakyAttachment(el) {
		const subscription = someObservable.subscribe((value) => {
			el.textContent = value
		})
		// BUG: No cleanup! Subscription persists after unmount
	}
</script>

Solução: Sempre retorne uma limpeza para assinaturas:

<script>
	function safeAttachment(el) {
		const subscription = someObservable.subscribe((value) => {
			el.textContent = value
		})

		return () => subscription.unsubscribe()
	}
</script>

11.3 Vazamento de Dados Entre Componentes

Problema: Mutar estado compartilhado em attachments

<script>
	// Shared mutable object
	const sharedConfig = { count: 0 }

	function counterAttachment(el) {
		// BUG: Mutating shared state affects all components using this config
		sharedConfig.count += 1
		el.textContent = sharedConfig.count
	}
</script>

Solução: Use estado local ao componente ou padrões imutáveis:

<script>
	function counterAttachment(el) {
		// Local state per attachment instance
		let count = 0

		function increment() {
			count += 1
			el.textContent = String(count)
		}

		el.addEventListener('click', increment)
		return () => el.removeEventListener('click', increment)
	}
</script>

11.4 Loops de Re-execução Infinita

Problema: Escrever em estado que também é lido no mesmo attachment

<script>
	let counter = $state(0)

	function infiniteLoop(el) {
		// BUG: Reads `counter`, then writes to it, triggering re-run
		el.textContent = String(counter)
		counter += 1 // This triggers a re-run!
	}
</script>

Solução: Use efeitos aninhados ou adie as escritas:

<script>
	let counter = $state(0)

	function safeAttachment(el) {
		// Read in outer attachment
		el.textContent = String(counter)

		// Write deferred to next tick
		queueMicrotask(() => {
			counter += 1
		})
	}
</script>

11.5 Considerações sobre Renderização no Lado do Servidor

Attachments só são executados no navegador, não durante o SSR. Isso geralmente é desejável, mas esteja ciente:

<script>
	function browserOnlySetup(el) {
		// This never runs on the server
		// Initial content should be set via regular attributes/content
	}
</script>

<!-- Set initial state declaratively for SSR -->
<div class="widget" data-initialized="false" {@attach browserOnlySetup}>Loading...</div>

12. Estratégias de Otimização de Performance

12.1 Debouncing e Throttling em Attachments

Para eventos de alta frequência, envolva os handlers adequadamente:

<script>
	function throttle(fn, delay) {
		let lastCall = 0
		return (...args) => {
			const now = Date.now()
			if (now - lastCall >= delay) {
				lastCall = now
				fn(...args)
			}
		}
	}

	function scrollTracker(el) {
		const handleScroll = throttle(() => {
			const scrollPercent = el.scrollTop / (el.scrollHeight - el.clientHeight)
			analytics.track('scroll_depth', { percent: Math.round(scrollPercent * 100) })
		}, 100)

		el.addEventListener('scroll', handleScroll, { passive: true })
		return () => el.removeEventListener('scroll', handleScroll)
	}
</script>

12.2 Inicialização Lazy

Adie operações custosas até que sejam realmente necessárias:

<script>
	function lazyChart(getData) {
		return (canvas) => {
			let chart = null

			const observer = new IntersectionObserver((entries) => {
				if (entries[0].isIntersecting && !chart) {
					// Only initialize when visible
					import('chart.js').then(({ Chart, registerables }) => {
						Chart.register(...registerables)
						chart = new Chart(canvas, {
							type: 'line',
							data: getData()
						})
					})
					observer.disconnect()
				}
			})

			observer.observe(canvas)

			return () => {
				observer.disconnect()
				chart?.destroy()
			}
		}
	}
</script>

12.3 Agrupando Operações de DOM

Minimize o layout thrashing agrupando leituras e escritas:

<script>
	function efficientLayout(el) {
		function updateLayout() {
			// Batch all reads first
			const width = el.offsetWidth
			const height = el.offsetHeight
			const parentWidth = el.parentElement?.offsetWidth ?? 0

			// Then batch all writes
			requestAnimationFrame(() => {
				el.style.transform = `scale(${parentWidth / width})`
				el.dataset.aspectRatio = String(width / height)
			})
		}

		const resizeObserver = new ResizeObserver(updateLayout)
		resizeObserver.observe(el)
		resizeObserver.observe(el.parentElement)

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

Conclusão: O Futuro da Interação com o DOM no Svelte

A diretiva {@attach ...} do Svelte 5 representa mais do que uma melhoria sintática em relação às actions — ela incorpora uma mudança filosófica em direção à reatividade unificada. Ao ser executado dentro de efeitos, os attachments herdam todos os benefícios do sistema reativo do Svelte: rastreamento automático de dependências, atualizações em lote eficientes e semântica de limpeza intuitiva.

Ao adotar attachments em sua base de código, lembre-se destes princípios fundamentais:

Adote o padrão factory para attachments parametrizados
Use efeitos aninhados para controle de reatividade refinado
Sempre considere a limpeza para assinaturas e event listeners
Aproveite o espalhamento de props para composição de componentes
Migre de forma incremental usando fromAction para bibliotecas existentes

A transição de actions para attachments não é apenas sobre nova sintaxe — é sobre pensar em termos de efeitos reativos em vez de callbacks imperativos. Essa mudança de modelo mental, uma vez internalizada, faz com que interações complexas com o DOM pareçam naturais e fáceis de manter.

À medida que o ecossistema Svelte continua a evoluir, espere que autores de bibliotecas adotem attachments por sua superior capacidade de composição. A habilidade de passar comportamentos de DOM através de hierarquias de componentes via espalhamento de props abre novas possibilidades para a construção de sistemas de componentes verdadeiramente encapsulados e reutilizáveis.

Referência: Resumo da API

Sintaxe de Template

<!-- Basic attachment -->
<div {@attach myAttachment}>...</div>

<!-- Factory pattern -->
<div {@attach tooltip('Hello')}>...</div>

<!-- Inline attachment -->
<div
	{@attach (el) => {
		/* setup */ return () => {
			/* cleanup */
		}
	}}
>
	...
</div>

<!-- Multiple attachments -->
<div {@attach a} {@attach b} {@attach c}>...</div>

<!-- On components (spreads to inner element) -->
<Component {@attach myAttachment}>...</Component>

Exportações do Módulo (`svelte/attachments`)

// Create Symbol keys for programmatic attachments
function createAttachmentKey(): symbol

// Convert actions to attachments
function fromAction<E extends EventTarget, T>(action: Action<E, T>, fn: () => T): Attachment<E>

function fromAction<E extends EventTarget>(action: Action<E, void>): Attachment<E>

// Type definition
interface Attachment<T extends EventTarget = Element> {
	(element: T): void | (() => void)
}

Conclusão

A diretiva {@attach} representa a abordagem moderna do Svelte 5 para extensão de comportamento em nível de elemento, combinando a flexibilidade do sistema legado de ações use: com suporte de primeira classe aos primitivos reativos do Svelte. Ao permitir definições de attachment inline, reatividade completa dentro das funções de attachment e composição fluida de múltiplos attachments, ela transforma a augmentação de elementos de um padrão imperativo em um paradigma declarativo e reativo que se encaixa naturalmente no modelo de componentes do Svelte.

Dominar o {@attach} exige compreender tanto suas capacidades quanto seus casos de uso adequados. Ele se destaca em comportamentos específicos de elementos — tooltips, detecção de clique fora, arrastar e soltar, melhorias de acessibilidade — complementando, em vez de substituir, os hooks de ciclo de vida, $effect e manipuladores de eventos em seus respectivos domínios. O caminho de migração via fromAction garante compatibilidade retroativa com o ecossistema, enquanto a natureza reativa dos attachments e os padrões de composição abrem novas possibilidades arquiteturais para a construção de comportamentos de elementos reutilizáveis e de fácil manutenção.

Principais Conclusões

{@attach} fornece extensão de comportamento em nível de elemento introduzida no Svelte 5.29, vinculando funções a elementos do DOM com gerenciamento automático de ciclo de vida (configuração na montagem, limpeza na desmontagem)
Reatividade completa dentro dos attachments - closures capturam estado reativo e são reexecutadas quando as dependências mudam, diferentemente das ações legadas use:, que precisam de chamadas manuais de atualização
A sintaxe suporta funções inline e referências - {@attach (el) => { ... }} para definições inline ou {@attach myAttachment} para referências reutilizáveis
Retorne uma função de limpeza para o teardown - retorne () => {} dos attachments para gerenciar a remoção de listeners de eventos, limpeza de timers e descarte de recursos
Múltiplos attachments se compõem de forma fluida com a sintaxe {@attach a} {@attach b} {@attach c}, sendo executados em ordem durante a montagem e em ordem inversa durante a desmontagem
O uso em componentes é propagado para o elemento interno - <Component {@attach myAttachment}> aplica o attachment ao elemento DOM raiz do componente, não à instância do componente
O helper de migração fromAction converte ações legadas use: em attachments com fromAction(action) para ações sem parâmetros ou fromAction(action, () => params) para as parametrizadas
Suporte a TypeScript com a interface Attachment<T> fornece segurança de tipos para tipos de elementos, com restrições genéricas garantindo que os attachments sejam aplicados apenas a alvos compatíveis

Veja Também

Documentação Oficial do Svelte 5 - {@attach}
Ações do Svelte (Legado) - A diretiva use: que o {@attach} substitui
Módulo svelte/attachments - Utilitários fromAction e createAttachmentKey
$effect - Efeitos colaterais reativos em nível de componente
Manipuladores de Eventos de Elemento - Os atributos on* para tratamento de eventos
Hooks de Ciclo de Vida - onMount e onDestroy para o ciclo de vida do componente
TypeScript com Svelte - Definições de attachment com segurança de tipos

Este artigo foi escrito para o Svelte 5.29+. Consulte sempre a documentação oficial do Svelte para obter os detalhes mais atuais da API e as melhores práticas.