La Evolución de la Interacción con el DOM en Svelte

Svelte siempre ha defendido la filosofía de escribir menos código logrando más. Desde sus inicios, el framework proporcionó la directiva use: (acciones) como mecanismo principal para interactuar de forma imperativa con elementos del DOM—adjuntando librerías de terceros, gestionando el foco, implementando drag-and-drop y otros escenarios donde las plantillas declarativas quedan cortas.

Sin embargo, a medida que Svelte evolucionó hacia su arquitectura reactiva basada en runes en la versión 5, surgió una tensión fundamental. Las acciones, aunque poderosas, operaban de cierta forma fuera del paradigma reactivo de Svelte. Recibían actualizaciones a través de un callback update explícito, creando una desconexión en el modelo mental respecto al sistema de reactividad del resto del framework.

Attachments

Svelte 5.29 introduce los attachments—un enfoque reimaginado para la interacción imperativa con el DOM que se integra de forma transparente con el sistema de efectos de Svelte. Los attachments se ejecutan dentro de efectos, rastreando automáticamente las dependencias reactivas y volviendo a ejecutarse cuando esas dependencias cambian.

Este cambio, aparentemente simple, tiene implicaciones profundas en cómo arquitecturamos bibliotecas de componentes, gestionamos interacciones complejas con el DOM y razonamos sobre la reactividad entre límites de componentes.

Este tutorial asume familiaridad con los runes de Svelte 5 ($state, $derived, $effect, $props) y un sólido conocimiento de los fundamentos de JavaScript, incluyendo Proxies, Symbols y el event loop. Construiremos de forma progresiva desde los conceptos fundamentales hasta patrones arquitectónicos avanzados, examinando no solo cómo usar los attachments, sino por qué representan un avance significativo en el modelo de componentes de Svelte.

1. El Nivel Conceptual

1.1 ¿Qué es un Attachment?

En esencia, un attachment es una función que recibe un elemento del DOM cuando dicho elemento se monta en el DOM. La función se ejecuta dentro de un contexto de efecto, lo que significa que cualquier estado reactivo leído durante la ejecución se convierte en una dependencia—cuando ese estado cambia, el attachment se vuelve a ejecutar automáticamente.

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

Esta firma de tipo revela el contrato esencial:

El attachment recibe un elemento
Opcionalmente retorna una función de limpieza
La limpieza se ejecuta antes de la re-ejecución o cuando el elemento se desmonta

1.2 El Modelo de Ejecución Basado en Efectos

**Comprender que los attachments se ejecutan dentro de efectos es fundamental** para dominar su comportamiento. Considera las implicaciones:

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

Cuando color o size cambian, el sistema reactivo de Svelte:

Marca el attachment como sucio
Invoca la función de limpieza (si se proporcionó)
Re-ejecuta la función del attachment
Rastrea las nuevas dependencias leídas durante la ejecución

Esto refleja exactamente cómo funciona $effect en el resto de Svelte 5, creando un modelo mental unificado para los efectos secundarios reactivos.

1.3 Attachments vs. Acciones: Un Cambio Filosófico

En la evolución de Svelte, la directiva use: (acciones) representó el enfoque original para las interacciones imperativas con el DOM. Con la introducción de los runes en Svelte 5, los attachments ({@attach ...}) ofrecen una forma más integrada de manejar dichas interacciones. Esta sección explora el cambio filosófico de las acciones a los attachments, detallando qué es cada uno, cuándo usarlos y cómo aplicarlos efectivamente.

¿Qué Eran las Acciones?

Las acciones eran el mecanismo inicial de Svelte para adjuntar comportamiento imperativo a elementos del DOM. Seguían un patrón de actualización imperativo donde los desarrolladores gestionaban manualmente los cambios de estado a través de un 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>

Este patrón requería que los desarrolladores:

Gestionaran manualmente las actualizaciones en un callback separado
Rastrearan qué parámetros cambiaron
Implementaran actualizaciones diferenciales para evitar trabajo redundante

