El Problema de Configuración del Compilador a Nivel de Componente

Al construir aplicaciones Svelte sofisticadas, inevitablemente te encontrarás con situaciones donde la configuración global del compilador no se adapta del todo a las necesidades de cada componente. Quizás estés construyendo una librería de componentes que debe funcionar independientemente de cómo estén configurados los proyectos que la consumen. Tal vez necesites compilar un componente específico como Web Component para usarlo en una aplicación JavaScript vanilla. O puede que estés trabajando con gráficos SVG que requieren un namespace de renderizado diferente al de tus componentes HTML.

El elemento especial <svelte:options> existe precisamente para estos escenarios. Proporciona un mecanismo declarativo para especificar opciones del compilador por componente directamente dentro de tus archivos .svelte, sobreescribiendo cualquier configuración global que hayas definido en tu svelte.config.js o en la configuración de tu bundler. Este control granular se vuelve indispensable a medida que las aplicaciones crecen en complejidad y deben acomodar requisitos diversos en distintos componentes.

A diferencia de los otros elementos especiales de Svelte que afectan principalmente el comportamiento en tiempo de ejecución (como <svelte:window> para enlazar eventos de ventana o <svelte:head> para manipular el <head> del documento), <svelte:options> opera completamente en tiempo de compilación. Las opciones que especifiques influyen en cómo el compilador de Svelte transforma el código fuente de tu componente en JavaScript, pero no dejan ningún rastro en la salida final en tiempo de ejecución. Esta distinción es crucial para entender cuándo y cómo aprovechar este poderoso elemento.

Anatomía del Elemento `<svelte:options>`

El elemento <svelte:options> usa una sintaxis basada en atributos sencilla para la configuración:

<svelte:options option={value} />

Este elemento de cierre automático debe aparecer en el nivel superior de tu archivo de componente—no puede estar anidado dentro de otros elementos o bloques de control de flujo. Si bien no hay un requisito estricto sobre su posición relativa a las etiquetas <script> o <style>, la práctica convencional de colocarlo al inicio del archivo (antes de la etiqueta script) mejora la visibilidad y hace que los requisitos especiales de compilación del componente sean inmediatamente evidentes para cualquiera que lea el código.

Importante: El contenido dentro de <svelte:options> está prohibido. A diferencia de otros elementos, no puedes colocar ningún contenido entre las etiquetas de apertura y cierre—utiliza siempre la forma de cierre automático.

El elemento acepta varios atributos, cada uno controlando un aspecto diferente de la compilación:

runes={true} — fuerza un componente al modo runes
runes={false} — fuerza un componente al modo legacy
namespace="..." — el namespace donde se usará este componente: "html" (por defecto), "svg", o "mathml"
customElement={...} — opciones para compilar como custom element (string para el nombre de etiqueta, u objeto para configuración detallada)
css="injected" — inyecta estilos en línea en lugar de extraerlos

Examinemos cada opción en profundidad, entendiendo no solo qué hace sino por qué y cuándo querrías usarla.

Controlando el Modo Runes: Garantizando un Comportamiento Predecible

La opción runes te da control explícito sobre qué sistema de reactividad usa un componente:

<svelte:options runes={true} />

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

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

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

Cuando estableces runes={true}, le indicas al compilador que analice y transforme este componente usando el sistema de runes de Svelte 5, independientemente de la configuración global de tu proyecto.

El Comportamiento de Inferencia por Defecto

Cuando omites la opción runes por completo, el compilador emplea una inferencia inteligente. Examina el código fuente de tu componente en busca de señales evidentes de uso de runes—$state, $derived, $effect, $props y construcciones similares. Si encuentra alguna declaración de rune, compila el componente en modo runes; de lo contrario, recurre al modo legacy. Esta detección automática funciona notablemente bien para la mayoría de los escenarios, pero ocasionalmente puede producir resultados sorprendentes cuando un componente es ambiguo.

