Script Modules: Más allá de las instancias de componentes

Cada componente Svelte que has escrito hasta ahora tiene un script de instancia—el bloque <script> que se ejecuta para cada instancia del componente. Pero ¿qué pasa si necesitas código que se ejecute una sola vez para todo el tipo de componente, no por instancia? ¿Qué pasa si quieres compartir estado o utilidades entre todas las instancias de un componente?

Aquí entran los script modules—el mecanismo de Svelte para compartir código a nivel de componente. En Svelte 5, la sintaxis evolucionó de <script context="module"> al más limpio <script module>, pero el concepto sigue siendo poderoso: código que se ejecuta una vez cuando el módulo del componente carga, compartido entre todas las instancias.

Este tutorial explora los script modules de forma exhaustiva: su sintaxis, casos de uso, limitaciones y cómo se integran con el sistema reactivo de Svelte 5.

Capítulo 1: Entendiendo los Script Modules

1.1 Scripts de instancia vs. scripts de módulo

Scripts de instancia (<script>):

Se ejecutan una vez por instancia del componente
Tienen acceso a props, estado y ciclo de vida
Pueden ser reactivos con runes como $state, $derived, $effect

Scripts de módulo (<script module>):

Se ejecutan una vez cuando el módulo del componente se carga por primera vez
Son compartidos entre todas las instancias del componente
No pueden acceder a datos específicos de la instancia (props, estado)
Se ejecutan en el alcance del módulo, no en el alcance del componente

<!-- Component.svelte -->
<script module>
	// This runs once for the entire component type
	console.log('Component module loaded')

	// Shared across all instances
	let instanceCount = 0

	export function getInstanceCount() {
		return instanceCount
	}
</script>

<script>
	// This runs for each component instance
	console.log('New instance created')

	// Access module-level function
	const count = getInstanceCount()
</script>

1.2 El modelo de ejecución

Los scripts de módulo se ejecutan durante la fase de carga del módulo, antes de que se creen instancias del componente:

<!-- Logger.svelte -->
<script module>
	// ✅ Runs immediately when module loads
	console.log('Logger module initialized')

	// Module-level state
	let logHistory = []

	export function log(message) {
		logHistory.push({ message, timestamp: Date.now() })
		console.log(`[${new Date().toISOString()}] ${message}`)
	}

	export function getLogHistory() {
		return [...logHistory]
	}
</script>

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

	// Use module function
	log(`${componentName} component mounted`)
</script>

1.3 Reglas de acceso y ciclo de vida SSR

Módulo → Instancia: Las declaraciones en el script de módulo están disponibles para el script de instancia y el marcado porque comparten el mismo alcance de módulo compilado. No son reactivas al estado de la instancia—trátalas como variables regulares a nivel de módulo.
Instancia → Módulo: Los scripts de módulo no pueden ver valores exclusivos de la instancia (props, runes) porque esos se crean por instancia.
Consideraciones del servidor: En SSR con SvelteKit, el estado del módulo se comparte entre solicitudes a menos que lo aisles explícitamente (por ejemplo, creando estado fresco dentro de un módulo con alcance de solicitud). Evita almacenar datos por solicitud en el alcance del módulo.
Guardias de entorno: Los scripts de módulo se ejecutan dondequiera que cargue el módulo del componente. Usa import { browser } from '$app/environment' (SvelteKit) o verificaciones de características antes de acceder a window/document.

Capítulo 2: Casos de uso comunes para los Script Modules

2.1 Utilidades y constantes compartidas

Los scripts de módulo destacan para proveer utilidades que no necesitan estado por instancia:

<!-- DateUtils.svelte -->
<script module>
	// Constants shared across instances
	export const DATE_FORMATS = {
		SHORT: 'MM/dd/yyyy',
		LONG: 'MMMM dd, yyyy',
		ISO: 'yyyy-MM-dd'
	}

	// Utility functions
	export function formatDate(date, format = DATE_FORMATS.SHORT) {
		// Implementation...
		return new Intl.DateTimeFormat('en-US').format(date)
	}

	export function isWeekend(date) {
		const day = date.getDay()
		return day === 0 || day === 6
	}

	export function addDays(date, days) {
		const result = new Date(date)
		result.setDate(result.getDate() + days)
		return result
	}