Las acciones operaban de cierta forma fuera del paradigma reactivo de Svelte, creando una desconexión con el sistema de reactividad del framework.

¿Qué Son los Attachments?

Los attachments son el enfoque moderno, integrado con runes, para las interacciones con el DOM. Se ejecutan dentro del sistema de efectos de Svelte, rastreando automáticamente las dependencias reactivas y volviendo a ejecutarse cuando esas dependencias cambian:

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

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

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

El enfoque de los attachments es declarativo sobre qué ocurre (el cuerpo de la función) mientras Svelte se encarga de cuándo ocurre (rastreo de dependencias y planificación).

Cuándo Usar Acciones vs. Attachments

Si bien @attach es el enfoque preferido para el nuevo código en Svelte 5, las acciones use: siguen siendo compatibles y pueden ser útiles para:

Bases de código heredadas que migran gradualmente.
Acciones que necesitan funcionar en distintas versiones de Svelte o incluso en otros frameworks (aunque es poco frecuente).
Escenarios complejos donde el control manual de las actualizaciones es beneficioso.

Para nuevas interacciones imperativas con el DOM en Svelte 5, se prefiere @attach para alinearse con la filosofía reactiva del framework y reducir la carga cognitiva.

Cómo Usar los Attachments

Los attachments son funciones que reciben un elemento del DOM y opcionalmente retornan una función de limpieza. Se integran de forma transparente con la reactividad de Svelte:

Uso básico: {@attach myFunction} adjunta una función simple.

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

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

Parametrizado: {@attach factory(param)} usa una factory para comportamiento dinámico.

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

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

En línea: {@attach (el) => { /* setup */ return () => { /* cleanup */ } }} para lógica de un solo uso.

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

Múltiples: Aplica varios attachments al mismo elemento para comportamientos combinados.

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

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

Componentes: Los attachments se propagan a través de componentes que distribuyen {...props} (rest props).

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

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

Pasar Opciones a los Attachments

Aunque los attachments en sí mismos solo reciben el elemento, usa factories para inyectar opciones o 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>

Este patrón permite parametrizar los attachments sin cambiar la firma (element) principal.

Cómo Migrar desde Acciones

Para las acciones existentes, usa fromAction para convertirlas en 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 acciones personalizadas, reescríbelas como attachments nativos eliminando el callback update y aprovechando las lecturas reactivas directamente en el cuerpo de la función.

El Cambio Filosófico en Detalle

Este cambio representa un movimiento de la programación imperativa hacia la reactividad declarativa. En el modelo de acciones, los desarrolladores tenían que anticipar y manejar manualmente los cambios de parámetros, lo que a menudo llevaba a una gestión de estado compleja y posibles errores por actualizaciones omitidas. Los attachments, en cambio, abrazan el paradigma reactivo de Svelte: describes el comportamiento deseado y el framework se asegura de que permanezca sincronizado con los datos.

Ventajas de los Attachments Sobre las Acciones

Menor Boilerplate: No se necesitan métodos update y destroy separados; todo está en una sola función.
Rastreo Automático de Dependencias: Svelte sabe automáticamente cuándo volver a ejecutar el attachment basándose en las lecturas reactivas.
Sistema de Efectos Unificado: Los attachments se comportan como $effect, haciendo el código más consistente.
Pruebas más Sencillas: Como los attachments son solo funciones, pueden probarse de forma unitaria en aislamiento.
Mejor Rendimiento: Menos sobrecarga por verificaciones manuales de actualización; el planificador de Svelte optimiza las re-ejecuciones.

2. Patrones Fundamentales y Sintaxis

2.1 Declaración Básica de Attachment

El attachment más simple es una función que realiza la configuración cuando un elemento se monta:

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

Los usuarios de TypeScript se benefician del tipo Attachment exportado desde svelte/attachments, que proporciona tipado correcto para el parámetro del elemento y el tipo de retorno.