Nota Crítica para Autores de Librerías: Establecer runes: true en tu svelte.config.js fuerza el modo runes para todo tu proyecto, incluyendo los componentes en node_modules. Esto puede romper librerías de terceros. En su lugar, establece explícitamente <svelte:options runes={true} /> en cada uno de tus componentes de librería para asegurarte de que se comporten de manera consistente independientemente de cómo estén configuradas las aplicaciones que los consumen.

Configuración de Namespace: Más Allá del HTML

Si bien la mayoría de los componentes Svelte renderizan elementos HTML, el framework también admite contenido SVG y MathML. La opción namespace le indica al compilador qué namespace XML rige el marcado del componente, afectando cómo se analizan y validan los elementos.

Trabajando con Componentes SVG

SVG (Scalable Vector Graphics) opera bajo reglas diferentes a las de HTML. Los nombres de elementos distinguen mayúsculas de minúsculas, ciertos atributos usan convenciones de nomenclatura diferentes (como viewBox en lugar de viewbox), y la API del DOM para crear elementos difiere. Al construir un componente que renderiza contenido SVG puro, debes declarar el namespace explícitamente:

<svelte:options namespace="svg" />

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

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

Sin la declaración del namespace, el compilador podría malinterpretar ciertos elementos o generar código de manipulación del DOM incorrecto. Por ejemplo, los elementos SVG deben crearse usando document.createElementNS() con el URI del namespace SVG en lugar de document.createElement().

Componentes de Fragmento SVG Puro

Al crear componentes SVG reutilizables que se compondrán dentro de un elemento <svg> padre, puedes crear componentes que rendericen fragmentos SVG sin su propia etiqueta <svg> raíz:

<svelte:options namespace="svg" />

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

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

Este componente puede luego componerse dentro de un SVG padre:

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

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

Soporte para MathML

Para notación matemática, Svelte admite el namespace MathML:

<svelte:options namespace="mathml" />

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

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

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

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

Los componentes MathML son menos comunes pero invaluables para aplicaciones educativas, documentación científica, o cualquier contexto que requiera una composición tipográfica matemática adecuada que el CSS por sí solo no puede lograr.

Estrategia de Inyección de CSS: La Opción `css="injected"`

Svelte típicamente extrae los estilos de los componentes en archivos CSS separados durante la compilación—tu bundler luego se encarga de combinar y cargar estos estilos. Sin embargo, ciertos escenarios se benefician de un enfoque diferente donde los estilos se incrustan directamente en el bundle de JavaScript y se inyectan en tiempo de ejecución.

<svelte:options css="injected" />

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

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

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

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

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

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

Cómo Funciona el CSS Inyectado

Con css="injected", el comportamiento difiere entre el renderizado del lado del servidor y el renderizado del lado del cliente:

Durante SSR: Los estilos del componente se renderizan como una etiqueta <style> en la sección <head> del documento, asegurando que los estilos estén disponibles inmediatamente cuando se analiza el HTML.

Durante CSR: Los estilos se incluyen en el bundle de JavaScript y se inyectan en el documento de forma dinámica cuando el componente se monta. Svelte es suficientemente inteligente para verificar si los estilos ya han sido inyectados (evitando bloques de estilos duplicados cuando existen múltiples instancias del mismo componente).

Cuándo Usar CSS Inyectado

Esta opción resulta particularmente útil en varios escenarios:

Librerías de Componentes: Al distribuir una librería de componentes, el CSS inyectado significa que los consumidores no necesitan configurar sus herramientas de build para manejar tu CSS. Los estilos "simplemente funcionan" cuando importan tu componente.

Componentes Cargados Dinámicamente: Para componentes con code-splitting cargados bajo demanda, el CSS inyectado garantiza que los estilos lleguen junto con el código del componente en lugar de requerir que se cargue un chunk CSS separado.