</script>

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

	// Use shared utilities
	$: formatted = formatDate(date)
	$: isWeekendDay = isWeekend(date)
</script>

2.2 Seguimiento de instancias y analíticas

Rastrea el uso de componentes en toda tu aplicación:

<!-- Button.svelte -->
<script module>
	let clickCount = 0
	let instances = new Set()

	export function recordClick(componentId) {
		clickCount++
		console.log(`Button clicked (total: ${clickCount})`)
	}

	export function registerInstance(id) {
		instances.add(id)
	}

	export function unregisterInstance(id) {
		instances.delete(id)
	}

	export function getStats() {
		return {
			totalClicks: clickCount,
			activeInstances: instances.size
		}
	}
</script>

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

	// Register this instance
	$effect(() => {
		registerInstance(id)
		return () => unregisterInstance(id)
	})

	function handleClick() {
		recordClick(id)
		// ... other click logic
	}
</script>

<button onclick={handleClick} {...props}>
	{@render children?.()}
</button>

2.3 Gestión de estado global del componente

Para estado global específico del componente que no pertenece a un store:

<!-- ThemeProvider.svelte -->
<script module>
	// Global theme state for all ThemeProvider instances
	let currentTheme = 'light'
	let subscribers = new Set()

	export function setTheme(theme) {
		currentTheme = theme
		// Notify all subscribers
		subscribers.forEach((callback) => callback(theme))
	}

	export function getTheme() {
		return currentTheme
	}

	export function subscribeToTheme(callback) {
		subscribers.add(callback)
		return () => subscribers.delete(callback)
	}
</script>

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

	// Subscribe to theme changes
	$effect(() => {
		const unsubscribe = subscribeToTheme((theme) => {
			// Update component state
			document.documentElement.setAttribute('data-theme', theme)
		})

		return unsubscribe
	})
</script>

<div class="theme-provider">
	{@render children?.()}
</div>

2.4 Patrón de registro de componentes

Crea sistemas de componentes descubribles:

<!-- ComponentRegistry.svelte -->
<script module>
	const registry = new Map()

	export function registerComponent(name, component) {
		registry.set(name, component)
		console.log(`Registered component: ${name}`)
	}

	export function getComponent(name) {
		return registry.get(name)
	}

	export function getAllComponents() {
		return Array.from(registry.entries())
	}

	export function unregisterComponent(name) {
		return registry.delete(name)
	}
</script>

<!-- Usage in other components -->
<script>
	import ComponentRegistry from './ComponentRegistry.svelte'

	// Register this component
	$effect(() => {
		ComponentRegistry.registerComponent('MyComponent', MyComponent)
		return () => ComponentRegistry.unregisterComponent('MyComponent')
	})
</script>

Capítulo 3: Exportando snippets desde scripts de módulo

Svelte 5.5.0 introdujo la capacidad de exportar snippets desde scripts de módulo, habilitando patrones poderosos de composición de componentes.

3.1 Exportación básica de snippet

<!-- FormSnippets.svelte -->
<script module>
	export { inputField, selectField, checkboxField }
</script>

