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

Svelte siempre ha defendido la filosofía de escribir menos código mientras se logra más. Desde sus inicios, el framework proporcionó la directiva use: (acciones) como el mecanismo principal para interactuar de manera imperativa con elementos del DOM—adjuntar librerías de terceros, gestionar el foco, implementar arrastrar y soltar, y otros escenarios donde las plantillas declarativas resultan insuficientes.

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 en cierta medida fuera del paradigma reactivo de Svelte. Recibían actualizaciones a través de un callback update explícito, lo que creaba una desconexión en el modelo mental con respecto al sistema de reactividad push-pull 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 perfectamente 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 la forma en que estructuramos librerías de componentes, gestionamos interacciones complejas con el DOM y razonamos sobre la reactividad a través de los límites de los componentes.

Este tutorial asume familiaridad con las runes de Svelte 5 ($state, $derived, $effect, $props) y una comprensión sólida de los fundamentos de JavaScript, incluyendo Proxies, Symbols y el event loop. Construiremos progresivamente desde 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 ese 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 crucial** para dominar su comportamiento. Consideremos 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 desactualizado
Invoca la función de limpieza (si se proporcionó)
Re-ejecuta la función del attachment
Rastrea cualquier nueva dependencia leída durante la ejecución

Esto refleja exactamente cómo funciona $effect en otras partes 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 las 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 de manera efectiva.

¿Qué Eran las Acciones?

Las acciones eran el mecanismo inicial de Svelte para adjuntar comportamiento imperativo a los elementos del DOM. Seguían un patrón de actualización imperativa 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 en cierta medida fuera del paradigma reactivo de Svelte, creando una desconexión con el sistema de reactividad push-pull del framework.

¿Qué Son los Attachments?

Los attachments son el enfoque moderno, integrado con las 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 attachments es declarativo sobre qué sucede (el cuerpo de la función) mientras Svelte se encarga de cuándo sucede (rastreo de dependencias y programació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: todavía son compatibles y pueden ser útiles para:

Bases de código heredadas que migran de forma gradual.
Acciones que necesitan funcionar en diferentes versiones de Svelte o incluso en otros frameworks (aunque es poco frecuente).
Escenarios complejos donde el control manual sobre 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 perfectamente 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)} utiliza una factory para un 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 uso único.

<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 expanden {...props} (rest props).

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

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

Pasar Opciones a los Attachments

Si bien 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 que los attachments sean parametrizados sin cambiar la firma principal (element).

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 desde la programación imperativa hacia la reactividad declarativa. En el modelo de acciones, los desarrolladores debían anticipar y gestionar manualmente los cambios de parámetros, lo que a menudo generaba una gestión de estado compleja y posibles errores por actualizaciones omitidas. Los attachments, por el contrario, adoptan el paradigma reactivo de Svelte: describes el comportamiento deseado y el framework se asegura de que permanezca sincronizado con los datos.

Beneficios de los Attachments sobre las Acciones

Menos Código Repetitivo: 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 según las lecturas reactivas.
Sistema de Efectos Unificado: Los attachments se comportan como $effect, haciendo que el código sea más consistente.
Pruebas más Sencillas: Como los attachments son simplemente funciones, pueden probarse de forma unitaria de manera aislada.
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 un 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 cantidad 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
Gestiona 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 directos funcionan bien para comportamientos estáticos, pero las aplicaciones reales requieren parametrización. Una factory de attachments 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 factory con valores reactivos, la expresión completa se re-evalúa 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 arrow functions 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 necesidad de pasar parámetros.
Prototipado rápido: Ideal para comportamientos simples y no reutilizables.

Cuándo Usar Attachments con Nombre en su Lugar

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

Los attachments inline destacan en interacciones ligeras y específicas de un componente, mientras que los attachments con nombre 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 más 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 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 Props Basado en Símbolos