Arquitecturas de Micro-Frontend: Al incrustar componentes Svelte en aplicaciones más grandes construidas con diferentes frameworks, el CSS inyectado elimina los desafíos de coordinación en torno a la carga de estilos.

Custom Elements: Al compilar componentes como web components (custom elements), css="injected" se habilita automáticamente ya que los estilos deben inyectarse en el shadow DOM.

Consideraciones sobre las Compensaciones

El CSS inyectado no es universalmente superior. Considera estas implicaciones:

Tamaño del Bundle: Los estilos se convierten en parte de tu bundle de JavaScript, aumentando su tamaño. Para aplicaciones grandes, el CSS extraído que puede cachearse por separado suele tener mejor rendimiento.

Flash of Unstyled Content (FOUC): En escenarios de renderizado solo en cliente, puede haber un breve momento en que el contenido aparezca antes de que se inyecten los estilos. El SSR mitiga esta preocupación.

Eficiencia del Caché: Los archivos CSS extraídos pueden cachearse independientemente del JavaScript, lo que potencialmente mejora el rendimiento en visitas repetidas.

Construyendo Custom Elements: Web Components con Svelte

Quizás el uso más poderoso y complejo de <svelte:options> es compilar componentes Svelte como custom elements (web components). Esta capacidad te permite crear elementos de UI reutilizables que funcionan en cualquier lugar—aplicaciones JavaScript vanilla, proyectos React, bases de código Vue, o incluso páginas HTML estáticas.

Creación Básica de Custom Elements

La forma más simple usa un valor de tipo string para la opción customElement:

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

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

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

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

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

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

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

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

Cuando este componente se compila con la opción del compilador customElement: true, produce un custom element que puede usarse en cualquier contexto HTML:

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

Definición Diferida de la Etiqueta

Puedes omitir el nombre de etiqueta para cualquiera de tus componentes internos que no desees exponer y usarlos como componentes Svelte regulares. Los consumidores del componente aún pueden asignarle un nombre después si es necesario, usando la propiedad estática element que contiene el constructor del custom element:

import MyElement from './MyElement.svelte'

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

Este patrón es útil al construir librerías de componentes donde el usuario final debe elegir los nombres de etiqueta.

Configuración Avanzada de Custom Elements

Para casos de uso sofisticados, la opción customElement acepta un objeto con amplias capacidades de configuración:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	tr.selected {
		background: #eff6ff;
	}

	tr:hover {
		background: #f8fafc;
	}

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

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

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

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

Analicemos cada opción de configuración:

tag: El nombre de etiqueta HTML para tu custom element. Debe contener un guion según la especificación de Web Components (ej., my-component, app-header, user-profile). Si se omite, puedes definir la etiqueta de forma programática más adelante.

shadow: Controla la creación del shadow DOM. Las opciones son 'open' (por defecto, permite que JavaScript externo acceda al shadow root) o 'none' (sin shadow DOM, los estilos no están encapsulados). El shadow DOM proporciona aislamiento de estilos pero impide que el CSS externo aplique estilos a los elementos internos.

props: Configuración detallada para cada propiedad, incluyendo:

type: Cómo analizar los valores de atributos ('String', 'Boolean', 'Number', 'Array', 'Object'). Es crítico porque los atributos HTML siempre son strings.
attribute: Mapeo personalizado del nombre del atributo. Svelte convierte camelCase a kebab-case por defecto, pero puedes sobreescribir esto.
reflect: Si los cambios en la propiedad deben actualizar el atributo correspondiente. Útil para selectores de atributos CSS y depuración.

La Opción `extend`: Personalización Profunda de Elementos Personalizados