{#snippet inputField(label, value, type = 'text', ...attrs)}
	<div class="form-field">
		<label>{label}</label>
		<input {type} bind:value {...attrs} />
	</div>
{/snippet}

{#snippet selectField(label, value, options, ...attrs)}
	<div class="form-field">
		<label>{label}</label>
		<select bind:value {...attrs}>
			{#each options as option}
				<option value={option.value}>{option.label}</option>
			{/each}
		</select>
	</div>
{/snippet}

{#snippet checkboxField(label, checked, ...attrs)}
	<div class="form-field">
		<label>
			<input type="checkbox" bind:checked {...attrs} />
			{label}
		</label>
	</div>
{/snippet}

3.2 Usando snippets exportados

<!-- ContactForm.svelte -->
<script>
	import { inputField, selectField, checkboxField } from './FormSnippets.svelte'

	let formData = $state({
		name: '',
		email: '',
		country: '',
		newsletter: false
	})

	const countries = [
		{ value: 'us', label: 'United States' },
		{ value: 'ca', label: 'Canada' },
		{ value: 'uk', label: 'United Kingdom' }
	]
</script>

<form>
	{@render inputField('Name', formData.name, 'text', { required: true })}
	{@render inputField('Email', formData.email, 'email', { required: true })}
	{@render selectField('Country', formData.country, countries)}
	{@render checkboxField('Subscribe to newsletter', formData.newsletter)}
</form>

3.3 Limitaciones de los snippets exportados

Los snippets exportados tienen reglas de alcance estrictas:

<!-- ❌ This will NOT work -->
<script>
	let instanceVar = "can't access this";
</script>

<script module>
	export { brokenSnippet };
</script>

{#snippet brokenSnippet()}
	<!-- Error: Cannot access instance variables -->
	<p>{instanceVar}</p>
{/snippet}

<!-- ✅ This WILL work -->
<script module>
	const MODULE_CONSTANT = "this is fine";
	export { workingSnippet };
</script>

{#snippet workingSnippet()}
	<p>{MODULE_CONSTANT}</p>
{/snippet}

Capítulo 4: Patrones avanzados y buenas prácticas

4.1 Estado reactivo a nivel de módulo

Aunque los scripts de módulo no pueden usar runes directamente, puedes crear patrones reactivos:

<!-- ReactiveModule.svelte -->
<script module>
	// Module-level reactive state using custom events
	let _value = 'initial'
	const listeners = new Set()

	export function getValue() {
		return _value
	}

	export function setValue(newValue) {
		_value = newValue
		// Notify listeners
		listeners.forEach((listener) => listener(newValue))
	}

	export function subscribe(listener) {
		listeners.add(listener)
		return () => listeners.delete(listener)
	}
</script>

<script>
	let localValue = $state('')

	// Subscribe to module changes
	$effect(() => {
		const unsubscribe = subscribe((newValue) => {
			localValue = newValue
		})
		return unsubscribe
	})
</script>

4.2 Combinando scripts de módulo con stores

Para estado compartido complejo, combina scripts de módulo con stores de Svelte:

<!-- UserPreferences.svelte -->
<script module>
	import { writable } from 'svelte/store'

	// Module-level store
	export const userPreferences = writable({
		theme: 'light',
		language: 'en',
		notifications: true
	})

	// Utility functions
	export function updatePreference(key, value) {
		userPreferences.update((prefs) => ({ ...prefs, [key]: value }))
	}

	export function resetPreferences() {
		userPreferences.set({
			theme: 'light',
			language: 'en',
			notifications: true
		})
	}
</script>

<script>
	import { userPreferences } from './UserPreferences.svelte'

	// Use in component
	let prefs = $state()
	userPreferences.subscribe((value) => (prefs = value))
</script>

4.3 Probando scripts de módulo

Los scripts de módulo pueden ser difíciles de probar debido a su naturaleza compartida:

// ModuleScript.test.js
import { getInstanceCount, recordClick } from './Button.svelte'

// Reset module state between tests
beforeEach(() => {
	// If your module exposes reset functions, use them
	// Otherwise, you may need to re-import or use a different strategy
})

// Test module functions
test('tracks clicks across instances', () => {
	expect(getInstanceCount()).toBe(0)
	recordClick('test-id')
	expect(getInstanceCount()).toBe(1)
})

Capítulo 5: Migración desde Svelte 4

5.1 Cambios de sintaxis

<!-- Svelte 4 -->
<script context="module">
	export const sharedValue = 'hello';
</script>

<!-- Svelte 5 -->
<script module>
	export const sharedValue = 'hello';
</script>

5.2 Cambios de comportamiento

Los scripts de módulo ahora se ejecutan en modo estricto
Mejor soporte para tree-shaking
Mensajes de error mejorados
Capacidad de exportar snippets (nueva en 5.5.0)

Conclusión: Cuándo usar module scripts

Los module scripts son poderosos pero deben usarse con criterio:

Usa module scripts para:

Utilidades y constantes compartidas
Analíticas y seguimiento de componentes
Estado global de componentes
Librerías de snippets
Registros de componentes

No uses module scripts para:

Lógica específica de instancia
Estado reactivo que varía por componente
Efectos secundarios que deben ejecutarse por instancia

Dominar los module scripts desbloquea nuevos patrones para la comunicación entre componentes y la organización del código en Svelte 5. Estos cierran la brecha entre las instancias individuales de componentes y las preocupaciones a nivel de aplicación, haciendo que tus componentes sean más componibles y mantenibles.