2.2 Funciones de Limpieza: El Contrato del Valor de Retorno

Retornar una función de limpieza es opcional, pero esencial para:

Eliminar event listeners
Cancelar temporizadores o animaciones
Desechar instancias de bibliotecas de terceros
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últiples Attachments en un Solo Elemento

Los elementos pueden recibir cualquier número de attachments, cada uno operando de forma independiente:

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

Tiene su propio contexto de efecto
Rastrea sus propias dependencias
Administra su propio ciclo de vida de limpieza

3. Factories de Attachments—Interacción con el DOM Parametrizada

3.1 El Patrón Factory Explicado

Los attachments sin parámetros funcionan bien para comportamientos estáticos, pero las aplicaciones reales requieren parametrización. Una factory de attachment es una función que retorna un attachment, lo que permite pasar configuración:

<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 Reactividad en Factories: Entendiendo la Re-ejecución

Al usar patrones de factory con valores reactivos, la expresión completa se vuelve a evaluar cuando las dependencias cambian:

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

Esta re-creación automática es el comportamiento predeterminado. Para muchos casos de uso—especialmente operaciones ligeras—esto es perfectamente aceptable. Sin embargo, para operaciones de configuración costosas, necesitamos un control más preciso.

3.3 Ejemplo de Factory en el Mundo Real: Integración con Floating UI

Construyamos una factory de tooltips lista para producción usando Floating UI para el posicionamiento:

<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—Cuando la Brevedad Gana

4.1 Sintaxis Inline para Casos Simples

Para attachments simples y de un solo uso, las funciones de flecha inline eliminan el código repetitivo:

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

Ventajas de los Attachments Inline

Sin definición de función separada: Mantiene la lógica cerca de la plantilla.
Contexto inmediato: Acceso a variables locales sin pasar parámetros.
Prototipado rápido: Ideal para comportamientos simples y no reutilizables.

Cuándo Usar Attachments Nombrados en su Lugar

Reutilización: Si la lógica se usa en múltiples lugares.
Complejidad: Para attachments con configuración o limpieza significativas.
Testing: Las funciones nombradas son más fáciles de testear unitariamente.
Legibilidad: Para lógica más extensa, las funciones nombradas mejoran la organización del código.

Los attachments inline brillan para interacciones ligeras y específicas de un componente, mientras que los attachments nombrados son mejores para comportamientos compartidos o complejos.

4.2 Efectos Anidados Dentro de Attachments Inline

Los attachments inline pueden aprovechar llamadas $effect anidadas para un control de reactividad de grano fino:

<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 patrón demuestra una técnica de optimización crucial: el attachment externo se ejecuta una sola vez para la configuración costosa, mientras que los efectos anidados manejan las actualizaciones reactivas granulares.

5. Pasar Attachments a Componentes

5.1 El Mecanismo de Prop Basado en Símbolos

Una de las características más poderosas de los attachments es su capacidad de pasar a través de los límites de los componentes mediante la propagación de props. Cuando se usa {@attach ...} en un componente, Svelte crea una prop con una clave 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 Cómo Funciona Esto Internamente

Cuando se usa {@attach fn} en un componente:

Svelte genera un Symbol único
La función de attachment se asigna a ese key de Symbol en el objeto de props
Cuando las props se propagan a un elemento, Svelte reconoce el Symbol y adjunta la función

Este mecanismo significa que los componentes wrapper "simplemente funcionan" sin reenvío 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 Construir Componentes Wrapper que Preserven los Attachments

Un patrón crítico para los autores de bibliotecas de componentes es asegurarse de que los attachments fluyan a través de los 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>

Al usar rest props (...props) y propagarlos al elemento raíz, cualquier attachment pasado a <Card> se aplica automáticamente al elemento <article>.

6. Controlar la Re-ejecución de Attachments