Una de las características más poderosas de los attachments es su capacidad de atravesar los límites de los componentes mediante la propagación de props. Cuando usas {@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 Internamente

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

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

Este mecanismo hace que los componentes contenedores "simplemente funcionen" 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 Contenedores 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 contenedores:

<!-- 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 sobre el elemento raíz, cualquier attachment pasado a <Card> se aplica automáticamente al elemento <article>.

6. Controlar la Re-ejecución de los Attachments

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

Por defecto, 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 vuelve a ejecutar—claramente indeseable.

Entendiendo 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 ejecutándose innecesariamente.
Fallas visuales: Bibliotecas reinicializándose, causando parpadeos.
Fugas de recursos: Limpieza incompleta por re-ejecuciones rápidas.
Comportamiento inesperado: Estado no preservado entre ejecuciones.

Cuando surgen estos problemas, el patrón getter proporciona 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 sola vez
veryExpensiveSetupWork se ejecuta una sola vez al montar
El $effect anidado se ejecuta cada vez que bar cambia

6.3 Ejemplo Práctico: Integración de Biblioteca de Gráficos

Considera integrar una biblioteca 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 forma programática, especialmente en código de biblioteca 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 Desarrollo de Bibliotecas

Este patrón brilla cuando se construyen bibliotecas 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 proporciona fromAction para convertir actions existentes en attachments, habilitando la migración gradual e interoperabilidad con bibliotecas 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 devuelva el parámetro, no el parámetro en sí. Esto garantiza el seguimiento correcto de la reactividad.

8.2 ¿Por Qué Migrar? La Ventaja de Composabilidad

Si bien las actions siguen funcionando, 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: Sin callback update separado que mantener
Integración con effects: Se puede usar $effect internamente para un control detallado

<!-- 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 bibliotecas - 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 Reales 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: Cuando se construyen 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, usar 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 consciencia 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 principal:

// 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 límite 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 deberían 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 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 al 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 diferir 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 el renderizado del lado del servidor

Los attachments solo se ejecutan en el navegador, no durante el SSR. Esto es generalmente deseable, pero hay que tenerlo 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 apropiadamente:

<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

Aplaza 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 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 adoptes 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 grano fino
Considera siempre la limpieza para suscripciones y escuchadores de eventos
Aprovecha el spreading de props para la composición de componentes
Migra de forma incremental usando fromAction para las librerías existentes

La transición de acciones a attachments no se trata únicamente de nueva sintaxis, sino de pensar en términos de efectos reactivos en lugar de callbacks imperativos. Este cambio de modelo mental, una vez interiorizado, hace que las interacciones complejas con el DOM se sientan naturales y fáciles de mantener.

A medida que el ecosistema de Svelte continúa evolucionando, es de esperar 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 el spreading de props abre nuevas posibilidades para construir sistemas de componentes verdaderamente encapsulados y reutilizables.

Referencia: Resumen de 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 los primitivos reactivos de Svelte. Al permitir definiciones de attachments en línea, reactividad completa dentro de las funciones de attachment y composición fluida de múltiples attachments, transforma la extensión 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 externos, arrastrar y soltar, mejoras de accesibilidad— mientras complementa, 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 la compatibilidad con versiones anteriores del 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} proporciona 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 - las clausuras capturan el estado reactivo y se vuelven a ejecutar cuando las dependencias cambian, a diferencia de las acciones use: heredadas que requieren llamadas de actualización manuales
La sintaxis admite 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 - retorna () => {} desde los attachments para manejar la eliminación de oyentes de eventos, limpieza de temporizadores y liberación de recursos
Múltiples attachments se componen sin problemas 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 propaga al elemento interno - <Component {@attach myAttachment}> aplica el attachment al elemento DOM raíz 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> proporciona seguridad de tipos para tipos de elementos, con restricciones genéricas que garantizan que los attachments solo se apliquen a destinos 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+. Consulta siempre la documentación oficial de Svelte para conocer los detalles más actuales de la API y las mejores prácticas.