La opción extend proporciona la máxima flexibilidad al permitirte mejorar o personalizar completamente la clase del elemento personalizado generado. Esto es particularmente poderoso para la integración con formularios HTML usando la API ElementInternals:

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

				// Store reference to internals for form integration
				#internals

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

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

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

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

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

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

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

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

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

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

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

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

	function validate() {
		if (!inputElement) return

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

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

		errorMessage = message

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

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

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

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

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

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

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

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

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

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

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

Este elemento personalizado extendido participa en formularios HTML igual que los controles de formulario nativos, habilitando características como el envío de formularios, la validación y la pseudo-clase CSS :invalid.

Comprendiendo los Matices del Ciclo de Vida de los Elementos Personalizados

Los elementos personalizados siguen su propio modelo de ciclo de vida que difiere sutilmente de los componentes Svelte estándar. Comprender estos matices previene bugs confusos:

Creación Diferida del Componente

Cuando se instancia un elemento personalizado, el componente Svelte interno no se crea de inmediato. La creación ocurre en el siguiente tick después de que se dispara connectedCallback (es decir, después de que el elemento se adjunta al DOM). Esto significa:

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

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

Las propiedades establecidas antes de la inserción al DOM se preservan y se aplican cuando el componente finalmente se monta, pero los métodos exportados no están disponibles hasta entonces. Si necesitas invocar funciones antes de la creación del componente, puedes solucionarlo usando la opción extend para agregar los métodos directamente a la clase del elemento personalizado.

Movimientos en el DOM y Desconexión Temporal

Si un elemento personalizado es removido temporalmente del DOM y vuelto a adjuntar (algo común durante ciertas operaciones del DOM), el componente Svelte interno sobrevive. La destrucción solo ocurre en el siguiente tick después de que se dispara disconnectedCallback, dando tiempo para que las operaciones de movimiento síncronas se completen sin destruir el componente.

Actualizaciones en Lote del Shadow DOM

Las actualizaciones al shadow DOM se agrupan en lotes y se aplican en el siguiente tick, no de forma síncrona. Esto previene re-renderizados excesivos, pero significa que no puedes inspeccionar el DOM actualizado inmediatamente después de cambiar una propiedad:

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

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

Problemas del Mundo Real y Sus Soluciones

2. Construyendo un Sistema de Diseño Agnóstico a Frameworks

Escenario: Tu empresa utiliza múltiples frameworks frontend en diferentes equipos—React para la aplicación principal, Vue para herramientas internas y JavaScript puro para sistemas legacy. Necesitas construir un sistema de diseño unificado que funcione en todas partes.

Solución: Librería de Elementos Personalizados con Svelte

Crea una librería de componentes que compile a elementos personalizados.

!!! Nota Importante sobre Slots en Elementos Personalizados !!!

Al compilar componentes Svelte como elementos personalizados, debes usar el elemento HTML nativo <slot> en lugar de la sintaxis de snippets de Svelte 5 ({@render children()}). Esto se debe a que los elementos personalizados operan en el shadow DOM nativo del navegador, que utiliza el mecanismo de slots estándar de Web Components. El elemento <slot> en elementos personalizados se comporta de manera diferente a los componentes Svelte regulares—el contenido con slot se renderiza de forma ansiosa (inmediatamente) en lugar de de forma perezosa.

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

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

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

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

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

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

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

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

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

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

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

Uso en diferentes frameworks:

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

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

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

Punto clave: Usa propiedades personalizadas de CSS (como --ds-primary) para la tematización, permitiendo que cada aplicación consumidora personalice los colores sin modificar el código del componente.

2. El Contenido de Slots se Renderiza de Forma Ansiosa en Elementos Personalizados

Escenario: Tienes un componente de pestañas donde el contenido de cada pestaña debería renderizarse solo cuando esa pestaña está activa. Pero con elementos personalizados, todo el contenido con slot se renderiza inmediatamente sin importar los bloques {#if}.

Comprendiendo el Problema: En Svelte estándar, el contenido con slot se renderiza de forma perezosa—se crea solo cuando el slot se renderiza efectivamente. En elementos personalizados (DOM), el contenido con slot se renderiza de forma ansiosa. Incluir un <slot> dentro de un bloque {#if ...} no evita que el contenido sea creado.

Solución: Slots con Nombre y Control de Visualización

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

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

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

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

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

Solución Alternativa: Si necesitas un renderizado verdaderamente perezoso, usa props de callback o carga dinámica de contenido en lugar de slots:

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

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

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

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

3. Los Elementos Personalizados No Funcionan con SSR

Escenario: Tu aplicación SvelteKit usa elementos personalizados, pero aparecen como cajas vacías durante el renderizado en el servidor antes de que cargue JavaScript.

Comprendiendo el Problema: Los elementos personalizados generalmente no son adecuados para el renderizado en el servidor porque el shadow DOM es invisible hasta que JavaScript carga. El navegador no sabe cómo renderizar la estructura interna del componente sin la definición de JavaScript.

Solución 1: Patrón de Mejora Progresiva

Diseña tus elementos personalizados para mostrar contenido significativo incluso antes de que JavaScript cargue:

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

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

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

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

Uso con contenido de respaldo:

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

Solución 2: Arquitectura con Conciencia de Hidratación

Mantén los elementos personalizados para widgets verdaderamente interactivos y usa componentes Svelte regulares para el contenido crítico de SSR:

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

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

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

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

4. Aplicando Estilos a Elementos Personalizados desde Afuera

Escenario: Estás usando un componente de elemento personalizado, pero necesitas aplicar estilos globales o personalizaciones de tema desde la aplicación padre.

Comprendiendo el Problema: El shadow DOM proporciona encapsulación de estilos—los estilos externos no pueden penetrar el límite del shadow. Esto generalmente es deseable, pero puede ser frustrante cuando necesitas tematización.

Solución 1: Propiedades Personalizadas de CSS (Recomendada)

Las propiedades personalizadas de CSS atraviesan el shadow DOM:

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

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

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

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

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

Tematización externa:

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

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

Solución 2: Deshabilitar el Shadow DOM

Para componentes que necesitan control total de estilos externos:

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

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

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

Compensación: Sin shadow DOM, pierdes la encapsulación de estilos. Los estilos de tu componente podrían entrar en conflicto con los estilos de la aplicación padre, y viceversa.

Solución 3: Estilos Basados en Parts

Usa el pseudo-elemento CSS ::part() para estilos externos selectivos:

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

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

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

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

Estilos externos con ::part():

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

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

5. El Contexto No Funciona a Través de los Límites de Elementos Personalizados

Escenario: Estás usando la API de contexto de Svelte (setContext/getContext) en tu aplicación, pero no funciona al cruzar los límites de los elementos personalizados.

Comprendiendo el Problema: La característica de contexto de Svelte funciona entre componentes Svelte regulares dentro de un elemento personalizado, pero no puedes usar el contexto a través de elementos personalizados. Establecer el contexto en un elemento personalizado padre no será accesible mediante getContext en un elemento personalizado hijo.

Solución 1: Eventos Personalizados para la Comunicación

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

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

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

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

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

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

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

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

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

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

Solución 2: Estado Compartido a través de Window o Módulo

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

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

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

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

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

6. Sistema de Íconos SVG con Colores Dinámicos

Escenario: Estás construyendo un sistema de íconos donde los íconos necesitan heredar colores de su contexto y soportar múltiples personalizaciones de color.

Solución: Componentes SVG con currentColor

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

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

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

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

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

Uso con colores heredados:

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

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

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

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

7. Componentes de Librería que se Comportan Diferente Según la Configuración del Consumidor

Escenario: Estás publicando una librería de componentes Svelte, pero los componentes se comportan de manera impredecible dependiendo de si el proyecto consumidor usa runes: true de forma global.

Solución: Declaración Explícita de Modo

Siempre declara el modo runes explícitamente en los componentes de la librería:

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

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

	let selectedIndex = $state(-1)

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

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

Consejo de documentación: Incluye en el README de tu librería:

## Compatibility

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

8. Incorporación de Widgets Svelte en Aplicaciones que No Usan Svelte

Escenario: Necesitas incorporar un widget complejo basado en Svelte (como un widget de chat o un panel de análisis) en sitios web construidos con diversas tecnologías—WordPress, HTML estático u otros frameworks.

Solución: Widget Autocontenido con Auto-Registro

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Incorporación en cualquier sitio web:

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

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

Buenas Prácticas y Errores Comunes

Ubicación y Visibilidad

Siempre coloca <svelte:options> al inicio de tu archivo de componente, antes de las etiquetas <script>:

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

<script>
	// Component logic
</script>

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

<svelte:options runes={true} />

Aunque técnicamente es válido en cualquier lugar del nivel superior, colocarlo al inicio hace que la configuración del compilador sea inmediatamente evidente.

Declaración Explícita de Props para Elementos Personalizados

Al crear elementos personalizados, debes desestructurar explícitamente las props en lugar de usar $props() sin desestructurar. El compilador necesita saber qué propiedades exponer en el elemento DOM:

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

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

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

Evitar Conflictos de Nombres de Propiedades

No nombres las propiedades de elementos personalizados comenzando con on—Svelte las interpreta como escuchadores de eventos:

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

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

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

Esto significa que <custom-element oneworld={true}> se trata como customElement.addEventListener('eworld', true), no como customElement.oneworld = true.

Preservación de Slots en Shadow Roots Declarativos

Al usar <template shadowrootmode="..."> para shadow DOM declarativo, Svelte 5 preserva los elementos <slot /> como slots DOM reales en lugar de transformarlos:

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

Combinación de Opciones para Escenarios Complejos

Las opciones pueden combinarse para requisitos sofisticados:

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

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

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

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

<style>
	svg {
		overflow: visible;
	}

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

	circle {
		transition: r 0.2s;
	}

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

Esto crea un elemento personalizado que renderiza un gráfico SVG, usa la reactividad moderna de runes y expone correctamente propiedades tipadas.

Pruebas de Elementos Personalizados

Al probar elementos personalizados, recuerda el comportamiento de montaje diferido:

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

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

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

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

		// Cleanup
		element.remove()
	})

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

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

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

Depuración de Elementos Personalizados

Usa las DevTools del navegador para inspeccionar los shadow roots de los elementos personalizados:

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

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

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

Referencia de Opciones Deprecadas

Svelte 5 depreca varias opciones que no son funcionales en el modo runes:

La Opción `immutable` (Deprecada)

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

Esta opción le indicaba al compilador que podía usar verificaciones de igualdad por referencia (===) en lugar de comparaciones profundas para la detección de cambios. En el modo runes, el sistema de reactividad de grano fino hace que esta optimización sea irrelevante—el compilador rastrea exactamente qué propiedades son accedidas y actualizadas.

La Opción `accessors` (Deprecada)

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

Esto generaba pares getter/setter para las props del componente, permitiendo que código externo lea y escriba props de manera programática. El modo runes maneja el acceso a propiedades de forma diferente. Para elementos personalizados, el acceso a propiedades se maneja automáticamente a través de las definiciones de propiedades del elemento personalizado.

Referencia Rápida

Cuándo Usar Cada Opción

Opción	Usar Cuando
`runes={true}`	Publicar librerías que necesitan un comportamiento consistente independientemente de la configuración del consumidor
`runes={false}`	Mantener componentes que usan intencionalmente patrones heredados
`namespace="svg"`	Construir componentes SVG puros o sistemas de íconos
`namespace="mathml"`	Crear componentes de notación matemática
`css="injected"`	Distribuir componentes independientes, construir widgets o compilar elementos personalizados
`customElement="tag-name"`	Crear web components agnósticos al framework
`customElement={{ ... }}`	Configuración avanzada de elementos personalizados con tipado de props, control del Shadow DOM o integración con formularios

Conclusión

El elemento <svelte:options> proporciona un control preciso sobre cómo se compilan los componentes individuales, habilitando escenarios que de otro modo requerirían reestructurar toda la configuración del build o abandonar por completo el modelo de compilación de Svelte. Esta configurabilidad a nivel de componente es especialmente valiosa al construir librerías, mantener bases de código heredadas durante una migración, o crear web components agnósticos al framework que necesitan integrarse con entornos diversos.

Dominar <svelte:options> significa entender no solo la sintaxis de cada opción, sino las decisiones estratégicas detrás de cuándo usarlas. La opción runes garantiza que los componentes de librería se comporten de manera predecible independientemente de las configuraciones de las aplicaciones consumidoras. La opción namespace es esencial para los componentes SVG y MathML, reconociendo que no todo el contenido es HTML. La opción css="injected" simplifica los escenarios de distribución y carga dinámica, aunque con compensaciones que vale la pena entender. La configuración de customElement desbloquea Svelte para construir web components verdaderamente portables con tipado sofisticado de props, control del Shadow DOM e interoperabilidad con frameworks.

Con <svelte:options> en tu conjunto de herramientas, puedes construir aplicaciones Svelte que manejen con elegancia requisitos diversos—desde componentes basados en runes de última generación hasta web components portables que se pueden desplegar en cualquier lugar donde se ejecuten navegadores modernos. La clave está en entender no solo qué hace cada opción, sino cuándo utilizarla y qué implicaciones arquitectónicas conlleva.

Puntos Clave

<svelte:options> configura el comportamiento del compilador por componente sobrescribiendo los valores predeterminados a nivel de proyecto para el modo runes, el namespace, la inyección de CSS, los elementos personalizados, la inmutabilidad y las advertencias de accesibilidad
La opción runes={true/false} habilita el control explícito del modo permitiendo componentes heredados en proyectos con runes u optando componentes específicos fuera de runes en bases de código en transición
La opción namespace es crítica para SVG y MathML - usa namespace="svg" para componentes SVG o namespace="mathml" para notación matemática y asegurar la creación correcta de elementos
La opción css="injected" empaqueta los estilos en JavaScript habilitando la carga dinámica de componentes sin archivos CSS separados, ideal para code-splitting y web components, pero aumentando el tamaño del bundle de JS
La configuración de elementos personalizados mediante el objeto customElement transforma los componentes Svelte en web components agnósticos al framework con nombres de etiqueta, opciones de Shadow DOM y mapeos de props/eventos
Shadow DOM "open" vs "none" intercambia encapsulación - el modo open aísla los estilos pero bloquea el CSS global, mientras que el modo none habilita el estilizado pero pierde la encapsulación
Los props con conocimiento de tipos requieren interfaces TypeScript en las declaraciones svelte:options tag="...">, usando SvelteComponent.element para la extensión correcta de HTMLElement
Los elementos personalizados tienen limitaciones de ciclo de vida y contexto - sin soporte SSR, árboles de contexto separados de las aplicaciones Svelte padre, y la renderización del contenido de slots requiere entender la mecánica de proyección

Ver También

Documentación Oficial de Svelte 5 - <svelte:options>
Especificación de Web Components - API de elementos personalizados nativa del navegador
Shadow DOM - Comprender la encapsulación de estilos y la proyección de slots
Custom Elements Everywhere - Pruebas de compatibilidad con frameworks para web components
Documentación de Svelte Runes - Comprender el nuevo modelo de reactividad
SVG en HTML - Manejo de namespaces para contenido SVG
MathML Core - Notación matemática en navegadores web
Cascada e Herencia CSS - Cómo el Shadow DOM afecta el estilizado
Genéricos de TypeScript - Props de elementos personalizados con tipos seguros