6.1 El Desafío de la Re-ejecución

De forma predeterminada, los attachments se vuelven a ejecutar cada vez que cambia alguna dependencia. Para operaciones costosas, esto puede 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>

Cada vez que bar cambia, veryExpensiveSetupWork se ejecuta nuevamente—claramente indeseable.

Comprendiendo los Disparadores de Re-ejecución

La re-ejecución ocurre cuando:

El estado reactivo leído durante la ejecución del attachment cambia.
La fábrica de attachment es llamada con nuevos parámetros (recreando la función de attachment).
El componente vuelve a montar el elemento.

Señales de que la Re-ejecución es un Problema

Problemas de rendimiento: Configuración costosa que se ejecuta innecesariamente.
Fallas visuales: Librerías que se reinicializan, causando parpadeos.
Fugas de recursos: Limpieza incompleta por re-ejecuciones rápidas.
Comportamiento inesperado: Estado no preservado entre re-ejecuciones.

Cuando surgen estos problemas, el patrón getter provee una solución.

6.2 El Patrón Getter para Lectura Diferida

La solución es pasar una función getter en lugar del valor directamente, difiriendo la lectura reactiva a un efecto anidado:

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

Ahora:

expensiveSetup(() => bar) crea el attachment una vez
veryExpensiveSetupWork se ejecuta una vez al montar
El $effect anidado se ejecuta cada vez que bar cambia

6.3 Ejemplo Práctico: Integración de Librería de Gráficos

Considera la integración de una librería de gráficos donde la inicialización es costosa:

<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. Creación Programática de Attachments

7.1 La Función `createAttachmentKey`

A veces necesitas crear attachments de manera programática—especialmente en código de librería donde estás construyendo objetos de props dinámicamente. La función createAttachmentKey de svelte/attachments genera claves Symbol reconocidas por el mecanismo de spreading de 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 en el Desarrollo de Librerías

Este patrón destaca cuando se construyen librerías de componentes que necesitan adjuntar comportamiento dinámicamente:

<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últiples Attachments Programáticos

Puedes incluir múltiples attachments en un único objeto de props llamando a createAttachmentKey() varias veces:

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

8.1 La Utilidad `fromAction`

Svelte provee fromAction para convertir actions existentes en attachments, habilitando la migración gradual e interoperabilidad con librerías basadas en 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 crítica: El segundo argumento debe ser una función que retorne el parámetro, no el parámetro en sí. Esto asegura un seguimiento correcto de la reactividad.

8.2 ¿Por Qué Migrar? La Ventaja de la Composabilidad

Si bien las actions aún funcionan, los attachments ofrecen una composabilidad superior:

Paso a través de componentes: Los attachments pasan a través de los límites de componentes mediante spreading
Reactividad unificada: No hay un callback update separado que mantener
Integración con efectos: Pueden usar $effect internamente para un control más preciso

<!-- 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 Estrategia de Migración para Bases de Código Existentes

Para bases de código grandes con muchas actions, migra de forma incremental:

Identificar patrones de uso de actions - catalogar todas las actions
Envolver actions críticas de librerías - usar fromAction para código de terceros
Reescribir actions personalizadas - convertir tus propias actions a attachments nativos
Actualizar interfaces de componentes - asegurarse de que los componentes wrapper hagan 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>

Errores Comunes en la Migración

Olvidar el getter: Usar fromAction(action, param) en lugar de fromAction(action, () => param).
Limpieza faltante: Las actions con limpieza manual necesitan un manejo adecuado de destroy.
Límites de componentes: Las actions no pasan a través de componentes a menos que se haga spread.
Diferencias de reactividad: Los attachments rastrean dependencias automáticamente, a diferencia de las actualizaciones manuales de las actions.

Probando tu Migración

Asegúrate de que los attachments se comporten de manera idéntica a las actions.
Prueba la reactividad: los cambios deben disparar actualizaciones sin llamadas manuales a update.
Verifica la limpieza: sin fugas de memoria ni efectos persistentes.
Comprueba el paso a través de componentes: los attachments deben funcionar en componentes wrapper.

9. Casos de Uso del Mundo Real y Patrones

9.1 Sistema de Gestión de Foco

Gestionar el foco es fundamental para la accesibilidad. Aquí hay un attachment completo de trampa 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 Carga Diferida

<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 Colaboración en Tiempo 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 Validación de Formularios con Retroalimentación 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. Patrones Avanzados y Consideraciones Arquitectónicas

10.1 Composición de Múltiples Attachments

Crea attachments de orden superior que combinen múltiples comportamientos:

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

Cuándo Usar la Composición

Paquetes de comportamiento reutilizables: Combina funcionalidades relacionadas en una sola prop.
Attachment programático: Al construir objetos de props dinámicamente en librerías.
Componentes complejos: Donde múltiples comportamientos siempre se aplican juntos.

Alternativa: Múltiples Directivas `{@attach}`

Para casos simples, múltiples {@attach} en el mismo elemento suele ser más claro y no requiere una función auxiliar:

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

La composición es poderosa para escenarios avanzados, pero múltiples directivas son suficientes para la mayoría de los casos de uso.

10.2 Attachments Condicionales

Los attachments pueden aplicarse condicionalmente usando expresiones ternarias:

<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 con Conciencia del Contexto

Aprovecha la API de contexto de Svelte para attachments que necesitan estado compartido:

<!-- 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 Pruebas de Attachments

Los attachments pueden probarse extrayendo la 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. Errores Comunes, Casos Extremos y Anti-Patrones

11.1 Trampas de Reactividad

Problema: Seguimiento de dependencias no deseado

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

Solución: Usa untrack para lecturas que no deben crear dependencias:

<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 Fugas de Memoria por Falta de Limpieza

Problema: Olvidar limpiar las suscripciones

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

Solución: Siempre retorna la limpieza para las suscripciones:

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

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

11.3 Filtración de Datos entre Componentes

Problema: Mutar estado compartido en 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>

Solución: Usa estado local del componente o patrones inmutables:

<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 Bucles de Re-ejecución Infinita

Problema: Escribir en estado que también se lee en el mismo 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>

Solución: Usa efectos anidados o difiere las escrituras:

<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 Consideraciones sobre Renderizado en el Servidor

Los attachments solo se ejecutan en el navegador, no durante el SSR. Esto suele ser deseable, pero ten en cuenta:

<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. Estrategias de Optimización de Rendimiento

12.1 Debouncing y Throttling en Attachments

Para eventos de alta frecuencia, envuelve los manejadores de manera apropiada:

<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 Inicialización Diferida

Pospón las operaciones costosas hasta que realmente sean necesarias:

<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 Agrupación de Operaciones del DOM

Minimiza el layout thrashing agrupando lecturas y escrituras:

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

Conclusión: El Futuro de la Interacción con el DOM en Svelte

La directiva {@attach ...} de Svelte 5 representa más que una mejora sintáctica sobre las acciones—encarna un cambio filosófico hacia una reactividad unificada. Al ejecutarse dentro de efectos, los attachments heredan todos los beneficios del sistema reactivo de Svelte: seguimiento automático de dependencias, actualizaciones agrupadas eficientes y semántica de limpieza intuitiva.

A medida que adoptas los attachments en tu base de código, recuerda estos principios clave:

Adopta el patrón factory para attachments parametrizados
Usa efectos anidados para un control de reactividad de granularidad fina
Considera siempre la limpieza para suscripciones y listeners de eventos
Aprovecha el prop spreading para la composición de componentes
Migra de forma incremental usando fromAction para librerías existentes

La transición de acciones a attachments no se trata simplemente de una nueva sintaxis—se trata de pensar en términos de efectos reactivos en lugar de callbacks imperativos. Este cambio de modelo mental, una vez internalizado, hace que las interacciones complejas con el DOM se sientan naturales y mantenibles.

A medida que el ecosistema de Svelte continúa evolucionando, espera que los autores de librerías adopten los attachments por su superior componibilidad. La capacidad de pasar comportamientos del DOM a través de jerarquías de componentes mediante prop spreading abre nuevas posibilidades para construir sistemas de componentes verdaderamente encapsulados y reutilizables.

Referencia: Resumen de la API

Sintaxis de Plantillas

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

Exportaciones del 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)
}

Conclusión

La directiva {@attach} representa el enfoque moderno de Svelte 5 para la extensión de comportamiento a nivel de elemento, combinando la flexibilidad del sistema de acciones use: heredado con soporte de primera clase para las primitivas reactivas de Svelte. Al habilitar definiciones de attachment en línea, reactividad completa dentro de las funciones de attachment y composición fluida de múltiples attachments, transforma el enriquecimiento de elementos de un patrón imperativo a un paradigma declarativo y reactivo que se siente natural dentro del modelo de componentes de Svelte.

Dominar {@attach} requiere comprender tanto sus capacidades como sus casos de uso apropiados. Sobresale en comportamientos específicos de elementos —tooltips, detección de clics fuera, arrastrar y soltar, mejoras de accesibilidad— complementando en lugar de reemplazar los hooks de ciclo de vida, $effect y los manejadores de eventos en sus respectivos dominios. La ruta de migración fromAction garantiza compatibilidad retroactiva con el ecosistema, mientras que la naturaleza reactiva del attachment y los patrones de composición abren nuevas posibilidades arquitectónicas para construir comportamientos de elementos reutilizables y mantenibles.

Puntos Clave

{@attach} provee extensión de comportamiento a nivel de elemento introducida en Svelte 5.29, vinculando funciones a elementos del DOM con gestión automática del ciclo de vida (configuración al montar, limpieza al desmontar)
Reactividad completa dentro de los attachments - los closures capturan estado reactivo y se vuelven a ejecutar cuando las dependencias cambian, a diferencia de las acciones use: heredadas que necesitan llamadas de actualización manuales
La sintaxis soporta funciones en línea y referencias - {@attach (el) => { ... }} para definiciones en línea o {@attach myAttachment} para referencias reutilizables
Retornar una función de limpieza para el desmontaje - retornar () => {} desde los attachments para manejar la eliminación de event listeners, limpieza de temporizadores y disposición de recursos
Múltiples attachments se componen fluidamente con la sintaxis {@attach a} {@attach b} {@attach c}, ejecutándose en orden durante el montaje y en orden inverso durante el desmontaje
El uso en componentes se aplica al elemento interno - <Component {@attach myAttachment}> aplica el attachment al elemento raíz del DOM del componente, no a la instancia del componente
El helper de migración fromAction convierte acciones use: heredadas a attachments con fromAction(action) para acciones sin parámetros o fromAction(action, () => params) para las parametrizadas
Soporte de TypeScript con la interfaz Attachment<T> provee seguridad de tipos para los tipos de elementos, con restricciones genéricas que garantizan que los attachments solo se apliquen a objetivos compatibles

Ver También

Documentación Oficial de Svelte 5 - {@attach}
Acciones de Svelte (Heredadas) - La directiva use: que {@attach} reemplaza
Módulo svelte/attachments - Utilidades fromAction y createAttachmentKey
$effect - Efectos secundarios reactivos a nivel de componente
Manejadores de Eventos de Elementos - Los atributos on* para el manejo de eventos
Hooks de Ciclo de Vida - onMount y onDestroy para el ciclo de vida a nivel de componente
TypeScript con Svelte - Definiciones de attachments con seguridad de tipos

Este artículo fue escrito para Svelte 5.29+. Siempre consulta la documentación oficial de Svelte para obtener los detalles más actualizados de la API y las mejores prácticas.